Dashboard Management
Dashboards are the canonical SQL-backed Analytics resources. New dashboards, saved analyses, reports, and bespoke extensions are represented as dashboard artifacts—not as separate user-facing Analytics objects. Legacy analysis tables and actions remain available only for compatibility.
Storage
Current storage:
| Table | Purpose |
|---|---|
dashboards |
Explorer and SQL dashboard records |
dashboard_folders |
Personal and shared SQL dashboard folders |
dashboard_views |
Saved filter presets per dashboard |
dashboard_shares |
Standard framework share grants |
dashboard_folder_shares |
Standard folder share grants |
dashboard_revisions |
Bounded dashboard history snapshots |
analyses |
Saved ad-hoc analysis records |
analysis_revisions |
Bounded analysis history snapshots |
analysis_shares |
Standard framework share grants for analyses |
Legacy settings keys such as u:<email>:dashboard-*, u:<email>:sql-dashboard-*, o:<orgId>:sql-dashboard-*, and adhoc-analysis-* are still read as a fallback and copied into SQL on access. Do not create new dashboard settings rows.
Dashboard folders
Dashboard folders are SQL-backed, access-scoped containers for organizing SQL
dashboards from /dashboards:
personalfolders are private to their owner.sharedfolders are organization-visible and require an active organization.- Use
list-dashboard-folders,create-dashboard-folder, andset-dashboard-folderfor folder reads and membership changes. - A folder never expands dashboard access. A personal folder can contain only an owned private dashboard; a shared folder can contain only an org-visible dashboard. Use the normal dashboard sharing actions separately.
For organization-wide consolidation, use migrate-analytics-artifacts first
with dryRun: true. The write requires an organization owner/admin and the
exact confirmation token MIGRATE_ANALYTICS_ARTIFACTS. It materializes
organization-scoped legacy settings, creates dashboard blocks for saved
analyses and standalone extensions, archives exact duplicates, copies shares,
and removes legacy settings keys only after SQL rows are materialized. Source
rows remain recoverable. Private member-only rows are intentionally outside
this organization-scoped operation.
Use mutate-dashboard for existing dashboard edits. It resolves the current
user/org context, validates the resulting config, writes the SQL-backed record,
syncs collab, and returns a compact result with a verified flag. Use
update-dashboard for new full-config saves, UI full-config saves, or explicitly requested low-level
JSON-pointer edits.
Every meaningful dashboard save snapshots the previous state into
dashboard_revisions. Use list-dashboard-revisions to inspect available undo
points and restore-dashboard-revision to restore one; restore snapshots the
current state first, then syncs open dashboard editors.
Each revision's changes names what the save that left it behind changed
(panel-added, column-resized, filter-changed, version-restored, and so
on), so restoring it undoes that change and every later one. To answer "undo
the column I widened", pick the revision whose changes match instead of
guessing from times. changesStatus is absent for revisions saved before
changes were recorded and unreadable when the stored list is corrupt; say you
can't tell what those changed rather than treating them as empty.
On the page, an editor's own saves show a toast that names the change its Undo
takes back, says "Saved for everyone" (org or public visibility; "Saved" when
private), and counts the others who have the dashboard open. That Undo
restores the revision its save left (a full-config update-dashboard save
returns it as revisionId), but only while the dashboard is as that save left
it: once someone else has saved, it fails rather than taking their change back.
For "undo my last change" in chat, restore the newest revision from
list-dashboard-revisions. The History panel shows each revision's first
change with "+N more".
Saved analyses follow the same undo model with analysis_revisions,
list-analysis-revisions, and restore-analysis-revision.
Dashboards open in View mode. An editor switches the header toggle to Edit
before drags, panel resizing, renames, column edits, and adding, editing, showing or hiding key
dates and data notes on the page save for everyone; the chat context reports the current
mode. A table column width dragged in View mode is
stored only in that person's browser, so "widen this column for me" is a drag
in View mode, not a dashboard change. config.columns[].width is the shared
width everyone sees; set it only when asked to change the dashboard itself.
Never use db-patch, raw SQL, or settings-key edits to create or modify a
dashboard config. Those bypass the dashboard action's access checks, SQL
validation, collab sync, and verification. If a dashboard action fails
because the argument shape was wrong, fix that action's arguments and retry
once — do not switch to db-patch or raw SQL.
GitHub folder sync
A linked folder mirrors its SQL dashboards to <path>/<dashboardId>.json in a
GitHub repo. Read docs/dashboard-github-folder-sync.md before changing or
explaining it.
- Run
preview-dashboard-folder-github-syncbefore any sync. It writes nothing. apply-dashboard-folder-github-syncpulls from GitHub. It writes only the panels, order, and settings that changed on the GitHub side.export-dashboard-folder-to-githubopens one PR with the app's changes. It refuses while an earlier export PR is still open.configure-dashboard-folder-github-synclinks or unlinks a folder. It stores no credentials.- A unit changed on both sides is a conflict. It is reported and not applied. Do not resolve it by overwriting either side without asking the user.
- Explorer dashboards, sharing, and deletions never sync. A synced dashboard cannot be permanently deleted; archive it or unlink its folder first.
Valid Panel Sources
panel.source is a backend selector, not a table name. It must be one of:
| Source | Query shape |
|---|---|
bigquery |
Literal warehouse SQL. Table names belong inside the SQL string. |
ga4 |
JSON descriptor for the Google Analytics Data API. |
amplitude |
JSON descriptor for an Amplitude query. |
first-party |
Read-only SQL over this template's analytics_events table, usually via query-agent-native-analytics. |
Do not use app-db as a dashboard source. For first-party events collected through /track, use source: "first-party" or the query-agent-native-analytics action rather than raw internal db-query.
Per-article content metrics also read through first-party:
analytics_content_items (one row per article, with author and publish date),
analytics_content_metric_snapshots (one value per item, day and metric), and
analytics_content_collection_runs (one row per daily collection step). A
daily job fills them, so a panel over them never calls BigQuery or a provider.
A missing snapshot means "not collected", never zero: show a step's latest run
status (failed, cost_limited, not_configured) instead of rendering a gap
as 0. These tables cannot be joined with analytics_events in one query. Turn
collection on with configure-content-collection, check it with
get-content-collection, and rerun a step with run-content-collection.
Metrics are ga4_pageviews (per blog article) and search_console_clicks /
search_console_impressions (per article, plus non-article pages stored as
search_console items). GA4 reads the collection's ga4.propertyId, set with
configure-content-collection --ga4PropertyId <numeric-id>; it never falls back
to the shared GA4_PROPERTY_ID used by other dashboards. An unset property
reports not_configured without querying. Changing the property starts a fresh
90-day backfill; its first successful save replaces the previous property's
pageview history, including dates outside that window. Failed replacements
keep the saved history. Pass ga4PropertyId: null to clear it; omitted settings keep
their saved values. Search Console data is two to three days late, so the
newest days have no row yet; read them as still arriving. Search Console
collection stays off until a property owner adds the service account that
get-content-collection returns as serviceAccount.email; then set its
searchConsoleSites and turn it on.
The signups step writes signups_first_touch per article: people who
first landed on the article and later signed up, on the day of that first
visit, so a window's days add up to its total. It is the only step that reads
the warehouse. It stays not_configured until configure-content-collection
sets its signups tables, signupSource, signupsSince and
maxBytesBilled. Measure the cap with estimate-content-signups-cost (a dry
run, free) and get the spend approved before turning the step on. Each run
dry-runs first, stops as cost_limited without querying when the estimate is
over the cap, and runs the join with that cap as BigQuery's billing limit.
The catalog's "Content" dashboard (content-view) is the reference for these
tables: start from its panels before writing new content SQL. Its Missing
data callout has no tab, so it shows on every tab. It joins the expected
sources to their latest run in the last 30 days, so it names each source whose
run failed, hit the cost cap or isn't connected, and each one with no run in
that window; keep that pattern rather than letting a missing row read as
"nothing missing". The
first-party SQL policy rejects functions outside its allow-list (for example
concat_ws) and reads CASE ( as a function call, so join a status column
instead of a scalar subquery inside CASE. Its parser also rejects VALUES
lists and IS DISTINCT FROM: list fixed rows with SELECT … UNION ALL and
compare with COALESCE(x, '') <> …. Its daily signups chart uses wide
rows (yKeys), not pivot: a pivot fills a missing series with 0, so an
uncollected day would draw as a zero instead of a gap. Pivot only where a
missing row is a real zero, like an author's week without signups. Content is a
built-in: turning collection on with configure-content-collection lists it
in the organization's Dashboards at content-view (contentDashboardId in the
result). It is read-only; build on it with duplicate-dashboard.
There is no dbt Semantic Layer panel source. For a Semantic Layer metric, answer in chat with query-dbt-semantic-metric; build a warehouse panel only on a table the owner names.
AI-generated first-party panels are dashboard-time-bound by default. Set
config.timeScope to "dashboard" and include the matching dashboard time
filter in the SQL. The allowed values are:
dashboard: use the dashboard-selected time range; the default for ordinary metrics.fixed-window: use an explicit bounded window independent of the dashboard filter.cohort-history: use the bounded history of an explicitly defined cohort.all-time: scan all available history; use only when the user requests it and putall-time,lifetime, orhistoricalin the title or description.
{{timeRange}} requires an explicit matching filters entry with
id: "timeRange" and type: "select". {{<id>Start}} and {{<id>End}}
require a matching filters entry with that id and type: "date-range".
Do not rely on undeclared time variables. Server validation rejects unbound
first-party SQL, so declare the filter or choose an explicit non-dashboard
scope before saving.
A bound anywhere in the SQL is not the same as every CTE having its own
bound. If a panel has multiple top-level CTEs (WITH a AS (...), b AS (...)) and more than one of them reads analytics_events, EVERY one of
those CTEs needs its own {{timeRange}}/{{<id>Start}}/{{<id>End}}
reference or literal date bound — not just the final SELECT or one sibling
CTE. A CTE that computes something like "this user's first-ever active day"
by scanning analytics_events with no bound at all will full-table-scan on
every render even though the panel looks time-bound overall (root cause of
a 2026-07-25 production incident: several dashboards had exactly this shape).
Server validation checks each top-level CTE independently now, so this fails
at save time — but write it right the first time: bound every CTE, or use
config.timeScope: "cohort-history" only for a CTE that is genuinely
defining a cohort (e.g. a first-seen date), never as a way to skip bounding
an ordinary activity scan.
Creating A Dashboard
When the user asks for a dashboard:
- Start from the preloaded
<resource scope="analytics-catalog">references (catalog-first), else onefind-data. If a relevant entry exists, use itstable,columns,queryTemplate, and gotchas verbatim. - If a metric definition, date range, or grain is ambiguous and the choice would change the panel's numbers, use the
ask-questionclarifying tool once before building. Skip it when the dictionary or the user already settled it. - If a metric is not documented, do not guess column names and do not ask the user for them. Find the table and columns with
search-bigquery-schema(or the provider's own schema action), then propose a dictionary entry withsave-data-dictionary-entry. - Build a complete
SqlDashboardConfigwithnameandpanels. Optionally set top-levelcolumns(1–6, default 2) to control how many grid columns the panels before any section use. - Every panel needs
id,title,source,chartType,width, andsql.widthis the number of grid columns the panel spans (1..6, clamped to the active section's column count).heightis optional; when set, it is 1–6 units of 180px, and when omitted the panel sizes to its content. Section panels skipsourceandsqland may set their owncolumns(1–6) to override the dashboard default for the panels following the section. Extension panels (chartType: "extension") also skipsourceandsql; useconfig.extensionIdfor ordinary author-selected shared embeds. Useconfig.extensionSlotIdonly when the user explicitly asks for a personal/per-viewer slot (see "Embedding An Extension As A Panel"). - Persist with
update-dashboard(load it withtool-search— it is not on the initial tool surface), not raw SQL or settings writes. For a large first-party dashboard, loadcompose-dashboardthe same way in onetool-searchcall. - Navigate to it with
pnpm action navigate --view=adhoc --dashboardId=<id>.
An explicit dashboard request authorizes the complete non-destructive build in the same turn. After querying or scaffolding, continue through extension-data seeding/refresh, dashboard save/embed, and navigation; do not ask whether to proceed or leave an empty Custom Block shell. Ask only when metric scope/grain is materially ambiguous, the change is destructive, or it has an external side effect such as sending email or outreach.
Layout is always 1 column when the available content width is below the md threshold (panels stack), then expands to the configured column count at/above it. The grid uses a container query, so it also stacks when the agent sidebar narrows the content pane — not only at narrow viewports. So picking 3 or 4 columns is fine — the renderer keeps narrow layouts readable automatically.
In Edit mode, drag a panel's right edge to change its grid width and its bottom edge to set a fixed height. Width is saved as grid columns; height is saved in 180px units. Existing panels without height keep content-based height until resized.
pnpm action update-dashboard --dashboardId weekly-metrics --config '<full json>'
pnpm action navigate --view=adhoc --dashboardId=weekly-metrics
The save path dry-runs BigQuery panels before persisting. If validation returns a provider error, fix the query and retry. A sql_validation_unavailable error (status 503) means the validator could not run, not that the SQL is wrong: retry the same write, or report the outage, without rewriting the query. Never work around validation by writing directly to a table.
Replicating Or Adapting Another Dashboard
When the user asks to replicate, clone, or adapt an existing dashboard into a new
one, call search-dashboard-references with focused terms first. It searches
accessible active saved dashboards (ids, names, descriptions, serialized config),
including legacy ones. Inspect each result with get-sql-dashboard when kind
is sql, or get-explorer-dashboard when it is explorer. A result is a
reference, not proof its source is authoritative for the new request: check the
provider and scope the user asked for before copying its source semantics, and do
not route a replication request to first-party Analytics by default. This applies
to a new dashboard, not to editing the dashboard that is already open.
Dual-Axis Charts
line, area, and bar panels can plot series against two y-axes. Reach for
this whenever series share an x-axis but not a unit — a count next to a rate, or
revenue next to a conversion percent. On a single axis the smaller series
flattens into the baseline and reads as "no data."
{
"id": "signups-vs-conversion",
"title": "Signups vs conversion rate",
"source": "first-party",
"chartType": "line",
"width": 1,
"sql": "SELECT day, signups, conversion_rate FROM ...",
"config": {
"timeScope": "dashboard",
"xKey": "day",
"yKeys": ["signups", "conversion_rate"],
"yFormatter": "number",
"rightYKeys": ["conversion_rate"],
"rightYFormatter": "percent"
}
}
rightYKeysnames series fromyKeys; everything unnamed stays on the left.rightYFormatterdefaults toyFormatterwhen omitted.- Each axis is labelled with its series names (up to two per side), and tooltip values use the formatter of the axis the series belongs to.
- At least one series must remain on the left. If
rightYKeysnames every series, or names a column the query never returned, the panel falls back to a single axis and shows a config warning rather than dropping the series. - Scheduled email reports render the same two scales, so a dual-axis panel is safe to put on a subscribed dashboard.
Key-Date Event Markers
Key dates mark a launch, release, or product change on line, area, bar,
and combo charts with a date x-axis. Do not add a fake series or an extension
for this. They live in two places:
- Key-date sets hold moments that matter across charts, such as Launches or
Product changes. A set belongs to the organization (to the user when there is
no organization) and draws on every time chart of every dashboard. Read sets
with
list-key-dates, passingdashboardIdfor the ones a dashboard draws; add or edit a date withsave-key-date(name the set withsetNameand it is created if missing); rename or create a set withsave-key-date-set; remove withdelete-key-dateordelete-key-date-set. Prefer a set to copying one date into many panels. - Panel events in
config.eventshold a date that matters to one chart only, in the same shape:
"config": {
"events": [
{ "date": "2026-10-14", "time": "00:01", "timeZone": "America/Los_Angeles", "label": "Product Hunt live" },
{ "date": "2026-10-14", "time": "12:00", "timeZone": "America/New_York", "label": "Launch posts on X, LinkedIn" }
]
}
A dashboard leaves sets off its charts with config.annotations, set through
mutate-dashboard's setDashboard({ annotations: { hiddenKeyDateSets: [setId, ...] } }).
The list replaces the sets already hidden, so include those that stay hidden;
the hidden data notes are kept. In Edit mode, people do the same from the dashboard
header's Annotations menu, which also adds and edits key dates and sets.
- Each event is
{ date: "YYYY-MM-DD", label, time?: "HH:MM", timeZone?, color? };coloraccepts SVG-safe hex values:#RGB,#RGBA,#RRGGBB, or#RRGGBBAA. Numeric x-axis timestamps use Unix epoch milliseconds. multiple are allowed.dateis the calendar date in the event's own zone. Givetimewhen the moment matters (a launch hour);timeZoneis an IANA zone and needs atime. Without a zone, the time is UTC. - A badge sits on the x-axis at the date with a faint dashed guide line. Hovering the badge lists every event on that day with its time, shown in the event's own zone ("12:01 AM PT"). It adds no legend entry and does not change the series tooltip.
- Events on the same day share one badge; on an hourly axis each timed event sits in its own hour, and an event without a time sits on the first hour shown for its date.
- On a daily or coarser axis, a date missing from the data snaps to the nearest x value. On an hourly axis, an event without a time whose date has no hours shown is hidden. A date outside the visible range is hidden; a non-date x-axis shows nothing.
- A set's date that a panel also lists in
config.eventsdraws once. mutate-dashboardrejects malformed events and other chart types.- Scheduled email reports draw key dates and panel events: the guide line, badge, and label text, including on combo charts. Labels sit in rows above the plot: same-day labels join, a long one wraps at words, and days that find no room are counted, not cut.
- A dashboard and its report emails draw the key dates of its owner's
organization, minus the sets it hides, even for a viewer or reviewer in
another organization. There
list-key-datesreturnseditable: false, without member emails or, unless you can edit the dashboard, the hidden sets, and no sets at all when no chart there draws key dates: a date you save lands in your own organization's sets, not on that dashboard. For a Human Review preview, passlist-key-datesandlist-data-notesthedashboardIdand the samereviewPreviewandreviewOrgIdasget-sql-dashboard.
Data Notes
A data note says the numbers on a chart are wrong or unusual for a stretch of
time: an incident (kind: "incident") or a tracking problem (kind: "data").
Use one instead of a key date whenever the point is "don't trust this range".
Notes belong to the organization, like key-date sets, and a dashboard draws
its owner organization's. Read them with list-data-notes, passing
dashboardId for the ones a dashboard draws; add or change one with
save-data-note (pass id to change only the fields given); remove with
delete-data-note.
matchEventslists the event names the problem affects. A note shows on every chart whose SQL filters on one of them: either side of=(inWHEREorCASE WHEN), anIN (...)item, or a simpleCASE event WHENvalue, matched exactly and case-sensitively; or aLIKEpattern (ILIKEin any case). A name the SQL only selects as a label, returns fromTHEN/ELSE, excludes (!=,<>, or aNOTover its comparison or parentheses), or writes in a comment does not count, and neither does= ANY(ARRAY[...])orIN UNNEST([...]).unlessEventsskips charts that also filter on the corrected event. Pin a note to specific charts withpanels: [{ dashboardId, panelId }]when no event filter identifies them.startDateandendDateareYYYY-MM-DD. Leave outendDatewhile the problem is ongoing, andstartDatewhen it has been wrong since before tracking began. Marking a notestatus: "fixed"needs anendDate; say what fixed it infix. Passnullto clear a date or the fix.- Time charts shade the note's range, with an edge only where it starts or ends inside the chart, and a hoverable title. Rows sorted by something other than date shade each run of the note's rows, never a row between them, under one title. Incidents are red; open data problems amber; fixed data problems grey. Other charts, and a time chart whose x values aren't dates, flag the note by the title and write it under the chart when its dates overlap the chart's time range: the panel's own range if it overrides the dashboard's. A chart whose SQL has no time range, or one the app can't read such as a quarter its SQL works out, does so while the note is ongoing or ended in the last 30 days.
- A dashboard hides a note on one chart with
setDashboard({ annotations: { hiddenDataNotes: [{ noteId, panelId }, ...] } }), listing the notes already hidden that stay hidden;hiddenKeyDateSetsis kept. - In Edit mode, people add a note from a chart's menu ("Add data note", pinned to that chart) or the Annotations menu; a note's hover card offers Edit, Mark fixed, and Hide on this chart, and the chart's menu offers Hide for each of its notes. On a dashboard from another organization they can hide its notes and sets but not add or change them.
- Scheduled email reports shade the same ranges, title each note once in the label rows above the plot alongside key dates (a title with no room left is counted), and write each note's text under the chart.
Adding A Marker
When someone asks to mark something on a chart, pick the kind from what a reader should take away:
- A moment that explains a change (a launch, a release, a pricing change) is a
key date. Call
list-key-datesfirst and add it to the set it belongs in rather than starting a near-duplicate set. GivetimeandtimeZonewhen the hour matters, as it does for launches. Use a panel'sconfig.eventsonly when the date matters to that one chart. - A stretch where the numbers are wrong or unusual (an outage, an undercount, a
tracking gap) is a data note. Take
matchEventsfrom the event names the charts' SQL filters on (get-sql-dashboardwithpanelIds), not from how the person phrased it, and pinpanelswhen no event name identifies the charts.
Pass the open dashboard's id as dashboardId to save-key-date or
save-data-note, and read the result's dashboard before replying. A note
lists the charts it is on in shownOn; a key date says only whether the
dashboard shows its set, in setShown. Neither promises a mark: a time chart
draws one only over the dates it plots. When hint says it shows on none, fix
the event names, or tell the person why. A hint with neither shownOn nor
setShown means the dashboard can't draw it at all (an Explorer dashboard, or
another organization's); it is still saved. A set or note the dashboard hides
is that dashboard's choice, so ask before showing it.
To explain a spike or dip, read keyDateSets and dataNotes from
get-sql-dashboard or view-screen first and cite what they say. They are the
organization's records, not part of the dashboard's saved config: a config
write needn't carry them and can't change them, though its annotations field
picks which ones this dashboard hides. If
annotationsError is there instead, say the markers could not be read rather
than that there are none. omittedKeyDateSetCount or omittedDataNoteCount
means the list was cut to fit, so read list-key-dates or list-data-notes
with dashboardId before saying a marker isn't there. keyDatesHint means no
chart on the dashboard draws key dates, so don't cite one there. A note's panelIds are the charts it is
on, but a time chart draws it only over the dates it plots (and, if its x
values aren't dates, only when they overlap its time range), so cite it for a change
only when the change falls within the note's dates. editable: false means
they are the owner organization's, so cite them but don't change them.
Reusable Native Dashboard Patterns
The recent extension-backed dashboards in Builder Analytics cluster into a few repeatable compositions. Prefer these native panels, with a real SQL or Data Program result behind each one, when creating a replacement or a new dashboard:
| Pattern | Native composition |
|---|---|
| Customer ROI / value realization | metric KPI cards, line or area trends, table detail, and callout or section panels for the business narrative |
| Account engagement / outreach | metric coverage and adoption cards, a daily line trend, heatmap or table segmentation, and callout alerts |
| GTM pipeline / cross-sell | funnel for ordered stages, metric totals, bar or line trends, and a table for account-level follow-up |
| Win/loss analysis | section groups with metric, table, bar, callout, and trend panels; use a Data Program for provider joins and evidence rows |
Panel config.description values and a callout row's message support inline
Markdown links. Use [label](https://example.com); raw HTML is not rendered.
Funnel panels use config.xKey for the stage label and config.yKey for a
non-negative count or value. The renderer preserves the SQL row order, shows
each stage's share of the first stage, and shows the change from the previous
stage. Keep the intended stage order in SQL with ORDER BY.
When people can skip a stage or go around it (onboarding, setup flows), add
config.funnelOutcomes so a skip never reads as drop-off. It names result
columns of per-stage people counts, not shares: completedKey and leftKey
are required, skippedKey is optional, and optionalKey names a boolean
column that tags a stage Optional. yKey stays the people shown the stage, and
completed + skipped + left must not exceed it; the rest are "moved on without
either". Each bar then splits into those outcomes and the stage leads with the
share who left the app there. A missing column draws the usual warning; a
stage whose counts are not numbers or add up to more than shown draws a plain
bar, and the panel check reports it under funnelOutcomes.
To let people click a table row and see its numbers split by app (or another
column) in a side panel, add config.breakdowns: [{ column: "app", label: "App" }] and put the column in the panel SQL inside {{?breakdown}}…{{/breakdown}}
blocks in both the select list and the GROUP BY, e.g. SELECT role{{?breakdown}}, {{breakdown}}{{/breakdown}}, COUNT(*) AS people … GROUP BY role{{?breakdown}}, {{breakdown}}{{/breakdown}}. The column must be a real column in scope at that
point of the SQL; when a CTE aggregates first, carry it through that CTE. A
normal load drops the blocks, so the panel costs nothing more until someone
opens a row; one capped breakdown query then serves every row on the same
filters. If the panel's rows already carry the column, no block is needed and
no query runs. For web, desktop or mobile, first-party events carry
properties.client_platform (web, electron, mobile); label electron
Desktop. Rows match their breakdown on every column that is not a number, so
give a numeric column that names rows (a week, a year, an ID) format: "text"
or "date" in config.columns; unformatted numbers count as measures. The
first format: "number" column is the group size that sorts, mutes and folds
groups, so make it a count such as people, not an average or a rate.
Breakdowns don't work on a pivoted table (config.pivot). The
open breakdown is in view-screen as rowBreakdown.
BigQuery and first-party line, area, bar, combo, pie and funnel charts can
declare config.drilldown: { sql: "…" }
to open records for a clicked point instead of aggregate rows. The template
receives the dashboard filters plus {{drillX}} (raw x-axis value) and
{{drillSeries}} (raw series key, or empty when absent), escaped for the source.
In declared BigQuery templates, variables must be inside ordinary quoted strings.
Lookup rejects variables in raw literals, identifiers or comments, variables
right after a string's backslash escape, and variables touching a quote other
than a triple-quoted string's own delimiters (an empty value could join the
quotes). Doubled quotes
('') are refused too: GoogleSQL reads them as two literals, so escape quotes
with a backslash. Static raw regex literals are allowed.
Declared first-party templates follow the same position rules in PostgreSQL
syntax: variables go inside plain '…' strings ('' escapes a quote),
never in "…" identifiers. Lookup also refuses E, U&, B, X and N
strings, a prefix touching its quote (write DATE '2026-10-01'), $,
backticks or # outside strings, and nested block comments.
Declared record templates do not support {{?variable}}…{{/variable}}
blocks, which could assemble new literal contexts after validation. Use SQL
CASE expressions with ordinary variables for optional filters.
Record templates can't use :list variables. With nothing selected,
{{appFilter:list}} renders as the bare name __empty_list_filter__. BigQuery
and PostgreSQL reject that name even inside a CASE branch that never runs, so
IN ({{appFilter:list}}) fails every click until someone picks a value. Under
an all option, such as the first-party app filter's default, it renders as
'all' and matches no rows. Match the comma-joined scalar instead, and treat
both an empty value and all as every app. In BigQuery:
('{{appFilter}}' IN ('', 'all') OR app IN UNNEST(SPLIT('{{appFilter}}', ','))).
In first-party SQL, which can also run on BigQuery:
('{{appFilter}}' IN ('', 'all') OR STRPOS(',' || '{{appFilter}}' || ',', ',' || app || ',') > 0).
An agent dashboard write that adds or changes a template with a :list
variable is refused with these patterns, and one with a {{?…}} block is
refused with the CASE advice above. A template saved earlier with :list
fails every click, even with values selected, until it is rewritten to one of
these patterns. The other rules
above are checked only when someone clicks, and a failed click shows just
"Couldn't load records".
A record template can return COUNT(*) OVER () AS total_matching alongside a bounded
record list such as LIMIT 500; the dialog hides that count column and reports
truncation. Without a valid count, the total and export completeness remain
unknown. Provider partial results also have unknown totals, even if a count is
present. The declared SQL runs only when a point is opened and reuses a
completed result for the same account, source, SQL and dashboard scope.
The dialog requests the panel-drilldown operation with a fixed 50 GiB server
byte cap; measure its scan before enabling it, since a row limit does not reduce
scanned bytes. This is an interaction budget, not a restriction on the SQL an
authenticated user can submit to the normal query operation under its source
budget.
Without a declaration, supported first-party catalog panels retain their
record templates and other charts open their aggregate rows. Normal panel SQL
is unchanged by this declaration.
When a dashboard is being migrated from an extension, create a new v2 copy, bind its panels to the real provider schema or Data Programs, and compare it with the original before retiring the extension-backed version. Do not invent customer-specific SQL, provider joins, cached rows, or extension ids in a catalog template. Existing dashboards remain readable while the native replacement is validated. Bespoke interaction flows, arbitrary layouts, and visualizations outside these contracts may remain Custom Blocks.
Sigma workbook import
The dashboard menu opens the Sigma import flow: a searchable table of every
workbook the user can see in Sigma, with the owner of each migrated one and a
Migrate button on the rest. Imports remain disabled for elements whose source project
Analytics cannot verify: Sigma's connection API reports provider type and
metadata but does not expose a BigQuery project identifier. Do not call
migrate-sigma-workbook for an unverified source or treat an Analytics
BigQuery credential as proof that it targets Sigma's project. Users can list
workbooks with list-sigma-workbooks and inspect one with
inspect-sigma-workbook. The feature is controlled by
analytics.sigma-dashboard-migration and requires a Sigma connection granted
to Analytics.
Use an existing Dispatch Sigma connection when it is granted to Analytics; the import flow discovers accessible connections without copying their Vault values. Any workspace member can connect a personal Sigma account with OAuth from the importer and choose the account's documented API region. OAuth tokens and the connection stay scoped to that user. If direct setup is needed, an organization owner or admin can still enter Sigma client credentials in the Analytics dialog. Analytics saves those values under Analytics-specific encrypted organization secrets and links them to an Analytics-only connection. Credential values must never pass through agent chat, action arguments, logs, source, or screenshots.
Each Sigma workbook migrates to at most one Analytics dashboard per
organization. list-sigma-workbooks reads migration status only for workbooks
the caller's Sigma connection returns, so status follows Sigma access. For a
migrated workbook it returns the dashboard id, link, and owner email and
display name to every org member, and the title and canOpen: true only when the caller can open
the dashboard. Point users at that dashboard, or its owner for access, instead
of importing again. Anyone whose Sigma login can open a workbook may retry its
failed import or take over an import stuck for ten minutes; only the person who
migrated a workbook may re-import it.
If Sigma adds verifiable source mapping in the future, the planned import will
create a private snapshot in the user's personal Sigma folder. Other source
types and unsupported elements will become review callouts. Preserve migration
warnings and never describe a future result as parity-complete or automatically
synchronized. Sigma's workbook-code API is public Beta and can omit unsupported
workbook features before inspection receives the response.
The source tree ships four provider-free v2 manifests in
server/lib/native-v2-dashboards.ts: Customer ROI, Account Engagement,
Cross-sell, and Win / Loss. They intentionally contain no customer names,
provider ids, SQL, cached rows, or guessed joins. After deployment, an
organization owner or admin provisions them with ensure-native-v2-dashboards
by supplying one real Data Program per binding key. The action validates the
stored program output contract, shares the programs with the organization,
and installs the read-only builtin-<template> built-ins (see Built-in
Dashboards). It never touches the extension-backed originals. Do not add these
to the root demo bootstrap or silently auto-bind them to guessed provider
schemas.
Custom Blocks
A Custom Block is a sandboxed extension embedded as a chartType: "extension"
panel (config.extensionId). It is the exception, not the default: native panels
and Data Programs come first, and dual-axis charts are native (config.rightYKeys).
R
…(truncated)