Note: This endpoint is experimental and is subject to rapid development and change.

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.

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.

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.

Back to top