Basics of Query API Version4 in PuppetDB

Elements in query API version4 in PuppetDB

As discussed above, a query is made up of an API URL in such a way that it contains endpoints, paging parameters, and entities which are all written in the English language. 

To make it easier and faster for the database to understand what we are requesting, there are query languages made which are codeless. They use specific English words that are used for specific purposes.

Query language

After the organization's database is designed, the role of query languages emerges. They help in giving instructions to store, receive and modify data in nodes(servers).
The query language is the language that the user uses to request the database for some data or information.
We have all heard about SQL, which is the structured query language. There are other languages like AQL, and data log. 

Just like that, Query API in PuppetDB supports two query languages: 

1.  AST (abstract syntax tree) query language.
It is an URL encoded string with an operator and arguments simultaneously.

2.  Puppet Query Language (PQL) 
It is based on AST query language.
It is a string-based query language designed with PuppetDB and Puppet data in mind. 
All you need to do is learn the operator syntax in order to use this language to Query API in PuppetDB.

Entities and Endpoints 

The entity is the implementation of database tables.
The PuppetDB API provides access to a series of data entities from the Puppet ecosystem.

Credit: Puppet platform.

The entity name is utilized within queries and operators themselves. For example: 

There are 18  different kinds of endpoints, all of which query an entity by making an HTTP request to the /entity endpoint. 
For example: 

Root query endpoint can be used to retrieve any known entities from a single endpoint using URL format as shown below:

(["from", "<ENTITY>"], ["<OPERATOR>", "<FIELD>", "<VALUE>"])

Catalog endpoints will help you query catalogs in the URL format as shown below:

(["from", "<ENTITY>"], ["<OPERATOR>", "<FIELD>", "<VALUE>"])

This will return an array containing catalog for the node mentioned. If a query parameter is not provided, all results will be returned.
There are several other endpoints that use URL parameters to help us access data entities.

Root endpoints

Root endpoints are used to query an entity.

What do we mean by query endpoints?
Query endpoints can be used to retrieve any known entities from databases. 

The root endpoint looks like:  /pdb/query/v4 - returns any known entity. The entity must be supplied using a query with the operator.

Response format - The response will be in application/JSON format and will contain a list of JSON object results based on the entity.

URL parameters - 

• query:  This is essential. Either a PQL query string or an AST JSON array containing the query in prefix notation as shown below:

(["from", "<ENTITY>"], ["<OPERATOR>", "<FIELD>", "<VALUE>"]) 

• ast_only: It is a Boolean value and is optional. When true, the query response will be the supplied query in AST, either exactly as supplied from PQL. False is set by default.
• Origin: This is optional. This is 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. 
• explain: This is optional. The string value is analyzed. This is used to tell PuppetDB to return the execution plan of a statement instead of the query results.

Query endpoints are also very useful for paging via the Query API in PuppetDB. 

Paging

Paging is the management of data stored and retrieved from secondary storage to primary storage of servers. For paging, a set of HTTP URL parameters supported by PuppetDB's query endpoints can be used. The platform also supports paging via Query operators.

Some of the URL parameters are discussed below:

URL parameters

1. Order_by

This is used to ask PuppetDB to return results in ascending or descending order. 
The value must be a JSON array of maps.
Each map represents how to sort a field and the sort order is determined by the order in which the maps are specified.
For example:

curl -X POST http://localhost:8080/pdb/query/v4/nodes \ -H ‘factsets’\
'order_by=[{"field": "certname", "order": "desc"}, {"field": "name"}]'

In the above example, under the field of descending, we have set descending order (desc) of certificate names of nodes(certname). Followed by ascending order of names of nodes(name) under the field of ascending.

2. Limit
This value is an integer. It sets a maximum number of results to restrict the result. 
For example:

'limit’= <int value>
number=(number.limit)

Once you have set the value of limit. You can then call it out by using a “.” dot + limit as shown above. The number variable will be paged till the limit value.

3. Include_total
This requests a count of how many records would have been returned.
This is a safety option if the limit parameter dows not work to show what has been navigated by the user. The value should be Boolean. 
False is set as default.
For example:

curl -vv -X GET http://localhost:8080/pdb/query/v4/factsets \  --data-urlencode 'limit=<int value>' --data-urlencode 'include_total=<true/false>'

If the limit parameter fails to complete it’s function then include_total will return all the details of user actions during paging if set to true.

4. Offset
This parameter works like a label does in programming languages where the program coded by the offset will be executed. The value should be an integer. This parameter must always be used along with order_by.
For example:

curl -X GET http://localhost:8080/pdb/query/v4/facts \
  --data-urlencode 'order_by=[{"field": "certname"}]' \
  --data-urlencode 'limit=<int value>' \
  --data-urlencode 'offset=<int value>'

Paging will be done till limit value along the offset value. This means that if limit is set 5 and offset is set initially to 0 then to 5, this will execute paging from page size 0 to 5.
 

Now it’s time to discuss some frequently asked questions

Frequently Asked Questions

What is Puppet forge?

Puppet forge is a collection of modules. All these modules are pre-made by puppet and stored in forge.

Is Ansible better or Puppet?

Ansible is better as it pushes the configuration to the node instantaneously. Thus it is more scalable than Puppet. Puppet is built on Ruby whereas Ansible is built on Python.

How to set up PuppetDB?

The steps to set up puppetDB are:

1. Install PuppetDB.
2. Install and configure PostgreSQL.
3. Configure PuppetDB to use PostgreSQL.
4. Start PuppetDB and open the firewall.
5. Configure the Puppet master
6.  Use PuppetDB.

Is there a free version of Puppet?

Open-source puppet is free to use.

Conclusion

In this article, we discussed query language and structure. We also learned about various elements of query API version4 in puppetDB including entities, endpoints, and paging.

Please refer to our guided paths on Code studio to learn more about DSA, Competitive Programming, JavaScript, System Design, etc. And also, enroll in our courses and refer to the mock test and problems available. Have a look at the interview experiences and interview bundle for placement preparations.

Do upvote our blog to help other ninjas grow.

Happy Learning!