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

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

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

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

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

We support two modes:

• private. Only the owner and explicit grantees can view.
• link_view. Anyone with the URL can view, anonymously and read-only. Editing still requires authentication. A link_view dashboard also exposes preview metadata, so pasted links render as cards in Slack, Linear, and similar tools.

Set visibility from the UI or via dashboard_set_visibility.

Permissions

We currently support three roles:

• Owner. Created the dashboard (or had it transferred). Can change visibility, transfer, or delete.
• Editor. Can add, remove, and edit blocks. Cannot change visibility.
• Viewer. Read-only.

Roles are dashboard-scoped. A user can be an owner of one dashboard and a viewer of another.

Storage

Each dashboard keeps its own cache of loaded data. Imported CSVs, pushed tables, and uploaded files are stored alongside block outputs (Parquet today, with other formats supported over time). Deleting a dashboard removes its cached data.

Runs and history

A run is recorded with a status, an output, the inputs it was computed against, and the actor that triggered it. Runs are immutable. The dashboard retains its full run history, so a prior result can be opened and compared against the current one.

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.