Dashboards
A dashboard is a shareable, URL-addressable layout of blocks that read from your data, run on demand, and persist at the URL. Humans and agents work side by side; a change to one block propagates to anything downstream. Dashboards carry their own permissions and a full audit trail of activity.
Displayed and internal blocks
Section titled “Displayed and internal blocks”A dashboard is a forest of blocks where some are displayed in the grid and the rest live as internal nodes upstream. A SQL block that aggregates rows can stay hidden; the chart that visualizes its output is displayed. Internal blocks are reached only as upstreams of a displayed root.
Promote a block to the grid with dashboard_set_displayed. The block is placed as a full-width row at the bottom by default. Use dashboard_set_layout to arrange the rows you want.
Layout
Section titled “Layout”Layout is an ordered list of rows, top to bottom. Each row holds one to four displayed blocks side by side. Rows split the 12-column width evenly unless you override cols. Each row has an optional pixel height; the default is short for control / markdown rows, around 290px for a chart. Content fits to the row: a chart redraws to fill it; anything taller scrolls inside it.
Set the whole layout in one idempotent call with dashboard_set_layout. Hidden blocks may not appear in the layout, and each displayed block must appear at most once.
Controls
Section titled “Controls”Controls are normal blocks with a particular terminal type. Today there are two:
filter-daterange— emits a JSON-encoded date range ("7d",{"start": ..., "end": ...}).param-enum— emits a single value picked from a list of options.
Subscribers read the control’s value through config.source (or by referencing it in config.inputs). SQL blocks bind named control values into the query as parameters: write $name in the SQL, declare it in config.inputs, and the engine substitutes the current value at run time.
To verify a control wire without persisting anything, call dashboard_run_block on the downstream block with filter_overrides={<filter_block_id>: <value>}. The cascade binds those values for the call without changing what’s stored.
Catalog
Section titled “Catalog”The catalog is the set of named sources a SQL block can query: imported files, pushed tables, block outputs, and tables exposed by connected warehouses or app databases. New sources land in the catalog when they are created. Renaming a source updates downstream references.
Visibility
Section titled “Visibility”Dashboards can be private or viewable by anyone with the link. Editing always requires authentication and permission.
See Sharing and permissions for visibility modes and roles.
Storage
Section titled “Storage”Each dashboard keeps loaded data and block outputs so it can be reopened and run again. Imported CSVs, pushed tables, uploaded files, and completed block outputs become sources in the dashboard catalog.
Run state
Section titled “Run state”Runnable blocks show their current status and latest output. Running a block updates that current result and refreshes downstream consumers.
Live collaboration
Section titled “Live collaboration”You can be in a dashboard with other people, with agents, or both. You see who else is there and what they’re working on. While someone has a block open, no one else can edit it. When they’re done, the change goes through, and any block that uses its output updates with it.