Using dashboard template variables

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 (:).

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.

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.

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). This only pertains to values. String keys do not matter.

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:

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.

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.

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: