Generating data series in the Query tab

If it isn't already selected, click on the Query tab to select it. The Query tab is where we will assign a data source to the panel's queries. With TestData DB set as the default data source, Grafana also sets up Random Walk to be the default query Scenario, so we are now ready to go with both a data source and a query that produces the displayed dataset series.

Before we go into the Query tab, we should probably talk a bit about its purpose. Rather than some similar applications that connect to a single database application, Grafana was designed to be agnostic about data. Grafana data source plugins are not only responsible for presenting a simplified query interface to the Grafana user but also for feeding the returned data into the Grafana 7 unified data model, which is used by many panels. Most Grafana users will find that, even with a simplified query UI, they can make relatively sophisticated queries.

In cases where a complex query is beyond the scope of the query UI, data sources such as MySQL and PostgreSQL will also support regular SQL queries. Other data sources such as Prometheus and InfluxDB support raw text queries as well. Bear in mind that the data source query interface will not provide protection against dangerous queries, so if you do plan to use native queries, consult with your database administrator about designating a user account with restricted permissions for your Grafana data sources.

What is a query?

Essentially, a query is a mechanism for extracting a data series for display by the panel. The Query tab allows multiple queries from the same data source or a mix of multiple data sources to be extracted. It can even reference a data source from other panels. Depending on the data source plugin, Grafana will convert the tab's queries into API calls to the data source server (similar to a SQL statement to an RDBMS), retrieve the data in an internal structure called a data frame, and then display some or all of it, depending on the current time range.

For now, we'll just use the current TestData DB as our data source so that we can concentrate on the different aspects of the graph panel interface. In the next chapter, we'll look more closely at how to query an actual third-party data source, rather than an internally generated one.

Query tab features

Let's have a look at the main features of the Query tab. Depending on the data source, individual queries will differ, but the overall interface will be the same, as shown in the following screenshot:

Here are the key features that have been identified in the preceding screenshot:

1. Data source menu
2. Query Options
3. Query inspector button
4. Query
5. Move Query Down and Up
6. Duplicate Query
7. Query visibility toggle
8. Delete Query
9. + Query button

Let's have a look at each of these features and see how they work together to give you control over a data source query and the resulting data series.

The Data source menu

The Data source menu is where you will select the data source for the panel. In general, a panel will only contain queries from a single data source, so the pulldown will present all the available data sources. If you do want to combine multiple data sources into a single graph, select Mixed. You can then specify the data source as you add queries.

Query Options

Monitoring the value of a given point at a sample of time (called an interval) is critical to maintaining the proper visual representation of data. Next to the Data source menu is the Query Options section, which contains the various options for configuring how the panel handles how time series data is displayed.

Max data points controls the maximum number of data points that should be displayed, even if the time range is very wide. Min interval is used to give Grafana the sampling interval of the data in the query to help it determine the minimum time interval to display with a single data point. Setting the value to the frequency of each data point helps Grafana optimize the display of time series panels, especially when dealing with wide time ranges. For example, your data is written to a Prometheus database once every minute (thesampling frequency); here, you would set Min Interval to1m.

In order to keep track of the interval of time represented by a single pixel, Grafana provides a helpful Interval display.

While the time range control at the top of the panel is used to set a global time range for all the panels on the dashboard, often, you want to override the time range for individual panels. Perhaps you want to see a 1-hour, 2-hour, and 4-hour range for your panel. You don't want to have to keep flipping the time range multiple times so that you can replicate the panel three times and set three different time ranges.

The Relative time setting is used to set the panel time range to one that's independent of the dashboard time range. The Time shift setting is useful for moving the panel's time range back some offset from the current time. Using both has the effect of altering the width of the window of time displayed and/or moving the endpoint of that window back in time relative to now.

To specify the time interval for Min Interval, Relative time, and Time shift, use the following time abbreviations:

Query inspector

The Query inspector button will open a text console revealing the contents of the query Grafana is submitting to the API. This is a very informative feature for a couple of reasons. If you are having trouble getting the results you want, Query inspector can give you an insight into how you might be making an incorrect query to the data source. Additionally, by viewing the actual generated query, you can determine how you might go about making it more efficient. A more efficient query can substantially improve the responsiveness of a Grafana dashboard, especially when it contains several panels.

Query

The query is, of course, the central interface element for deriving a dataset. It can contain a number of elements, depending on the data source. In the case of the TestData DB data source, it is simply a Scenario dropdown for selecting a number of different options for generating test data.

The Alias text field is for giving the dataset a name of your choosing. The data source will designate a name for each query, but that name is often not very descriptive, so adding an Alias is a good way to document the contents of the query. In later chapters, we'll look at some tips on how to use the Alias name to annotate the legend and to create display overrides.

Query controls

Clicking the query arrows moves the query up or down and has the effect of changing the order of the datasets as they are displayed. This has a direct impact, should you choose to stack multiple datasets (the Display section). Duplicating the query creates a copy of the current query directly below it. This saves some time if you want to use the same query but display different aggregations or change a single field (column). Clicking on the query trash can icon deletes the query.

Add Query

Add Query adds a new query below the current one.

Duplicating an existing query

With this in mind, let's go back to our query. Since we got a query for free when we created the panel, let's create another one, just to see how it affects the display:

1. Select the TestData DB data source from the dropdown.
2. Click on the Duplicate Query icon. You should now see two queries, both with the Random Walk scenario:

Let's now move on to the Panel tab and see how we can use it to modify the look of our panel.