Factsets endpoint

• query: optional. A JSON array containing the query in prefix notation (["<OPERATOR>", "<FIELD>", "<VALUE>"]). See the sections below for the supported operators and fields. For general info about queries, see our guide to query structure.

If a query parameter is not provided, all results will be returned.

See the AST query language page.

• certname (string): the certname associated with the factset.

• environment (string): the environment associated with the fact.

• timestamp (string): the most recent time of fact submission from the associated certname.

• producer_timestamp (string): the most recent time of fact submission for the relevant certname from the Puppet Server.

• producer (string): the certname of the Puppet Server that sent the factset to PuppetDB.

• hash (string): a hash of the factset's certname, environment, timestamp, facts, and producer_timestamp.

The following list contains related entities that can be used to constrain the result set using implicit subqueries. For more information, consult the documentation for subqueries.

• environments: the environment a factset was received from.

• producers: the Puppet Server that sent the factset to PuppetDB.

Successful responses will be in application/json. Errors will be returned as a non-JSON string.

The result will be a JSON array with one entry per certname. Each entry will be in the form:

{
  "certname": <node name>,
  "environment": <node environment>,
  "timestamp": <time of last fact submission>,
  "producer_timestamp": <time of command submission from Puppet Server>,
  "producer": <Puppet Server certname>
  "facts": <expanded facts>,
  "hash": <sha1 sum of "facts" value>
}

The <expanded facts> object is an expansion of the following form:

{
  "href": <url>,
  "data": [ {
    "name": <string>,
    "value": <any>
  } ... ]
}

Using curl from localhost:

Get the factset for node "example.com":

curl -X GET http://localhost:8080/pdb/query/v4/factsets \
  --data-urlencode 'query=["=", "certname", "example.com"]'

Get all factsets with updated after "2014-07-21T16:13:44.334Z":

curl -X GET http://localhost:8080/pdb/query/v4/factsets \
  --data-urlencode 'query=[">", "timestamp", "2014-07-21T16:13:44.334Z"]

Get all factsets corresponding to nodes with uptime greater than 24 hours:

curl -X GET http://localhost:8080/pdb/query/v4/factsets \
  -d 'query=["in", "certname",
              ["extract", "certname",
                ["select_facts", ["and", ["=", "name", "uptime_hours"],
                                         [">", "value", 24]]]]]'

Which returns:

[ {
  "facts" : {
    "href": "/pdb/query/v4/factsets/desktop.localdomain/facts",
    "data": [
      {
        "name": "blockdevice_sde_vendor",
        "value": "Generic"
      },
      {
        "name": "mtu_wlp5s0",
        "value": 1500
      },
      {
        "name": "processor6",
        "value": "Intel(R) Core(TM) i7-4790 CPU @ 3.60GHz"
      },
      {
        "name": "trusted",
        "value" : {
          "authenticated" : "remote",
          "certname" : "desktop.localdomain",
          "extensions" : { }
        },
      },
      {
        "name": "system_uptime",
        "value": {
          "days" : 5,
          "hours" : 120,
          "seconds" : 433391,
          "uptime" : "5 days"
        },
      },
      ...
    ]
  },
  "producer" : "server.localdomain",
  "producer_timestamp" : "2015-03-06T00:20:14.833Z",
  "timestamp" : "2015-03-06T00:20:14.918Z",
  "environment" : "production",
  "certname" : "desktop.localdomain",
  "hash" : "d118d161990f202e911b6fda09f79d24f3a5d4f4"
} ]

curl 'http://localhost:8080/pdb/query/v4/factsets/kb.local'

{
  "certname" : "kb.local",
  "environment" : "production",
  "facts" : {...},
  "hash" : "93253d31af6d718cf81f5bc028be2a671f23ed78",
  "producer" : "foo.local",
  "producer_timestamp" : "2015-06-04T15:27:56.893Z",
  "timestamp" : "2015-06-04T15:27:56.979Z"
}

curl -X GET http://localhost:8080/pdb/query/v4/factsets/my_fake_hostname

{
  "error" : "No information is known about factset my_fake_hostname"
}

This route is an extension of the facts endpoint. It uses the same parameters, operators, fields, and response format.

If you provide a query parameter, it will specify additional criteria, which will be used to return a subset of the information normally returned by this route.