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. See NRQL variables for using variables in a NRQL query.
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.
Important points to note about adding a query:
The variable you defined goes inside the {{ … }} brackets.
The variable generates a string value.
To help you when you're creating a query, there's a color code:
Clauses, from, select, facet, and where, are in pink.
For restrictions related to writing queries, see Writing queries.
Use template variables
We'll walk you through creating 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 steps.
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 new dashboard without variables, click the edit button, and then, click + Add variable button located at the top-left corner. Once you've finished adding variables, click Done editing.
If the dashboard includes widgets, click the + Add variable button.
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 {{...}}. For example, if you use country here as the name, then when writing a query you'll call the variable with {{country}}.
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:
Query: You can write a query that will return a dynamic list of options used in the dropdown menu. For example, the following query would return a dynamic list of country values:
SELECT uniques(countryCode)FROM PageAction since 2 days ago
List: A list of comma-separated values that are used to populate the options in the dropdown menu. For example, you could manually define a list of country values using a list like: ES, US, CA.
Text field: Instead of a dropdown of values to choose from, this allows dashboard users to filter for whatever text they input.
Account
Only present for query type. For organizations with multiple accounts, this sets the account that is queried.
Query
Write here your query using uniques (attribute).
Multi-select
Optional. This option allows a dropdown to allow multiple selections at the same time instead of a single selection.
Default values
Optional. These are the defaults value that the dashboard will filter on. For example, if you used the country query above, you could input ES as the default value and the dashboard would automatically filter to that value. You can also select all possibilities.
To use multiple values on a WHERE clause you need to use IN instead of =.
Output format
This lets you change how the data generated by the variable is handled in the query. The selected option you choose here is related to the query you're going to add later in the widget. The default option is string because this is the more common option used in the majority of queries. You can change the default option to one of these:
String: Use this when the variable will produce a string.
Number: Use this when it will product a numeric value.
Identifier: Use this when you want to substitute parts of the query, like event names or facet names.
See this example of what a template variable for country values would look like:
Once you've defined your template variable, you can add a widget that uses your created template 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.
To create a widget:
From your dashboard click + Add widget button located at the top-right corner.
There are 2 options:
Add a chart. You'll create your widget using the query builder.
Add text, images, or links. You'll create your widget adding your own content using our Markdown editor.
We choose Add a chart option.
Add your query and click Run.
Following our example mentioned in step 1:
SELECT countryCode FROM PageAction WHERE countryCode IN({{countryCode}})
Click Save
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.
Here's an example of the resulting widget, on the right, with the country dropdown to the left.
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 or keyset syntax. Uniques return up to 10,000 results. Check uniques and the keyset. Here's a couple of query examples:
From PageAction select uniques(countryCode)
From PageView select keyset() SINCE 1day ago
You can use almost any NRQL query as long as the uniques and keyset components return a list of values.
Nested variables are not supported: there can't be variables within variables.
Some examples
Here are some different types of template variable implementations.
You can enable the multi-value option from the display options section when creating a variable of type NRQL/ENUM.
Here's an example of a query that creates a variable named {{MultiValue}} and returns a list of all unique eventId's:
SELECT uniques(eventId)FROM AjaxRequest
Then you would create a widget with the following query:
SELECTcount(*)FROM AjaxRequest WHERE eventId IN({{MultiValue}})
You can define only one template variable at a time, but you can use more than one template variable in a single widget.
Here's an example of a query that uses two template variables. Note that this assumes the countryCode and city template variables would have already been created and that they have a single value.
SELECT countryCode, city FROM PageAction WHERE countryCode = {{countryCode}} and city = {{city}}
If you have multiple values for your variables, such as Chicago, New York, Paris for your city variable, you need to use IN:
SELECT countryCode, city FROM PageAction WHERE countryCode IN({{countryCode}})and city IN({{city}})
Using variables and regex, you can create a filter, provided you're sure that a part of the filter is fixed.
You need to use this partial match if you want to use like.
Let's say you want to filter by release version. The query returns something like: release-1234.
You can create a variable using aparse to parse the version number:
SELECTcount(*)FROM PageAction WHERE aparse(platformVersion,'release-*')IN({{releaseversion}}) facet platformVersion
Or if you prefer, you could use the capture command:
SELECTcount(*)FROM PageAction WHERE capture(platformVersion, r'release-(?P<platformVersion>\d+)')IN({{releaseversion}}) Facet platformVersion
You can use LIKE and RLIKE as template variables to filter data in a dashboard. To use this feature, the value you add when creating the template variable must use the % wildcard symbols at the start and end of the value.
Here's an example. You define a string variable, as shown here:
You can then create a widget chart and use your variable like this:
FROM NrdbQuery SELECTuserWHEREuserLIKE {{like_filter}}
or like this:
FROM NrdbQuery SELECTuserWHEREuserRLIKE {{like_filter}}
You can create a variable of type NRQL with a string output format and use it after a facet clause to group by different values.
For example, you might create a variable named {{userAgentName}} that would look like:
SELECT uniques(userAgentName)FROM PageAction
Then you'd create a widget with the following query:
SELECTcount(*)FROM PageAction WHERE userAgentName={{userAgentName}} FACET userAgentName
You can create a variable with an identifier output format and use it after a FACET clause to group by different values.
For example, you might create a {{location}} variable of type list with two possible values: countryCode and city. You'd set the output format to identifier.
Then you'd create a widget with the following query:
SELECTcount(*)FROM PageAction FACET {{location}}
You can create a variable with output format number and use that inside a percentile function.
For example, you could create a {{percentile}} variable of type list with two possible values: 55 and 90. You'd want to set the output format as number.
Then you'd create a widget with the following query: