Creating dashboard variables

Use dashboard variables to turn a dashboard into a template, for example, to let users pick an asset and plot its time series. With the Cognite Data Source for Grafana, you populate a variable from a GraphQL query against a data model. A variable can hold whole instance references that queries filter on, and it can narrow the options of another variable.

Before you begin

Create a dashboard that uses the Cognite Data Source for Grafana.

Dashboards built on asset-centric features use the Assets tab of the variable editor instead. See Creating variables from asset queries.

Create a variable from a GraphQL query

Use GraphQL queries against data models to populate variable values from CDF. The GraphQL tab uses the same editor as the GraphQL query tab in panels.

The variable editor with a GraphQL query that lists assets, the response, and Instance ID selected as the value

Open the variable editor

Open the dashboard’s variable settings and add a variable. Set Type to Query, select your Cognite Data Source as the Data source, and select the GraphQL tab.

Select the data model and version

Select the Data model and Version you want to query.A new variable opens on the Cognite core data model (CogniteCore, version v1) with a query that lists the first 10 assets. You can run this query as-is.

Write and test the query

In the Query field, enter a GraphQL query. Select Test query to see the raw response in the Response pane without saving the variable.

query MyQuery {
  listCogniteAsset(first: 10) {
    items {
      space
      externalId
      name
    }
  }
}

The query can return list results (items) or connection-style results (edges). Select Examples to open ready-made queries.

Select the value and display text

In the Value field, select the field the variable holds for each row in the response, for example, externalId or instanceId.space. The list is populated from your query once the query is valid.Optionally, in the Display text field, select a different field to show in the variable dropdown. For example, set Value to externalId and Display text to name so users pick readable names. If you leave Display text empty, the dropdown shows the value.

Save the variable

Select Update.If the query fails, the variable shows the error message instead of an empty list. If the data source can’t save the variable, a message explains why.

The variable dropdown on the dashboard lists the values the query returned. Use $variable or ${variable} in panel queries to insert the selected value.

Emit instance references

A GraphQL variable can hold a whole instance reference, the space and externalId of an instance, instead of a single field. Use instance references to filter queries on direct relations, for example, to show the time series or the records of the asset a user selects.

Select space and externalId in the query

In the variable’s GraphQL query, select both space and externalId on the same object. This can be the rows themselves or one nested field, such as instanceId { space externalId }.

query MyQuery {
  listCogniteAsset {
    items {
      space
      externalId
      name
    }
  }
}

Select Instance ID as the value

In the Value field, select Instance ID (space + externalId). Set Display text to name so the dropdown shows readable names.

The editor shows Emits instance references. Each value is stored as {"space":"...","externalId":"..."}.

Use instance references in queries

A variable that holds instance references filters a query on a direct relation. The data source writes the selected instances in the syntax of each query tab.

Where	How to use the variable	Learn more
GraphQL query tab	In the query, for example, `assets: {containsAny: $asset}`	Using dashboard variables in GraphQL queries
Synthetic time series query tab	In a variable’s filter, for example, `assets=$asset`	Use dashboard variables in filters
Records query tab	As the value of a filter on a direct relation property	Filtering records
Another GraphQL variable	In the variable’s query	Chain variables

The instance pickers on the Time series and Activities tabs don’t accept dashboard variables. To plot the time series of the instance a user selects, use the GraphQL or Synthetic time series tab.

Syntax in GraphQL queries

In the GraphQL query of a panel or of another variable, the data source writes the variable in GraphQL syntax:

Syntax	Result
`${asset}`, `$asset`, or `[[asset]]`	A GraphQL instance argument, `{space: "...", externalId: "..."}`
`${asset}` in a multi-value variable	A list of instance arguments. Selecting All includes every option.
`${asset.space}`	The `space` of the instance
`${asset.externalId}`	The `externalId` of the instance

Variables that don’t hold instance references, and variables with a format such as ${asset:csv}, are filled in by Grafana as usual.

Chain variables

A variable’s GraphQL query can use other dashboard variables, so the value selected in one variable narrows the options of the next. For example, a site variable can limit an asset variable to the assets of the selected site, and a third variable can list the children of the selected asset. When a user changes a variable, Grafana updates the variables that depend on it.

Create the first variable

Create a variable from a GraphQL query, for example, site. To filter the next variable on a direct relation, emit instance references.

Use the first variable in the query of the second

Create a second variable, and use the first variable in its query. For example, this query lists the assets whose parent is the asset held in the site variable:

query AssetsOfSite {
  listCogniteAsset(
    filter: {
      and: [
        { parent: { space: { eq: "${site.space}" } } }
        { parent: { externalId: { eq: "${site.externalId}" } } }
      ]
    }
  ) {
    items {
      space
      externalId
      name
    }
  }
}

Variables that hold plain values work too, for example, "$siteName" in a string filter.

When a user selects a value in the first variable, the dropdown of the second variable lists only the matching options.

The options of a variable are the rows of the first field in the query, such as the items of listCogniteAsset. Instances nested deeper in the response, for example, the children of an asset returned by getCogniteAssetById, don’t become options. To list related instances, filter a list query on the relation, as in the example.

Build

Creating dashboard variables

Before you begin

Create a variable from a GraphQL query

Emit instance references

Use instance references in queries

Syntax in GraphQL queries

Chain variables

Further reading