save_dashboard
Create or update a saved dashboard: a live page NEM Explorer hosts for this user at a stable URL, whose panels re-run their queries against current data every time it is opened. THIS is the tool for "build me a dashboard", "can I have a page that tracks X", "add a chart to my Y dashboard", or anything the user wants to come back to. Not share_artifact — that publishes a one-off write-up to a PUBLIC page; a dashboard is private, live, and editable. You author a JSON document, not code: named read-only SQL queries plus panels (markdown, chart, table, stat) that reference them by name. A dashboard whose panels plot time should declare a time block — it gives the page a time picker and drag-to-zoom — and filter and bucket with $__timeFilter(ts) and $__timeGroup(ts). When the user wants to switch region on the page, declare params and read them in SQL as {region:String} rather than saving a dashboard per region; a detail page per row is one dashboard with a parameter plus a table links entry, not a dashboard per row. Call get_dashboard_guide for the vocabulary and the rules. To EDIT an existing one, call get_dashboard first and pass its name here along with the complete edited spec — a save REPLACES the spec, it does not merge. Passing name plus a different title renames it (and changes its URL). Every query is executed before anything is stored: if one fails, or a panel plots a column its query does not return, NOTHING is saved and you get every problem back at once, with the real column names. Fix them all and call again. Returns the url to give the user. A heavy dashboard can take a while to save. If this call times out, the save may still have landed: call get_dashboard. If its revision moved, its last_save carries that save's warnings. If it did not move (or a new dashboard does not exist), the save was refused or is still running and no reason is stored: save again to see why, with a narrower widest date option if a long window is the likely cause.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"title": "<title>"
},
"name": "save_dashboard"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ctes | No | SQL several queries repeat, declared once: `{"name": "owners", "sql": "SELECT …", "description": "…"}`. A query that names `owners` (`FROM owners`, `JOIN owners`) gets it prepended as a CTE. A shared CTE may name the ones declared before it. | |
| name | No | The dashboard to overwrite, as its name or its title. Omit to create a new one. Pass this whenever the user is editing something that already exists — "add a capacity factor chart to my SA wind dashboard". Without it a second dashboard is created alongside the first, which is rarely what anyone wants and is invisible until they open the list. Give both `name` and a different `title` to rename: the name follows the title, and the old one stops resolving. | |
| time | No | The dashboard's time range — a time picker on the page, drag-to-zoom on every time chart, and `from` / `to` / `bucket` in the queries: `{"default": "now-7d", "min_interval": "5m", "max_span": "1y"}` `default` (and optional `default_to`, `now` unless set) are time expressions: `now-7d`, `now-6h`, `now-1M/M` (start of last month; `m` is minutes, `M` months), `now/fy`, or `YYYY-MM-DD`. `min_interval` is the data's own resolution (`4s`, `5m`, `30m`, `1d`; default `5m`) and `max_span` the widest range a viewer may pick (default `1y`). `earliest` (`2026-10-01`) is where the data starts, for something that began on a known day: an earlier pick is cut to it. Queries use `$__timeFilter(ts)` and `$__timeGroup(ts)` (or `$__dateFilter(d)` / `$__dateGroup(d)` on a Date column), or the raw placeholders `{from:DateTime}`, `{to:DateTime}`, `{bucket:UInt32}`. A query too heavy for the whole `max_span` caps its own window with `$__timeFilterMaxSpan(ts, 35d)`, not an `AND dateDiff(...)` condition. | |
| title | Yes | The dashboard's headline, e.g. "SA wind vs price". Also what its name is derived from on first save: "SA wind vs price" is saved as `sa-wind-vs-price`, which is what the user will say to ask for it later. | |
| panels | No | The panels, rendered top to bottom. Each is one of: `{"type": "markdown", "markdown": "## Heading\n…"}` `{"type": "chart", "query": "regional_price", "title": "…", "chart_type": "line", "x": "hour", "y": ["rrp"], "color": "REGIONID"}` `{"type": "table", "query": "regional_price", "title": "…"}` `{"type": "stat", "query": "latest", "title": "…", "value_column": "rrp", "unit": "$/MWh"}` `{"type": "stats", "query": "kpis", "title": "Last 12 months", "items": [ {"value_column": "events", "label": "price events"}, …]}` — 2 to 8 numbers from one row on one compact line Add `"width": "half"` to any panel to put two side by side, and `"description"` (at most two sentences, ≤ 300 bytes) to a chart, table or stat to say what the reader should look for. `"chart_type": "calendar"` lays one measure per day out as a 53-week heatmap (`x` a date, one `y`). `"chart_type": "heatmap"` colours a two-way grid by one measure: `x` the columns, `color` the rows, one `y` (e.g. month by year). `"chart_type": "map"` places rows on a map coloured by one `y`, labelled by `x`: `"lat"`/`"lon"` name the coordinate columns, `"lat2"`/`"lon2"` make each row a segment (a line from bus to bus), and an optional signed `"direction"` column draws an arrow along it (+ toward lat2/lon2). `"hidden_series": ["min_price", "max_price"]` on a chart draws those `y` columns switched off (a legend click turns them on), so extremes do not flatten the axis. A table, or a calendar chart, may carry drill-through `links`: `{"type": "table", …, "links": [{"column": "DUID", "dashboard": "unit-detail", "params": {"duid": "DUID", "start": "$start"}}]}` — each cell of `column` (each day, on a calendar) opens that dashboard with its parameters taken from the clicked row (a column name) or from this page (`$param`). The target may be this dashboard itself. Call `get_dashboard_guide` before your first dashboard — it has the full vocabulary and the rules that get a save refused. | |
| params | No | Defaults for the variables the queries read. A variable is any ClickHouse placeholder in the SQL — `{region:String}`, `{min_mw:Float64}`, `{regions:Array(String)}`, `{day:Date}` — and gets a control on the page automatically; all it needs is a default: `{"region": "SA1", "min_mw": 100, "regions": ["SA1", "VIC1"]}` A value may be an object instead, adding `options` (the only values allowed — the control becomes a dropdown), `label`, `description`, or `"hidden": true` (no control; a click sets it, e.g. a calendar's day): `{"region": {"default": "SA1", "options": ["NSW1", "QLD1", "SA1", "TAS1", "VIC1"], "label": "Region"}}` For a list that changes over time (units, stations, participants), give `options_query` instead of `options`: a standalone SELECT returning a `value` column and optional `label`, re-read whenever the page opens: `{"duid": {"default": "HAMISF1", "options_query": "SELECT DUID AS value, concat(DUID, ' – ', STATION_NAME) AS label FROM semantic.duid WHERE FUEL_TYPE = 'Solar' ORDER BY DUID"}}` Values are bound by ClickHouse, never pasted into the SQL. The older list form (`[{"name": "region", "type": "enum", …}]`) still works. | |
| queries | No | The named SQL queries this dashboard runs, each `{"name": "regional_price", "sql": "SELECT …", "description": "…"}`. Add `"partial_day_ok": true` to a query whose daily series is meant to end on today's part-day, and the save stops warning about it. `name` is lowercase letters, digits and underscores; panels reference it. One query can feed several panels and is executed once per page view. Every query must be a single read-only SELECT/WITH over `consolidated`, `semantic` or `calculated` — never `raw_*` and never `scratch.*`. All of them are executed before the dashboard is saved. Nothing is stored if any fails. | |
| seo_title | No | The search-result title for the dashboard's public page, when it should say more than `title` (at most 60 characters). `title` names the dashboard and its URL, so this is how a listed dashboard gets a better search title without moving its URL. Omit it and the page uses `title`. | |
| question_id | No | ||
| meta_description | No | The snippet under the public page's search result (at most 155 characters). Omit it and the page uses the opening of its prose. |