Schema#

The SQL interface exposes a fixed set of tables. Unknown tables and columns are rejected before a query runs, and GET /sql/v1/catalog returns the live list.

These tables are the platform’s own data model made queryable, so the names will be familiar if you have used Nominal through the app. Reading the data model overview is not a prerequisite, but it explains what assets, runs, datasets, and tags are for, which makes the schema below easier to navigate. The glossary covers the rest of the terms.

The tables fall into two groups, and the difference determines both how you query them and which functions you can use.

Telemetry tables#

Time-series and log data. Every query against these must filter by dataset_rid.

Table

Value type

Purpose

points_double

DOUBLE

Floating-point time series

points_int

BIGINT

Integer time series

points_string

VARCHAR

String and enum time series

points_struct

VARIANT

Structured, JSON-valued time series

logs

Timestamped log messages

channels

The channels in a dataset, with their tags and data types

Any dataset can also be read as a table of its own, named by its quoted RID, as in FROM "<ri.catalog.instance.dataset.identifier>". It reads all of the dataset’s points and log entries without a dataset_rid filter. See Reading a whole dataset.

Metadata tables#

Descriptive records about assets, runs, datasets, and events. No scoping requirement, so these are where you start when you don’t yet know a dataset_rid.

Table

Purpose

assets

Physical things you collect data from

runs

Time ranges of activity

run_assets

Which assets each run covers

datasets

Data sources, with their time bounds

events

Points or intervals of interest

event_assets

Which assets each event is associated with

Your query log#

query_history sits outside both groups and records the SQL queries you have run. It needs no scoping predicate. You read your own queries from every workspace in your organization, and org admins read everyone’s.

Column types#

Columns report these logical types:

Type

Notes

TIMESTAMP

Nanosecond precision in the telemetry tables, microsecond precision in the metadata tables. See Reading timestamps for how to read it in Python.

VARCHAR

Text.

DOUBLE

Floating point.

BIGINT

64-bit integer.

MAP

Key-value pairs. tags and args map strings to strings, while properties holds typed values. See Properties.

ARRAY

Repeated values, of strings unless noted.

VARIANT

JSON, in points_struct.value. See points_struct.

Whole MAP and ARRAY columns from the metadata tables come back as text, such as [hotfire, propulsion] for labels. Index into them in the query, as in labels[1] or properties['<key>']['value'], to get the parts.

Tags#

The points_* and logs tables each carry a tags column of type MAP, holding the key-value pairs recorded alongside a series. Tag keys are arbitrary, set at ingest time, and vary between datasets. See Tags for how they are assigned, and Filtering by tag for how to query them.

Next steps#