> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Querying data models with GraphQL in Grafana

> Run a GraphQL query against a data model with the GraphQL query tab in Grafana to show the instances it returns and plot the CogniteTimeSeries among them.

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](https://docs.cognite.com/cdf/dashboards/guides/grafana/timeseries.md). To learn how to write GraphQL queries against data models, see [Query data with GraphQL](https://docs.cognite.com/cdf/dm/dm_graphql/dm_graphql_querying.md).

## Before you begin

* Make sure an administrator has [set up the data source](https://docs.cognite.com/cdf/dashboards/guides/grafana/admin_oidc.md) and [turned on the GraphQL tab](https://docs.cognite.com/cdf/dashboards/guides/grafana/admin_oidc.md#feature-flags).

## Running a query

![The GraphQL query tab with a query that lists numeric time series and the response next to it](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/dashboards/grafana/graphql-tab.png)

**1. Select the data model and version**

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

**2. 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.

**3. 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:

```graphql theme={"languages":{"custom":["/_languages/kuiper.json"]}}
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](https://docs.cognite.com/cdf/dm/dm_graphql/dm_graphql_querying#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.

> [!TIP]
>
> 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.

**4. 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.

**5. 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](https://docs.cognite.com/cdf/dashboards/guides/grafana/query_options.md).

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](https://docs.cognite.com/cdf/dashboards/guides/grafana/query_options.md#labels).

> [!TIP]
>
> 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:

```graphql theme={"languages":{"custom":["/_languages/kuiper.json"]}}
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](https://docs.cognite.com/cdf/dashboards/guides/grafana/variables.md#emit-instance-references). To use one variable in the query of another, see [Chain variables](https://docs.cognite.com/cdf/dashboards/guides/grafana/variables.md#chain-variables).

## Further reading

* [Query options for time series panels](https://docs.cognite.com/cdf/dashboards/guides/grafana/query_options.md)
* [Creating dashboard variables](https://docs.cognite.com/cdf/dashboards/guides/grafana/variables.md)
* [Query data with GraphQL](https://docs.cognite.com/cdf/dm/dm_graphql/dm_graphql_querying.md)