Root endpoint

The root query endpoint can be used to retrieve any known entities from a single endpoint.

/pdb/query/v4

This will return any known entity based on the required query field. Unlike other endpoints, the entity must be supplied using a query with the from operator or a PQL query string.

Like all other PDB query endpoints, query results from the root query endpoint will be restricted to active nodes by default. To target only inactive nodes, you can specify node_state = 'inactive'; for all both active and inactive, use node_state = 'any'.

URL parameters

  • query: required. Either a PQL query string, or an AST JSON array containing the query in prefix notation (["from", "<ENTITY>", ["<OPERATOR>", "<FIELD>", "<VALUE>"]]). Unlike other endpoints, a query with a from is required to choose the entity for which to query. For general info about queries, see our guide to query structure.

  • timeout: An optional limit on the number of seconds that the query will be allowed to run (e.g. timeout=30). If the limit is reached, the query will be interrupted. At the moment, that will result in either a 500 HTTP response status, or (more likely) a truncated JSON result if the result has begun streaming. Specifying this parameter is strongly encouraged. Lingering queries can consume substantial server resources (particularly on the PostgreSQL server) decreasing performance, for example, and increasing the maximum required storage space. The query timeout configuration settings are also recommended.

  • ast_only: optional. A boolean value. When true, the query response will be the supplied query in AST, either exactly as supplied or translated from PQL. False by default.

  • origin: optional. A string describing the source of the query. It can be anything, and will be reported in the log when PuppetDB is configured to log queries. Note that Puppet intends to use origin names beginning with puppet: for its own queries, so it is recommended that other clients choose something else.

  • explain: optional. The string value analyze. This parameter can be used to tell PuppetDB to return the execution plan of a statement instead of the query results. The execution plan shows how the table(s) referenced by the statement will be scanned, the estimated statement execution cost and the actual run time statistics.

Response format

The response will be in application/json, and will contain a list of JSON object results based on the entity provided in the top-level from query.

Examples

Using curl from localhost:

curl -X GET http://localhost:8080/pdb/query/v4 --data-urlencode 'query=["from","nodes",["=","certname","macbook-pro.local"]]'

[
  {
    "catalog_environment": "production",
    "catalog_timestamp": "2015-11-23T19:25:25.561Z",
    "certname": "macbook-pro.local",
    "deactivated": null,
    "expired": null,
    "facts_environment": "production",
    "facts_timestamp": "2015-11-23T19:25:25.079Z",
    "latest_report_hash": "0b2aa3bbb1deb71a5328c1d934eadbba5f52d733",
    "latest_report_status": "unchanged",
    "latest_report_noop": true,
    "cached_catalog_status": "not_used",
    "report_environment": "production",
    "report_timestamp": "2015-11-23T19:25:23.394Z"
  }
]

The same query can also be executed using PQL:

curl -X GET http://localhost:8080/pdb/query/v4 --data-urlencode 'query=nodes { certname = "macbook-pro.local" }'

[
  {
    "catalog_environment": "production",
    "catalog_timestamp": "2015-11-23T19:25:25.561Z",
    "certname": "macbook-pro.local",
    "deactivated": null,
    "expired": null,
    "facts_environment": "production",
    "facts_timestamp": "2015-11-23T19:25:25.079Z",
    "latest_report_hash": "0b2aa3bbb1deb71a5328c1d934eadbba5f52d733",
    "latest_report_status": "unchanged",
    "latest_report_noop": true,
    "cached_catalog_status": "not_used",
    "report_environment": "production",
    "report_timestamp": "2015-11-23T19:25:23.394Z"
  }
]

Paging

This query endpoint supports paged results via the common PuppetDB paging URL parameters. For more information, see the documentation on paging.