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

# Query options for time series panels

> Reference for the Data points, Aggregation, Granularity, Gap filling, and Label fields that the Time series, GraphQL, and Synthetic time series query tabs in Grafana share.

The Time series, GraphQL, and Synthetic time series query tabs share the options that decide which data points a panel reads and how each series is named. This page describes those options. To learn how to pick the time series, see the page for each tab.

| Option | Time series | GraphQL | Synthetic time series |
| - | - | - | - |
| [Data points](#read-data-points) | Yes | Yes | Aggregate and Raw |
| [Aggregations](#choose-an-aggregation) | Yes | Yes | Per variable |
| [Granularity](#set-the-granularity) | Yes | Yes | Yes |
| [Gap filling](#fill-gaps) | Yes | Yes | No |
| [Labels](#labels) | Yes | Yes | Yes |

## Data points

In the Data points field, choose one of the options in the table.

| Option | Returns |
| - | - |
| Aggregate | One value for each granularity interval, computed by CDF |
| Raw | The data points as stored |
| Latest | The last data point in the dashboard time range |

Raw and latest values of string time series come back as text, which you can read in table and state timeline panels. For state time series, raw values and the latest value keep each state's code and are labeled from the state set, so the state timeline panel shows the state labels in the order of the state set.

## Aggregations

With Aggregate, select an Aggregation. The list follows the type of the time series: first the aggregations of that type, then the aggregations that every type has.

| Time series type | Aggregations |
| - | - |
| Numeric | Average, Max, Min, Sum, Step Interpolation, Continuous Variance, Discrete Variance, Total Variation |
| State | Most time in state, State duration, State count, State transitions |
| All types | Count, Interpolation, Count (good), Count (uncertain), Count (bad), Duration (good), Duration (uncertain), Duration (bad) |

To learn how CDF computes each aggregation, see [Aggregation functions](https://docs.cognite.com/dev/concepts/aggregation.md#aggregation-functions), [Supported aggregates](https://docs.cognite.com/dev/concepts/resource_types/state_timeseries.md#supported-aggregates) for state time series, and [Status codes](https://docs.cognite.com/dev/concepts/reference/status_codes.md#aggregate-behavior) for the good, uncertain, and bad aggregations.

For state time series, **State duration**, **State count**, and **State transitions** return one series for each state. Use the `{{state}}` token in Label to place the state in the series name. Without the token, the state is appended to the name. See [Labels](#labels).

If a saved query uses an aggregation that the type of the time series doesn't support, the query fails and the error lists the aggregations you can use.

## Granularity

The Granularity field sets the width of each aggregate interval:

* Auto follows the dashboard time range and the panel width. Choose Standard for about one interval per pixel, or Fewer points for intervals about four times wider. Fewer points makes dashboards with many time series load faster. A badge shows the granularity that Auto resolves to.
* Fixed takes a value such as `12h`. The field is pre-filled with the granularity in effect, and flags values that CDF doesn't accept.

To learn more, see [Granularity](https://docs.cognite.com/dev/concepts/aggregation.md#granularity).

## Gap filling

By default, intervals without data points are left out. Use Gap filling to fill them:

* Fixed fills gaps up to a duration, for example, `4h`.
* × granularity fills gaps up to a multiple of the granularity, so the limit follows an Auto granularity as the time range changes. A badge shows the limit sent to CDF.

If a fixed limit is shorter than the granularity, the data source uses the granularity instead and shows a warning. To learn how CDF fills gaps and which aggregations support it, see [Gap filling](https://docs.cognite.com/dev/concepts/aggregation/gap_filling.md).

> [!TIP]
>
> A Grafana time series panel draws its line across intervals without a value. To see the gaps that gap filling leaves open, set the panel's Disconnect values option.

## Labels

The Label field names each series. To name a series from the properties of its time series, write a template with `{{property}}` tokens. The tab fills in each token when the query runs.

If you leave the field empty, the Time series tab names the series `space:externalId`, the GraphQL tab uses the time series name, and the Synthetic time series tab uses the expression with each variable replaced by the name of its time series.

| Token | Resolves to |
| - | - |
| `{{property}}` | A property of the time series in the selected view, for example, `{{name}}`, `{{description}}`, or `{{sourceId}}`, plus `{{space}}` and `{{externalId}}`. |
| `{{property.path}}` | A nested value of a property that holds an object, such as a direct relation, for example, `{{unit.externalId}}`. Lists aren't walked into. |
| `{{unit}}`, `{{unit.symbol}}`, `{{unit.name}}`, `{{unit.quantity}}`, `{{unit.externalId}}` | The unit the data points are plotted in: the target unit if you set one, otherwise the storage unit, looked up in the unit catalog. You can use any property of [CogniteUnit](https://docs.cognite.com/cdf/dm/dm_reference/dm_core_data_model.md#unit). |
| `{{state}}` | For state time series with a per-state aggregation, the state of each series. See [Aggregations](#choose-an-aggregation). |
| `$variable` | A dashboard variable. Grafana fills in variables before the tokens are resolved. |

For example, `{{name}} ({{unit.symbol}})` names a temperature series `Outdoor temperature (°C)`, and switches to `(°F)` when you set the target unit to Fahrenheit.

The tokens tell you when a template doesn't match the data:

* A token for a property the view doesn't have renders as `:property`, so a typo shows in the legend instead of falling back to the default name.
* A property with no value renders as `null`, or as `:property.path` for a nested path, which usually means a relation that isn't set.
* An object renders as JSON. Use a bare `{{unit}}` to see every unit property you can refer to, then narrow the token to the one you want.

Spaces inside the braces are allowed, so `{{ name }}` and `{{name}}` mean the same thing.

The tabs differ in where the tokens read from:

* On the Time series tab, the tokens read the time series instance in the selected view, so every property of the view is available.
* On the GraphQL tab, the tokens read the response, so a field you want in the label must be selected in the query. For example, `{{unit.symbol}}` works only if the query selects `unit { symbol }`. For time series reached through a relation, a field the time series doesn't have resolves against the parent row.
* On the Synthetic time series tab, prefix the token with the variable name, for example, `{{A.name}}` or `{{A.unit.symbol}}`, and `{{A.unit}}` resolves to the variable's Unit if you set one.

## Further reading

* [Plotting time series with the Time series tab](https://docs.cognite.com/cdf/dashboards/guides/grafana/timeseries.md)
* [Querying data models with GraphQL in Grafana](https://docs.cognite.com/cdf/dashboards/guides/grafana/graphql.md)
* [Computing synthetic time series in Grafana](https://docs.cognite.com/cdf/dashboards/guides/grafana/synthetic_timeseries.md)
* [Aggregation](https://docs.cognite.com/dev/concepts/aggregation.md)