SQL REST API#

The SQL REST API exposes three endpoints: one to run a bounded query, one to export an unbounded result, and one to introspect the queryable surface.

Method

Path

Purpose

POST

/sql/v1/query

Run a query and get the result back

POST

/sql/v1/query/export

Run an unbounded query and get a download URL for the result

GET

/sql/v1/catalog

List queryable tables, columns, and allowed functions

Each path hangs off your deployment’s REST API URL, the same base the rest of the platform REST API uses. Copy it from the API keys page in Settings.

Authentication#

All three endpoints take a bearer token in the Authorization header. Use an organization API key:

Authorization: Bearer <your-api-key>

See API keys setup for how to obtain a key. The config file/command line set-up is not required, just obtaining an API key.

What you can query#

Queries are validated before execution with key rules listed below:

  • Read-only, single statement. One SELECT per request. Multi-statement requests are rejected, as is anything that would change schema (CREATE, ALTER, DROP) or data (INSERT, UPDATE, DELETE).

  • Only table, columns, and functions in the catalog are permitted. The catalog can be viewed from the console or call GET /sql/v1/catalog for the current list.

  • Telemetry tables must be scoped by dataset_rid. The points_double, points_int, points_string, points_struct, logs, and channels tables each require a dataset_rid predicate, or a join on dataset_rid to a metadata table. The metadata tables (assets, runs, run_assets, datasets, events, and event_assets) have no such requirement.

Joins work across any number of metadata tables, and between metadata and telemetry tables. Telemetry tables combine with each other through IN subqueries and PIVOT. See Writing queries.

Every request needs view access to the workspace named in workspace_rid, and reads only that workspace’s data. Telemetry queries also need read access to each dataset they name.

Permitted operations#

Next steps#