Core concepts

A short glossary for the terms used throughout these docs.

Data source

A connection to one external database, warehouse, or API — the credentials and options needed to reach it (host, user, database name, and so on). Every query runs against exactly one data source. Access to a data source is granted per group, so a group only sees the sources it’s been given.

Query

A saved SQL statement against a data source. A query can take parameters (named placeholders filled in at run time), can hold reusable snippets, and can be put on a schedule so its result refreshes automatically instead of only on demand.

Queries have version history: every save creates a new version, and a query can be in a draft state — edited but not yet published — so you can iterate without changing what dashboard viewers currently see.

[!NOTE] Running a query can return an immediate cached result or hand you back a job to poll, depending on whether a fresh run was needed. See the async query model if you’re calling this through the API rather than the editor.

Visualization

A rendering of a query’s result: a table, a line/bar/area/pie/scatter chart, a counter, or a funnel. A visualization always belongs to one query, but the same query can have several visualizations.

Dashboard

A grid layout of visualizations (called widgets once placed on a dashboard), optionally with its own parameters that filter every widget on the page at once, regardless of which query backs each one.

Alert / Monitor

A threshold check against one column of a saved query’s result — for example, “notify me if this value goes above X.” Alert and monitor are the same thing: the API and the object itself are always called a monitor, while “alert” is the everyday name for what it does. Notifications go out over email, Slack, webhook, PagerDuty, Mattermost, Teams, Discord, Google Chat, or Datadog.

There’s no separate “data observability” mechanism — freshness, row count, null rate, and duplicate checks are just this same monitor mechanism pointed at a query written to answer one of those questions. See Data observability monitors for the query recipes.

Sharing

Every query and dashboard has its own access control: per-user or per-group permissions, a public secret-token link for sharing outside the organization, or an iframe embed for pasting into another page.