Chapter 12. Data Queries

Data queries are not a replacement for data input methods in Cacti. Instead they provide an easy way to
query, or list data based upon an index, making the data easier to graph. The most common use of a data query
within Cacti is to retrieve a list of network interfaces via SNMP. If you want to graph the traffic of a network
interface, first Cacti must retrieve a list of interfaces on the host. Second, Cacti can use that
information to create the necessary graphs and data sources. Data queries are only concerned with the
first step of the process, that is obtaining a list of network interfaces and not creating the graphs/data
sources for them. While listing network interfaces is a common use for data queries, they also have other
uses such as listing partitions, processors, or even cards in a router.

One requirement for any data query in Cacti, is that it has some unique value that defines each row in the list.
This concept follows that of a 'primary key' in SQL, and makes sure that each row in the list can be uniquely
referenced. Examples of these index values are 'ifIndex' for SNMP network interfaces or the device name for
partitions.

There are two types of data queries that you will see referred to throughout Cacti. They are script
queries and SNMP queries. Script and SNMP queries are virtually identical in their functionality and
only differ in how they obtain their information. A script query will call an external command or
script and an SNMP query will make an SNMP call to retrieve a list of data.

All data queries have two parts, the XML file and the definition within Cacti. An XML file must be
created for each query, that defines where each piece of information is and how to retrieve it. This
could be thought of as the actual query. The second part is a definition within Cacti, which tells
Cacti where to find the XML file and associates the data query with one or more graph templates.

Once you have created the XML file that defines your data query, you must add the data query
within Cacti. To do this you must click on Data Queries under the Data
Gathering heading, and select Add. You will be prompted for some
basic information about the data query, described in more detail below.

Table 12-1. Field Description: Data Queries

Name

Description

Name

Give the data query a name that you will use to identify it. This name will be used throughout Cacti when presented with a list of data queries.

Description

(Optional) Enter a more detailed description of the data query including the information it queries or additional requirements.

XML Path

Fill in the full path to the XML file that defines this query. You can optionally use the <path_cacti> variable that will be substituted with the full path to Cacti. On the next screen, Cacti will check to make sure that it can find the XML file.

Data Input Method

This is how you tell Cacti to handle the data it receives from the data query. Typically, you will select "Get SNMP Data (Indexed)" for an SNMP query and "Get Script Data (Indexed)" for a script query.

When you are finished filling in all necessary fields, click the Create button
to continue. You will be redirected back to the same page, but this time with some additional
information to fill in. If you receive a red warning that says 'XML File Does Not Exist', correct
the value specified in the 'XML Path' field.

Every data query must have at least one graph template associated with it, and possibly
more depending on the number of output fields specified in the XML file. This is where
you get to choose what kind of graphs to generate from this query. For instance, the
interface data query has multiple graph template associations, used to graph traffic,
errors, or packets. To add a new graph template association, simply click Add
at the right of the Associated Graph Templates box. You will be presented
with a few fields to fill in:

Table 12-2. Field Description: Associated Graph Templates

Name

Description

Name

Give a name describing what kind of data you are trying to represent or graph. When the user creates a graph using this data query, they will see a list of graph template associations that they will have to choose from.

Graph Template

Choose the actual graph template that you want to make the association with.

When you are finished filling in these fields, click the Create button.
You will be redirected back to the same page with some additional information to fill in. Cacti
will make a list of each data template referenced to in your selected graph template and display
them under the Associated Data Templates box. For each data source item
listed, you must selected the data query output field that corresponds with it. Do not forget to
check the checkbox to the right of each selection, or your settings will not be saved.

The Suggested Values box gives you a way to control field values of data sources and graphs
created using this data query. If you specify multiple suggested values for the same field, Cacti will evaluate
them in order which you can control using the up or down arrow icons. For more information about valid field names
and variables, read the section on suggested values.

When you are finished filling in all necessary fields on this form, click the Save button to
return to the data queries edit screen. Repeat the steps under this heading as many times as necessary to represent
all data in your XML file. When you are finished with this, you should be ready to start adding your data query to
hosts.