docs-v2

16 KiB

Raw Blame History

title

description

aliases

Using dashboard template variables

Chronograf dashboards support template variables that let you modify queries through simple user interactions. Variable types include databases, measurements, field keys, tag keys, tag values, comma-separated values (CSV), maps, custom meta queries, and text.

/chronograf/v1.6/introduction/templating/

/chronograf/v1.6/templating/

chronograf_1_6

weight	parent
90	Guides

Chronograf's dashboard template variables allow you to alter specific components of cells' queries without having to edit the queries, making it easy to interact with your dashboard cells and explore your data.

Using template variables

Template variables are used in cell queries and titles when creating Chronograf dashboards. Within the query, template variables are referenced by surrounding the variable name with colons (:).

SELECT :variable_name: FROM "telegraf"."autogen".:measurement: WHERE time < :dashboardTime:

You can use either predefined template variables or custom template variables. Variable values are then selected in your dashboard user-interface (UI).

Predefined template variables

Chronograf includes predefined template variables controlled by elements in the Chrongraf UI. These template variables can be used in any of your cells' queries.

:dashboardTime:
:upperDashboardTime:
:interval:

dashboardTime

The :dashboardTime: template variable is controlled by the "time" dropdown in your Chronograf dashboard.

If using relative times, it represents the time offset specified in the dropdown (-5m, -15m, -30m, etc.) and assumes time is relative to "now". If using absolute times defined by the date picker, :dashboardTime: is populated with lower threshold.

SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime:

In order to use the date picker to specify a particular time range in the past which does not include "now", the query should be constructed using :dashboardTime: as the lower limit and :upperDashboardTime: as the upper limit.

upperDashboardTime

The :upperDashboardTime: template variable is defined by the upper time limit specified using the date picker.

It will inherit now() when using relative time frames or the upper time limit when using absolute timeframes.

SELECT "usage_system" AS "System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardTime: AND time < :upperDashboardTime:

interval

The :interval: template variable is defined by the interval dropdown in the Chronograf dashboard.

In cell queries, it should be used in the GROUP BY time() clause that accompanies aggregate functions:

SELECT mean("usage_system") AS "Average System CPU Usage"
FROM "telegraf".."cpu"
WHERE time > :dashboardtime:
GROUP BY time(:interval:)

Create custom template variables

Template variables are essentially an array of potential values used to populate parts of your cells' queries. Chronograf lets you create custom template variables powered by meta queries or CSV uploads that return an array of possible values.

To create a template variable:

Click Variables at the top of your dashboard, then + Add Template Variable.
Provide a name for the variable.
Select the variable type. The type defines the method for retrieving the array of possible values.
View the list of potential values and select a default. If using the CSV or Map types, upload or input the CSV with the desired values in the appropriate format then select a default value.
Click Create.

Once created, the template variable can be used in any of your cell's queries or titles and a dropdown for the variable will be included at the top of your dashboard.

Template Variable Types

Chronograf supports the following template variable types:

Databases
Measurements
Field Keys
Tag Keys
Tag Values
CSV
Map
Custom Meta Query
Text

Databases

Database template variables allow you to select from multiple target [databases](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#database).

Database meta query
Database template variables use the following meta query to return an array of all databases in your InfluxDB instance.

SHOW DATABASES

Example database variable in a cell query

SELECT "purchases" FROM :databaseVar:."autogen"."customers"

Database variable use cases

Database template variables are good when visualizing multiple databases with similar or identical data structures. They allow you to quickly switch between visualizations for each of your databases.

Measurements

Vary the target [measurement](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#measurement).

Measurement meta query
Measurement template variables use the following meta query to return an array of all measurements in a given database.

SHOW MEASUREMENTS ON database_name

Example measurement variable in a cell query

SELECT * FROM "animals"."autogen".:measurementVar:

Measurement variable use cases

Measurement template variables allow you to quickly switch between measurements in a single cell or multiple cells in your dashboard.

Field Keys

Vary the target [field key](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#field-key).

Field key meta query
Field key template variables use the following meta query to return an array of all field keys in a given measurement from a given database.

SHOW FIELD KEYS ON database_name FROM measurement_name

Example field key var in a cell query

SELECT :fieldKeyVar: FROM "animals"."autogen"."customers"

Field key variable use cases

Field key template variables are great if you want to quickly switch between field key visualizations in a given measurement.

Tag Keys

Vary the target [tag key](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#tag-key).

Tag key meta query
Tag key template variables use the following meta query to return an array of all tag keys in a given measurement from a given database.

SHOW TAG KEYS ON database_name FROM measurement_name

Example tag key variable in a cell query

SELECT "purchases" FROM "animals"."autogen"."customers" GROUP BY :tagKeyVar:

Tag key variable use cases

Tag key template variables are great if you want to quickly switch between tag key visualizations in a given measurement.

Tag Values

Vary the target [tag value](/{{< latest "influxdb" "v1" >}}/concepts/glossary/#tag-value).

Tag value meta query
Tag value template variables use the following meta query to return an array of all values associated with a given tag key in a specified measurement and database.

SHOW TAG VALUES ON database_name FROM measurement_name WITH KEY tag_key

Example tag value variable in a cell query

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "species" = :tagValueVar:

Tag value variable use cases

Tag value template variables are great if you want to quickly switch between tag value visualizations in a given measurement.

CSV

Vary part of a query with a customized list of comma-separated values (CSV).

Example CSVs:

value1, value2, value3, value4

value1
value2
value3
value4

Since string field values [require single quotes in InfluxQL](/{{< latest "influxdb" "v1" >}}/troubleshooting/frequently-asked-questions/#when-should-i-single-quote-and-when-should-i-double-quote-in-queries), string values should be wrapped in single quotes.

'string1','string2','string3','string4'


_**Example CSV variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "petname" = :csvVar:

CSV variable use cases

CSV template variables are great when the array of values necessary for your variable can't be pulled from InfluxDB using a meta query. They allow you to use custom variable values.

Map

Vary part of a query with a customized list of key-value pairs in CSV format. They key of each key-value pair is used to populate the template variable dropdown in your dashboard. The value is used when processing cells' queries.

Example CSV:

key1,value1
key2,value2
key3,value3
key4,value4

If values are meant to be used as string field values, wrap them in single quote ([required by InfluxQL](/{{< latest "influxdb" "v1" >}}/troubleshooting/frequently-asked-questions/#when-should-i-single-quote-and-when-should-i-double-quote-in-queries)). This only pertains to values. String keys do not matter.

key1,'value1' key2,'value2' key3,'value3' key4,'value4'


_**Example Map variable in a cell query**_
```sql
SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :mapVar:

Map variable use cases

Map template variables are good when you need to map or alias simple names or keys to longer or more complex values. For example, you may want to create a :customer: variable that populates your cell queries with a long, numeric customer ID (11394850823894034209). With a map variable, you can alias simple names to complex values, so your list of customers would look something like:

Apple,11394850823894034209
Amazon,11394850823894034210
Google,11394850823894034211
Microsoft,11394850823894034212

The customer names would populate your template variable dropdown rather than the customer IDs.

Custom Meta Query

Vary part of a query with a customized meta query that pulls a specific array of values from InfluxDB. These variables allow you to pull a highly customized array of potential values and offer advanced functionality such as filtering values based on other template variables.

Example custom meta query variable in a cell query

SELECT "purchases" FROM "animals"."autogen"."customers" WHERE "customer" = :customMetaVar:

Custom meta query variable use cases

Custom meta query template variables should be used any time you are pulling values from InfluxDB, but the pre-canned template variable types aren't able to return the desired list of values.

Text

Vary a part of a query with a single string of text. There is only one value per text variable, but this value is easily altered.

Text variable use cases

Text template variables allow you to dynamically alter queries, such as adding or altering WHERE clauses, for multiple cells at once. You could also use a text template variable to alter a regular expression used in multiple queries. They are great when troubleshooting incidents that affect multiple visualized metrics.

Reserved variable names

The following variable names are reserved and cannot be used when creating template variables. Chronograf accepts template variables as URL query parameters as well as many other parameters that control the display of graphs in your dashboard. These names are either predefined variables or would conflict with existing URL query parameters.

:database:
:measurement:
:dashboardTime:
:upperDashboardTime:
:interval:
:upper:
:lower:
:zoomedUpper:
:zoomedLower:

Advanced template variable usage

Filtering template variables with other template variables

Custom meta query template variables allow you to filter the array of potential variable values using other existing template variables.

For example, let's say you want to list all the field keys associated with a measurement, but want to be able to change the measurement:

Create a template variable named :measurementVar: (the name "measurement" is reserved) that uses the Measurements variable type to pull in all measurements from the telegraf database.
Create a template variable named :fieldKey: that uses the custom meta query variable type. The following meta query pulls a list of field keys based on the existing :measurementVar: template variable.
```
SHOW FIELD KEYS ON telegraf FROM :measurementVar:
```
Create a new dashboard cell that uses the :fieldKey: and :measurementVar template variables in its query.
```
SELECT :fieldKey: FROM "telegraf"..:measurementVar: WHERE time > :dashboardTime:
```

The resulting dashboard will work like this:

Defining template variables in the URL

Chronograf uses URL query parameters (also known as query string parameters) to set both display options and template variables in the URL. This makes it easy to share links to dashboards so they load in a specific state with specific template variable values selected.

URL query parameters are appeneded to the end of the URL with a question mark (?) indicating beginning of query parameters. Multiple query paramemters can be chained together using an ampersand (&).

To declare a template variable or a date range as a URL query parameter, it must follow the following pattern:

Pattern for template variable query parameters

# Spaces for clarity only
& tempVars %5B variableName %5D = variableValue

&
Indicates the beginning of a new query parameter in a series of multiple query parameters.

tempVars
Informs Chronograf that the query parameter being passed is a template variable. Required for all template variable query parameters.

%5B, %5D
URL-encoded [ and ] respectively that enclose the template variable name.

variableName
Name of the template variable.

variableValue
Value of the template variable.

Whenever template variables are modified in the dashboard, the corresponding URL query parameters are automatically updated.

Example template variable query parameter

.../?&tempVars%5BmeasurementVar%5D=cpu

Including multiple template variables in the URL

To chain multiple template variables as URL query parameters, include the full pattern for each template variable.

# Spaces for clarity only
.../?  &tempVars%5BmeasurementVar%5D=cpu  &tempVars%5BfieldKey%5D=usage_system

16 KiB Raw Blame History