For custom dashboards, you can use template variables to dynamically filter charts and other widgets. Template variables help make your dashboards more useful, and help you more easily create dashboards you can reuse for different use cases.
Why use template variables?
Template variables are a powerful and dynamic way of filtering an entire dashboard based on specific metadata values a dashboard creator chooses. The benefits of using template variables are:
- They make dashboards easier to use: your users don't have to understand the structure of the data, but can simply choose from various filter options you've set.
- They allow you to create reusable dashboard templates, which you can then duplicate and adjust for many other uses.
Here's an example of a dashboard with several template variables, which you can see at the top of the dashboard.
With template variables, you can set up a wide variety of variables and filters to create the dashboard experience you need. Examples of experiences you can create:
- A dropdown to choose an app name
- A dropdown to choose specific regions
- A dropdown to select specific durations or other numeric values
- Filters that use free text fields to find matching strings
Requirements and limitations
Template variables can only be used in the context of making widgets for custom dashboards. (For using variables in a NRQL query, see NRQL variables.)
Queries with template variables can only be used in the context of a dashboard. For this reason, some query-related features don't work. For example, the Export dashboard as PDF
option doesn't support widgets with variables.
For restrictions related to writing queries, see Writing queries.
Use template variables
We'll walk you through making a template variable, and then we'll give you a few examples of different kinds of template variables.
Creating a template variable consists of two parts:
- Define the template variable
- Create or edit your widgets to use that variable
Step 1. Define the template variable
First, you'll define a template variable. This is the variable that you'll use in a NRQL query to create a widget.
To define a variable:
- From a dashboard without variables, click Add variable. (If there are already variables present, click the + icon to the right of the variables.)
- Complete the Add variable workflow. Below are some rules and tips for each of the fields.
Field | Details |
---|---|
Name to use in queries | The name of the variable. This is what you'll use in the query, surrounded by Variable names must start with a letter, and can contain letters, numbers, and underscores. |
Display name | Optional. This is how the variable will display above the dashboard so that dashboard users know what the variable represents. If this is left blank, it will use the main name value. |
Type | There are three options:
|
Account | Only present for |
Default values | Optional. These are the defaults value that the dashboard will filter on. For example, if you used the To use multiple values on a |
Multi-select | Optional. This option allows a dropdown to allow multiple selections instead of a single selection. |
Output format | This lets you change how the data generated by the variable is handled. By default, we attempt to automatically figure out what the value will be. But you can change this to a specific:
|
For an example of what a template variable for country
values would look like, see the screenshot at the top of this doc.
Once you've defined your template variable, you can move on to adding a template variable to your widgets.
Step 2. Create widgets that use the variable
Once you've configured a template variable, you'll need widgets on a dashboard that use the variable that you've defined in their query.
Here's an example of creating a query that uses the country
variable we mentioned in part 1:
SELECT countryCode FROM PageAction WHERE countryCode = {{countryCode}}
A couple important points to note about using a variable in a query:
- The variable you defined goes inside the
{{ … }}
brackets. - The variable generates a string value.
And here's an example of the resulting widget, on the right, with the country
dropdown to the left.
When you're done defining a template variable and adding a widget that references that variable, you can verify it's working as expected by choosing different options from the template variable bar and seeing if the widget changes based on your selection.
Rules for writing a query-type template variable
As discussed in the section on defining template variables, there are three variable types: query, list, and text field. The query-type variable is the most complex to create because you must create a working query that returns values, which are then used to populate the dropdown in the template variable bar at the top of the dashboard.
Important
Note that this is a different topic than writing queries that make use of a template variable.
Here are some rules and guidance on creating a query-type variable:
- Queries must use the
uniques
syntax. Uniques return up to 10,000 results. Check theuniques
syntax. Here's a query example:From PageAction select uniques(countryCode)
. - You can use almost any NRQL query as long as the
uniques
component returns a list of values. - Nested variables are not supported: there can't be variables within variables.
Examples
Here are some different types of template variable implementations.