Concepts

Nine words, used precisely throughout. Most confusion about SQLDesk is really confusion between two of these — a parameter and a filter especially.

Data source

A connection to somewhere data lives: a Postgres database, a Trino cluster, a BigQuery project, a Google Sheet. It holds the credentials, which are encrypted, and it belongs to one or more groups. Whoever is in a group can use the data source; whoever is not cannot see it at all.

Query

SQL, saved, against one data source. A query has an owner, can be scheduled, forked and published.

Query result

What came back the last time a query ran, kept in SQLDesk's own database. Opening a dashboard shows the stored result rather than running the query again, which is why a dashboard opens quickly and why what it shows has an age on it.

Visualization

A way of drawing one query's result — a table, a line chart, a counter, a gauge. A query can have several, and they all draw the same rows. Changing the SQL changes all of them at once.

Dashboard and widget

A dashboard is a grid of widgets. A widget is either a visualization from some query, or a textbox. Two widgets showing the same query share one fetch, so a dashboard with five views of one query fetches its stored result once.

Parameter

A hole in the SQL, written {{ region }}. The value is substituted before the query runs, so the warehouse does different work. Parameters can be text, numbers, dates, or a list of allowed values.

Filter

Not a parameter. A filter narrows rows already fetched, in the browser, by naming a column something::filter in the SELECT. Nothing is re-run. Use a parameter to change what the warehouse does; use a filter to slice what it already returned.

Group

How permission works. A user belongs to groups; a data source is available to groups, fully or view-only. Viewing and running is groups all the way down. Editing a query or dashboard can also be granted to named people, once an admin turns on Enable experimental multiple owners support under Settings → General.

Alert

A rule over one query's result — a column, a comparison, a value — and a list of destinations. It is checked after the query runs, not on a timer of its own, so an alert on an unscheduled query only fires when somebody runs it.