This is documentation for the next version of Grafana documentation. For the latest stable release, go to the latest version.

Documentation Grafana documentation Data sources InfluxDB Template variables

InfluxDB template variables

Instead of hard-coding details such as server, application, and sensor names in metric queries, you can use variables. Grafana displays these variables in drop-down select boxes at the top of the dashboard to help you change the data displayed in your dashboard. Grafana refers to such variables as template variables.

For general information about variables, refer to Variables and Add and manage variables.

Before you begin

• Configure the InfluxDB data source.
• Understand Grafana template variables.

Supported variable types

To switch a dashboard between InfluxDB instances, use a data source variable. Don’t use a query variable that returns data source names as a workaround. Query-based workarounds can break after Grafana upgrades because they depend on internal identifiers. Refer to Add a data source variable for details.

Where you can use variables

Variable support differs by query editor and mode:

Create a query variable

By adding a query template variable, you can write an InfluxDB metadata exploration query. These queries return results such as measurement names, key names, and key values.

For more information, refer to Add a query variable.

InfluxQL query variable examples

To create a variable containing all values for the hostname tag, use the following query in the Query field:

SQL Copy

SHOW TAG VALUES WITH KEY = "hostname"

You can fetch key names for a given measurement:

SQL Copy

SHOW TAG KEYS [FROM <measurement_name>]

You can list available measurements:

SQL Copy

SHOW MEASUREMENTS

Flux query variable examples

For Flux-configured data sources, write a Flux query that returns a single column of values:

flux Copy

import "influxdata/influxdb/schema"
schema.tagValues(bucket: v.defaultBucket, tag: "hostname")

SQL query variable examples

For SQL-configured data sources (InfluxDB 3.x), write an SQL query that returns a single column of values:

SQL Copy

SELECT DISTINCT hostname FROM cpu

You can list available tables:

SQL Copy

SHOW TABLES

You can list columns in a specific table:

SQL Copy

SHOW COLUMNS FROM cpu

Scope variables to the dashboard time range

By default, metadata queries such as SHOW TAG VALUES return values from the entire retention period, not just the dashboard time range. If a host or sensor stopped reporting long ago, its values still appear in the variable drop-down as long as they exist within retention.

To limit variable results to the dashboard time range:

1. Include a time condition in the variable query. Variable queries interpolate the same time macros as regular queries: $timeFilter for InfluxQL, $__timeFilter(<column>) for SQL, and v.timeRangeStart and v.timeRangeStop for Flux.
2. Set the variable’s Refresh option to On time range change so the values update when the dashboard time range changes.

InfluxQL example:

SQL Copy

SHOW TAG VALUES WITH KEY = "hostname" WHERE $timeFilter

SQL example:

SQL Copy

SELECT DISTINCT hostname FROM cpu WHERE $__timeFilter(time)

Chain or nest variables

You can create nested variables, sometimes called chained variables.

For example, if you have a variable named region, you can configure the hosts variable to display only hosts from the selected region.

InfluxQL:

SQL Copy

SHOW TAG VALUES WITH KEY = "hostname"  WHERE region = '$region'

SQL:

SQL Copy

SELECT DISTINCT hostname FROM cpu WHERE region = '$region'

If you have a variable containing key names, you can use it in a GROUP BY clause. This allows you to adjust the grouping by selecting from the variable list at the top of the dashboard.

Use filters

InfluxDB supports the use of filters for InfluxQL. They allow you to define multiple key/value filters, which Grafana automatically applies to all your InfluxDB queries. Filters also support expressions.

To add filters:

1. Navigate to the dashboard you want to update and click Edit.
2. Click the Add new element icon (blue plus sign).
3. Click Filter and Group by.
4. Enter a Name for the filter.
5. Select an option in the Display drop-down list to control where on the dashboard the filter is displayed.
6. Select your InfluxDB data source in the Data source drop-down list.

For more information, refer to the Filter and Group by documentation.

Choose a variable syntax

The InfluxDB data source supports two variable syntaxes for use in the Query field:

• $<varname> - Use this syntax for standalone variable references. It doesn’t allow you to use a variable in the middle of a word or expression.
• ${varname} - Use this syntax when you want to interpolate a variable in the middle of an expression.

InfluxQL examples:

SQL Copy

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^$host$/ AND $timeFilter GROUP BY time($__interval), "hostname"

SQL Copy

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^${host}$/ AND $timeFilter GROUP BY time($__interval), "hostname"

When you enable the Multi-value or Include all value options with InfluxQL, Grafana converts the labels from plain text to a regular expression-compatible string, so you must use =~ instead of = and wrap the variable in a regular expression such as /^$host$/.

For example, if $host is a multi-value variable and you select server1 and server2, Grafana joins the values with |, wraps them in parentheses, and escapes any special characters. The interpolated query looks like this:

SQL Copy

SELECT mean("value") FROM "logins" WHERE "hostname" =~ /^(server1|server2)$/ AND $timeFilter GROUP BY time($__interval), "hostname"

SQL examples:

SQL Copy

SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host = '$host' GROUP BY $__dateBin(time)

SQL Copy

SELECT $__dateBin(time), mean(usage_system) FROM cpu WHERE $__timeFilter(time) AND host IN ($host) GROUP BY $__dateBin(time)

When you enable the Multi-value option with SQL, use the IN operator instead of = to match multiple values.

Prevent unwanted value escaping

When you use a variable inside a regular expression, or when the variable is multi-value, Grafana escapes special characters in the values so the query remains valid. If you need the literal, unmodified value instead, use the raw format option:

SQL Copy

SELECT mean("value") FROM "requests" WHERE "path" = '${path:raw}' AND $timeFilter GROUP BY time($__interval)

This is useful for custom variables whose values intentionally contain characters that Grafana would otherwise escape. For all available format options, refer to Advanced variable format options.

Templated dashboard example

To view an example of a templated dashboard, refer to this InfluxDB example dashboard.