Dashboard Data Binding

A dashboard visual can bind to a DatasetReference (survey responses, a Sheet resource) instead of only embedding static chart data — the marquee cross-product integration, applying the datasets standard to the dashboard product. A bound visual resolves its chart data from dataset.readDataset at render time; static visuals work unchanged — binding is additive.

How it works

flowchart LR
  ED["Dashboard Editor blade<br/>Bind-to-data form"] -->|"pick provider → resource →<br/>x column + series rows"| VIS["Visual.dataset<br/>{ reference, query }"]
  VIS -->|render / per-visual refresh| READ["dataset.readDataset"]
  READ --> PROV["DatasetProviderMap<br/>Sheet · SurveyResponses"]
  PROV -->|rows| AGG["client aggregation<br/>count/sum/avg/min/max per series"]
  AGG --> CHART["chart data"]
  PUB["publishResource"] -->|bakes resolved data| SNAP["published snapshot<br/>(no live reads on /view)"]
  VIS -.-> PUB

Data model

Visual.dataset?: VisualDatasetBinding — stored inside the dashboard content blob, no DB columns:

// packages/app/shared/models/dashboard/data/VisualDatasetBinding.ts
interface VisualDatasetBinding {
  reference: DatasetReference;
  query: DatasetQuery; // { xColumn, series: { column, aggregation: DatasetAggregationType }[] }
}

Behavior

• Bind-to-data form (in the Dashboard Editor blade): pick a provider → pick a resource via the shared DatasetReferencePicker → pick the x column and edit multiple series rows (column + aggregation, add/remove).
• Render: a resolver computes chart data from the fetched Dataset per bound visual, with loading and error states per visual and a manual refresh action.
• Publish: published dashboards bake the resolved data into the snapshot (/docs/architecture/publishing) — the public view never issues live dataset reads.

Key files

Notes

• Aggregation runs client-side over the row-capped dataset — no server query language. Revisit only if the row cap becomes a real limit (dataset row cap).
• Fetch on dashboard load + manual refresh; live updates are deferred (realtime dataset refresh).
• A bound visual with a deleted/unreadable source renders an error state, never breaks the dashboard.