The annotation model
A dashboard is a .sql file. It has two kinds of statement:
SELECT, one chart: the query on this page, drawn by the dashboard CLI.- Setup: any statement without a role cast (
CREATE TABLE,INSTALL,LOAD,SET VARIABLE, …). It runs for its effect, once, on a shared connection. - Panels: a
SELECTwhose output columns carry::ROLEcasts. Each one becomes a chart, a KPI tile, a table, an input or a block of text.
CREATE TABLE sales AS FROM read_parquet('sales.parquet'); -- setup
SELECT region ::XAXIS, sum(revenue) ::BARCHART, -- a panel 'The North sells most'::TITLEFROM sales GROUP BY ALL ORDER BY 2 DESC;How a panel reads
Section titled “How a panel reads”- The measure’s cast picks the chart.
::BARCHART,::LINECHART,::HEATMAP,::MAP, … — the chart catalogue has one page for each kind, with the data it needs. - The other columns say where and how each row is drawn. These are encodings:
::XAXIS,::YAXIS,::CATEGORY(colour / series),::SIZE,::LABEL,::FACET(small multiples),::YMIN/::YMAX(intervals). - Constant columns set options.
'Revenue by week'::TITLE,'€'::YFORMAT,'quantile 5'::CLASSES: one value for the whole panel, written in the sameSELECT. - SQL does the work. One row per mark: aggregate with
GROUP BYand sort withORDER BYin SQL, not in the chart. Measures are cast toDOUBLEfor you, sosum()of aHUGEINTdraws as a number.
Statements that shape the page
Section titled “Statements that shape the page”Some roles are a statement of their own and act on what follows. They are directives:
SELECT 'Overview'::TAB; -- a tab: the panels after it live under itSELECT 8::COL; -- the next panel is 8 of 12 columns wideSELECT DISTINCT region ::DROPDOWN FROM sales; -- an input → getvariable('region')Write a directive as its own statement, never as an extra column on a chart’s SELECT. dashboard --check --strict flags one written inline (layout/next-panel). See Layout and tabs and Inputs and interactivity.
The file’s header
Section titled “The file’s header”-- @… comment lines at the top name and file the dashboard: -- @title (a plain business question), -- @description, -- @group, -- @tags, -- @owner, -- @certified. The builder’s sidebar and the servers’ start pages read them. All header lines →
Check it
Section titled “Check it”dashboard --check my.sql # which panels break, are empty, or break a design ruledashboard --check --strict my.sql # …and fail on warnings (for CI)dashboard --roles # every role, groupedThe role reference lists all of them (generated from the role registry, src/roles.rs).