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. 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.
    • Identifiers are in black.
    • Functions are in blue.
    • Strings are in green.
    • Integers are in brown.
  • See our How to use NRQL: the mechanics of querying page if you want to know more about writing queries with NRQL.

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.

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.


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 1 day 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.

If you haven't already, create your free New Relic account below to start monitoring your data today.