Grafana plugin#

Nominal’s data source plugin 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:

grafana cli plugins install nominal-nominalds-datasource

Add the data source#

API keys setup 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 in the data source’s workspace, and needs a base URL starting with https. Filter telemetry tables such as points_double on dataset_rid, and use the plugin’s macros for the panel’s time range:

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, and its SQL guide has more SQL patterns, including annotations.

Grafana® is a registered trademark of Grafana Labs.