# Grafana plugin

Nominal’s [data source plugin](https://grafana.com/grafana/plugins/nominal-nominalds-datasource/) for Grafana® shows Nominal channels in Grafana dashboards and Explore. It needs Grafana 12.1 or later and a Nominal API key.

## Install the plugin

In Grafana, go to **Administration** > **Plugins and data** > **Plugins**, search for **Nominal**, open it, and select **Install**. On a Grafana server you run yourself, you can install it from the command line instead:

```shell
grafana cli plugins install nominal-nominalds-datasource
```

## Add the data source

[API keys setup](https://dev.nominal.io/quickstart/api-keys-setup.md) shows where to find your API key, base URL and workspace RID.

1. In Grafana, go to **Connections** > **Data sources**, and add the **Nominal** data source.
2. Set **Base URL** to your base URL, including its `/api` path, such as `https://api.gov.nominal.io/api`.
3. Paste your API key in **API Key**.
4. Set **Workspace RID**. Asset search then lists only that workspace’s assets, and SQL queries run in it. Left empty, search covers every workspace your key can access, and SQL queries run in the key’s default workspace.
5. Select **Save & test**. It checks that Grafana can reach Nominal with your key and, if you set a workspace RID, that the key can see the workspace.

## Query a channel

Each query uses either **Compute** or **SQL**, chosen with **Query API** in the query editor. A Compute query picks one channel from menus. A SQL query runs a Nominal SQL query you write. One panel can mix both.

For a Compute query, pick an **Asset**, by searching for its name or pasting its RID, then a **Data scope** on it, then a **Channel**. What comes back depends on the channel’s type:

- **Numeric:** the aggregations you pick in **Aggregation(s)**, per time bucket: **Mean** (the default), **Min**, **Max**, **First**, **Last**, **Count** or **Variance**. Each is its own series.
- **String:** the most frequent value in each time bucket. A **State timeline** panel shows it over time.
- **Log:** every entry, for a **Logs** panel.

A SQL query runs [Nominal SQL](https://dev.nominal.io/sql-guides.md) in the data source’s workspace, and needs a base URL starting with `https`. [Filter telemetry tables](https://dev.nominal.io/sql-guides/writing-queries.md#scoping-telemetry-queries) such as `points_double` on `dataset_rid`, and use the plugin’s macros for the panel’s time range:

```mysql
SELECT $__timeGroup(ts) AS "time", channel, AVG(value) AS "value"
FROM points_double
WHERE dataset_rid = '<dataset rid>'
  AND $__timeFilter(ts)
GROUP BY 1, 2
ORDER BY 1
```

`$__timeFilter(ts)` keeps the rows in the panel’s time range, and `$__timeGroup(ts)` buckets them at the panel’s interval. With **Format** set to **Time series**, numeric columns are plotted and string columns label the series. **Table** shows the rows as they come back.

## Dashboard variables

Variables let one dashboard switch between assets, data scopes and channels. Add a dashboard variable of type **Query** that uses your Nominal data source. With **Mode** on **Catalog**, its query is one of these:

- `assets`: every asset in the workspace
- `assets(<search>)`: the assets matching the search, such as `assets(engine)`
- `datascopes(${asset})`: the data scopes on the asset in `$asset`
- `channels(${asset}, ${datascope})`: the channels in the asset’s data scope in `$datascope`
- `channels(${asset})`: the channel names in all of the asset’s data scopes, each once

A query can use the variables defined before it, as these use `${asset}`, and runs again when they change. With **Mode** on **SQL**, a Nominal SQL query fills the variable: one column gives each option’s label and value, or columns named `__text` and `__value` give them separately. In a SQL query, write a variable as `${<name>:sqlstring}`, such as `channel IN (${channel:sqlstring})`.

## Troubleshooting

If **Save & test** fails, check that **Base URL** ends in `/api` and that your API key is valid.

If an asset is missing from search, it may be in another workspace: search lists only the data source’s workspace. An asset in another workspace that your key can access still works if you paste its RID.

The plugin’s source is at [nominal-io/grafana-plugin-public](https://github.com/nominal-io/grafana-plugin-public), and its [SQL guide](https://github.com/nominal-io/grafana-plugin-public/blob/main/docs/sql.md) has more SQL patterns, including annotations.

Grafana® is a registered trademark of Grafana Labs.