Chapter 10. 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.

10.1. Creating a Data Query

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 10 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

 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.

10.1.1. Associated Graph Templates

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 10 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.

16