Querying data models with GraphQL in Grafana

Use the GraphQL query tab to run a GraphQL query against a data model. The Query type field decides what the panel shows:

Instances fetches data modeling instances. The panel shows the rows the query returns, for example, a list of assets, equipment, or activities in a table panel.
Numeric, String, or State fetches data points. The query is a filter that selects the time series to plot, for example, every time series of an asset, and the panel plots the data points of each time series in the result.

The tab includes a Response pane, so you can preview what the query returns before you save the dashboard. To pick a single time series by name instead, use the Time series tab. To learn how to write GraphQL queries against data models, see Query data with GraphQL.

Before you begin

Make sure an administrator has set up the data source and turned on the GraphQL tab.

Running a query

The GraphQL query tab with a query that lists numeric time series and the response next to it

Select the data model and version

On the GraphQL tab, select the Data model and Version.

Choose the query type

In the Query type field, choose what the panel fetches.

Query type	Returns
Numeric	The data points of the numeric time series in the result. This is the default.
String	The data points of the string time series in the result.
State	The data points of the state time series in the result.
Instances	The rows the query returns, without data points. Use it to show instances of any type in a table panel.

With a time series query type, the panel skips time series of other types and shows a warning that names them. To plot time series of several types, add one query for each type.

Write the query

In the Query field, write the query. With Instances, select the fields you want as columns. With a time series query type, select space and externalId on each time series to plot. For example, this query plots the time series linked to the first 10 activities:

query MyQuery {
  listCogniteActivity(first: 10) {
    items {
      name
      timeSeries {
        items {
          space
          externalId
          name
          type
        }
      }
    }
  }
}

The tab uses the data model schema to find time series in the response. It plots every row, or field on a row, whose type is CogniteTimeSeries or a type that implements it.

For a relation to many instances, select the fields under items. See GraphQL list and getById queries with subqueries.

The editor underlines mistakes as you type, such as syntax errors and fields or arguments that the data model doesn’t have. Press Shift+Enter to save and run the query.

Select Examples to open ready-made queries, for example, for string or state time series, for instances without data points, or for time series reached through a relation.

Test the query

Select Test query to run the query and show the raw response in the Response pane. The test sends the query exactly as the panel runs it, with dashboard variables filled in, and doesn’t save anything.If the query has a syntax error, the error appears next to the editor and you can’t test the query until you fix it. Until then, the panel keeps running the last valid query.

Set the data points and label

For every query type except Instances, set the Data points field the same way as on the Time series tab. See Query options for time series panels.In the Label field, use {{field}} to insert any field you selected in the query, for example, {{name}} @ {{space}}. For time series reached through a relation, you can also use fields from the parent row. For example, in the query above, {{name}} is the time series name, and a field that only the activity has resolves against the activity. Hover over the field to see the fields that the current query offers. For state time series, you can also use the {{state}} token.If you leave Label empty, each series uses the time series name. The tokens read the response, so select the fields you use in the label in the query. See Labels.

With Instances, the panel shows the rows of the query as a table. With a time series query type, it plots one series for each time series in the result, named by the label you set.

Using dashboard variables in GraphQL queries

Use $variable or ${variable} to insert a dashboard variable in the query. Grafana fills in the variables before the query runs. If a variable holds instance references, the data source writes the variable as a GraphQL instance argument, {space: "...", externalId: "..."}, or as a list for a multi-value variable. Use this to filter on a direct relation. For example, this query lists the time series linked to the assets in the asset variable:

query MyQuery {
  listCogniteTimeSeries(
    filter: {
      assets: {
        containsAny: $asset
      }
    }
  ) {
    items {
      space
      externalId
      name
      description
    }
  }
}

Use ${asset.space} or ${asset.externalId} to insert one part of the reference. To learn how to create a variable that holds instance references, see Emit instance references. To use one variable in the query of another, see Chain variables.

Build

Querying data models with GraphQL in Grafana

Before you begin

Running a query

Using dashboard variables in GraphQL queries

Further reading