> ## 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// 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 records in Grafana > List and aggregate records in Grafana with the Records query tab, including filters, time windows, and unit conversion. Use the Records query tab to read [records](https://docs.cognite.com/cdf/dm/records/concepts/records_and_streams.md) from Cognite Data Fusion (CDF) and show them in Grafana panels. You pick a record view, and the tab returns the records as table rows, or as server-side statistics that you can display as KPIs, categorical plots or time series. ## 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 Records tab](https://docs.cognite.com/cdf/dashboards/guides/grafana/admin_oidc.md#feature-flags). ## Listing records Use the **List** query type to return each record as a row, for example, to show the latest alarms in a table panel. Each column you select becomes a field in the result. ![The Records query tab in List mode with the record view, time window, units, filters, sort, columns, and limit fields](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/dashboards/grafana/records-tab.png) **1. Select a record view** On the Records tab, set Query type to List and select a Record view. The dropdown lists record views with their space and version, and the stream each view reads from. After you select a view, a badge shows the stream, its type, and its maximum filtering interval. **2. Set the time window** In the Time window field, choose which records to read, by their last updated time. See [Choosing a time window](#choose-a-time-window). **3. Add filters** Optionally, select Add filter to match records on any property of the view, or on the record properties `space`, `externalId`, `createdTime`, and `lastUpdatedTime`. See [Filtering records](#filter-records). **4. Choose columns, sorting, and limit** * Columns - the properties to show. Leave it empty to show every view property and the record properties. * Sort by - up to five properties to sort by, ascending or descending. * Limit - the maximum number of records to return, from 1 to 1000. The default is 1000. If a query returns the maximum number of records, the panel shows only part of the matching records and displays a warning. Narrow the time range, add filters, or switch to **Aggregate** if you only need counts. > [!TIP] > > The panel shows one row for each record that matches the time window and filters, with the columns you selected. ## Aggregating records Use the **Aggregate** query type to compute statistics in CDF instead of returning rows, for example, to plot the number of alarms per hour for each site. ![The Records query tab in Aggregate mode, grouping alarms by source name and computing a count and an average severity](https://apps-cdn.cogniteapp.com/@cognite/docs-portal-images/1.0.0/images/cdf/dashboards/grafana/records-aggregate-tab.png) **1. Select Aggregate** Set Query type to Aggregate, select a Record view, and set the Time window. **2. Group the records** Optionally, select Add bucket under Group by. You can add up to four levels: * **Time bucket** groups records into time intervals, from `1s` to `7d`. Choose **Auto** to size the intervals from the panel width and time range, or **Auto · fewer points** for about a quarter as many points. * **Values of** groups records by the unique values of a property. Set how many of the top values to return. The default is 10. **3. Add metrics** Under Compute, select Add metric. You can add up to five metrics. Each metric uses one of the functions **Count**, **Average**, **Min**, **Max**, or **Sum** on a property, and becomes one column in the result. The groups you choose decide the shape of the result, and a badge in the editor shows which shape you get. The table lists the result for each combination of groups. | Group by | Result | | - | - | | Includes a time bucket | One time series for each group | | No time bucket | A table with one row for each group | | No buckets | A single row of totals | To learn more about aggregating records, see the [Records aggregation reference](https://docs.cognite.com/cdf/dm/records/guides/records_aggregations.md). ## Choosing a time window The Time window field selects records by their last updated time and narrows the stream before the data source applies the filters. Streams limit the time range a single request can cover, and the editor shows a warning if the window is longer than the stream allows. To learn about these limits, see [Query time range limits](https://docs.cognite.com/cdf/dm/records/concepts/records_and_streams.md#query-time-range-limits). The table lists the time window options. | Option | Records read | | - | - | | Dashboard range | Records last updated within the dashboard time range. This is the default. | | Custom | Records last updated between the bounds you set. | | None | All records in the stream. Not available for immutable streams. | With **Custom**, set the Window bounds with expressions that resolve to a point in time. You can use ISO timestamps, the operators `+ - * /`, and the anchors in the table. | Anchor | Value | | - | - | | `{{startTime}}` | The start of the dashboard time range | | `{{endTime}}` | The end of the dashboard time range | | `{{now}}` | The current time | | `{{maxFilteringInterval}}` | The maximum filtering interval of the stream, as a duration | For example, set **from** to `{{endTime}} - {{maxFilteringInterval}}` and **to** to `{{endTime}}` to read the most recent window the stream allows. If the dashboard range is longer than the maximum filtering interval, add several queries that each read one slice of the dashboard range. ## Filtering records Filters match records inside the time window and are combined with AND. For each filter, select a property and an operator: **equals**, **is any of**, **between**, **starts with**, **exists**, **contains all**, or **contains any**. Select **NOT** to invert a filter. Filter values accept dashboard variables. For a direct relation whose view names a target, the filter offers a searchable instance picker. To show only the records of the instances a user selects, filter a direct relation on a variable that holds [instance references](https://docs.cognite.com/cdf/dashboards/guides/grafana/variables.md#emit-instance-references). Type the variable, for example, `$asset`, as the filter value: * Use **equals** for a single-value variable, and **is any of** for a multi-value variable. * For a property that holds a list of direct relations, use **contains any** or **contains all**. If a value isn't an instance reference, the query fails with an error that names the property. ## Converting units If a property in the record view declares a unit, the Units field appears. Choose how to convert values: * **Storage units** - return values in the unit they're stored in. * **Unit system** - convert all unit-aware properties to the units of the unit system you select. * **Per property** - select Add conversion to convert individual properties to a target unit. Conversion also applies to filter values, so enter them in the target unit. To learn how CDF converts units for records, see [Unit-aware queries](https://docs.cognite.com/cdf/dm/records/concepts/records_and_streams.md#unit-aware-queries). By default, column and series names include the unit symbol, for example, `temperature (°C)`. Turn off Unit in label to hide it. ## Inspecting the request Select Request preview to see the exact request the panel sends to CDF, with dashboard variables filled in. Select Copy to copy the request body, for example, to reproduce a query with the API. ## Further reading * [About records and streams](https://docs.cognite.com/cdf/dm/records/concepts/records_and_streams.md) * [Get started with Records](https://docs.cognite.com/cdf/dm/records/guides/records_getting_started.md) * [Creating dashboard variables](https://docs.cognite.com/cdf/dashboards/guides/grafana/variables.md)