• Log inStart now

Template variables: dynamically filter dashboards

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:

  1. Define the template variable
  2. 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:

  1. From a dashboard without variables, click Add variable. (If there are already variables present, click the + icon to the right of the variables.)
  2. 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

    For rules and tips on writing queries, see Query-type variables.

  • 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.

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 =.

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:

  • 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.

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 the uniques 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.

Copyright © 2023 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.