Puppet Query Language
The Puppet Query language is used to access, manage, manipulate, and store Puppet data in PuppetDB. The PuppetDB contains the data, and to fetch or store the data, you need a language; the Puppet Query Language fulfills this purpose. It enables you to search the database and retrieve stored raw data. It offers a string-based query language.
In this article, we will be using PuppetDB, so first of all, let us get familiarised with PuppetDB. You can follow the articles below to understand how to start with PuppetDB.
Now we are ready to get started with our main topic.
Three main elements in PuppetDb can be queried using the Puppet Query Language. They are
-
Resources: These are the primary units for modelling the system configurations. Each resource gives information about a particular system component, such as a service or package. The main features of resources used in querying include resource type, a title, and a set of attributes.
-
Facts: Facts are the key-value pairs in Puppet. You can query for a particular value for a key, and all the records with a matching key-value pair will be retrieved. The main features on which facts are queried include "certname", a "name", and a "value". There are more features as well.
- Nodes: Nodes are the basic blocks of PE. You can use the certname feature to query nodes.
Now let’s understand the query structure.
Query Structure
The Puppet Query Language uses a specific structure to define the queries. The structure is as follows.
<entity> [<projection>] { <filter> <modifiers> }
As you can see, a Puppet Query has four parts.
-
Entity: The context on which you want to run your query. It can be a resource, fact, or node. It is a required field.
-
Projection: The projection here is similar to SQL projection. You can select particular columns or fields you want to retrieve as the query output. It is optional. If not passed, then all the fields of matching records are retrieved.
-
Filter: It is also an optional field. You can write some key-value pairs that you want to use to filter the entity. It limits the number of records fetched when a query is executed. If not passed, all the entries of the given entity are fetched.
-
Modifiers: It is used to mention the modifiers for the query. It is also an optional field.
For example, if you write the following query, it will retrieve all the resources of the User type with the title “john”. Also, for all the records in the output, only the certname will be provided, as we have used the projection field on certname.
resources [certname] { type = "User" and title = "john" }
Note: Whitespace is optional in PQL(Puppet Query Language) except for words like or and and. You can provide as much whitespace as you want, and it would not matter. You can add the whitespace to make the query more human-readable.
Let us now understand the various essential features of Puppet Query Language(PQL) in detail.
Entities
An entity is the first and only required part of a query in PQL. It defines the components on which you want to run your query. It provides the main context on which you perform any filters and projections. It can be a resource, fact, or node.
For example, if you want to output all the information about all the nodes in your PuppetDB, you can fire the below query.
nodes {}
This query indicated that all the records of nodes are to be fetched with all the fields. The empty curly brackets are essential. It specifies that no filter is applied and all the nodes are required.
Projections
The projection here is similar to SQL projection. An entity can have many fields, and you may need to retrieve only a few of them; this can be specified using the projection part of the query. You can select a set of particular columns or fields you want to retrieve as the query output.
Projection fields are mentioned within the square brackets just after the entity, as shown below
resources [<projection>] {}
It is an optional part of the query; if the fields are not mentioned, all the fields with matching records are fetched from the database. You can mention any number of projection fields as your needs.
For example, the below query will return the certname of all the resource entities from the database.
resources [certname] { }
The square brackets are also optional. So, the below two queries are equivalent.
nodes [ ] { }
nodes { }
The two main components of projections include fields and functions. We will discuss each in brief.
Fields
Projection is performed on the fields of the records. As mentioned above, you can mention any number of fields within the square brackets, and now those fields of the matching records will be retrieved. Multiple fields can be specified using comma-separated values.
Some entities can have many fields, and all the fields may not be necessary. Also, it is inefficient for both the network and the database to query all the fields of an entity. So, with the projection part of the query, you can reduce the number of fields to be returned.
For example, the below query will return the values at field1, field2, and field3 only for all the nodes.
nodes [field1, field2, field3] { }
Functions
Within the projections, only the aggregate functions are supported. The aggregate functions in PQL are used to perform calculations on a collection of data values and return a single value.
The syntax of using an aggregate function within projection is similar to fields. We have provided the syntax below.
Entity [ function( argument ) ] { }
PQL supports multiple aggregate functions. Some of these functions are:
-
count() It returns the number of objects returned in the query.
-
sum(<field>) It returns the sum of all values of the field provided.
-
avg(<field>) It returns the arithmetic average of all the values in the field provided.
-
min(<field>) It returns the minimum value of all the given field values.
- max(<field>) It returns the maximum value of all the given field values.
Filter
Another essential part of the query is the filter. It is used to filter or limit the records based on such key-value pairs. It is an optional part, i.e., if not passed, all the records are retrieved.
You can specify multiple filters connected using the conditional and boolean operators.
resources [certname, type, title] { type = "User" and title = "john" }
In the above query, you can see that only those resource entities are retrieved with the title john and type as User.
Conditional Operators
The conditional operators define a condition that returns either true or false. The records for which the conditions become true are returned using the filter. Following are the main conditional operators used in Puppet Query Language.
Equality (=)
The equality operator matches the field value of different records with a literal value.
nodes { certname = "func" }
All the records with the certname value “func” are returned.
Numeric comparison ( <=, >=, >, < )
These are used to compare a field value with a numerical value. There are four numeric comparison operators. They are:
<= less than or equal to
>= greater than or equal to
> greater than
< less than
These only work with numeric fields.
facts { value >= 15 }
All the fact records with values greater than or equal to 15 are returned.
Array Match ( in )
An array is a collection of values. The array match (in) operator checks whether a data value is present in an array or a subquery.
nodes { certname in ["func", "carz", "pas"] }
In the above query, all the node records are returned whose certname belongs to [“func”, “carz”, “pas”]. The in operator is used to specify multiple values for the certname field.
You can also use the in operator within a query as a subquery. A subquery is a query witten within another query.
nodes { certname in facts[certname] { value = "func" } }
In this query, the facts[certname] { value = “func”} is a subquery, which is executed first, and then all the nodes whose certname belongs to the output of the subquery are returned.
Null detection ( is null, is not null )
As the name suggests, this operator checks whether a field is null or not.
nodes { expired is null }
The above query returns all the nodes whose expired status is null.
In the same manner, you can also use the is not null operator.
Boolean operators
The boolean operators are used to specify a condition that returns true or false. It includes the logical operators that are used to connect multiple filters.
and It performs the and operation between two filter fields. For the overall condition to be true, both fields must be true. (Conjunction operation)
or It performs the or operation between two filter fields. For the overall condition to be true, either or both the fields must be true. (Disjunction operation)
! It performs the negation operation. It converts the true conditions to false and vice versa.
resources { type = "User" and title = "john" }
In the above query example, the and operator is used, which means that both conditions must be true to return a resource. If either condition is false, then the record is not retrieved.
Group By
The group by feature within the filter combines the records that share a common value for a given field. You can specify the field by which you want to club the records together.
For example, you can retrieve all the unique titles in the nodes by grouping all the records by title and projecting only the title.
nodes [title] { group by title }
You can also use the aggregate functions in the projection part of the query. This will apply the aggregate function on the combined records with respect to given fields.
For example, with the below query, you can count the number of records with a particular title. This can be done by forming the groups based on the common title name and then using the count() aggregation function, as shown below.
nodes [ title, count( ) ] { group by title }
Paging
PQL supports three paging clauses, including limit, offset and order by.
The order by clause in PQL is used to sort the output of a query based on the value of some fields. You can mention one or more fields based on which the records are sorted.
For example, In the below query, all the nodes with the certname “mbp.local” are fetched and the “report_timestamp is used to sort the records”. The order is not mentioned, so the records are sorted in ascending order by default.
nodes {certname = "mbp.local" order by "report_timestamp"}
To specify the order, you can mention asc or desc to specify ascending or descending order, respectively.
You can specify multiple fields in comma separated manner to sort with respect to multiple fields. In this, the field mentioned first is used as the primary sorting field.
For example, In the below query, all the nodes are fetched, and first, they are sorted by the "report_timestamp" in ascending order(since not specified), and then within the same "report_timestamp", the records are sorted by certname in descending order.
nodes {order by "report_timestamp", certname desc }
Now, you can also restrict the number of entries to be retrieved. It is done using the limit and the offset clauses.
For example, the below query will return the top 10 records when all the nodes are fetched and sorted in ascending order by their title.
nodes { order by title limit 10 }
Frequently Asked Questions
What is Puppet?
Puppet is a software configuration management tool. It is a platform to configure the system and software settings. Puppet has its declarative language to manage the settings. You do not need much knowledge of programming to use Puppet.
How to ensure if Puppet is installed on the system or not?
To ensure that Puppet is installed or not in your system, run the command puppet-V. If it gives an output with some version of Puppet, that means Puppet is installed; else not.
What is Puppet Enterprise?
Puppet Enterprise is a commercial version of Puppet developed on top of the open-source Puppet platform. It makes the automation and delivery of infrastructure and complex workflows more accessible.
Is PuppetDB written in Java?
PuppetDB is not really written in Java. It is written in the Java Virtual Machine(JVM) compatible Clojure language.
What are the parts of a query in PQL? Which parts are optional?
There are four parts of a query in PQL. They are entity, projection, filter, and modifier. The entity is the only required part, and all other parts are optional.
Conclusion
This article discussed the Puppet Query Language. We have discussed the structure and components of a query in Puppet Query Language.
To learn more about Puppet and PuppetDB, visit the below articles.
I hope you have gained a better understanding of these topics now! Are you planning to ace the interviews with reputed product-based companies like Amazon, Google, Microsoft, and more?
Attempt our Online Mock Test Series on Coding Ninjas Studio now!
Happy Coding!
26+ registered 
