@metabase/cli 0.1.4 → 0.1.6

package/skill-data/transform/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: transform
+description: Author and run Metabase transforms via `mb` — body shape (native SQL + MBQL 5), create + run-with-wait, run inspection, cancel, the `update`-vs-recreate iteration rule, and the writable-keys-only PATCH contract. Load when the user touches transforms — "create a transform", "run a transform", "fix a failing transform", "list transform runs", "cancel a running transform", or anything `mb transform …`.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Transforms
+
+A **transform** persists the result of a query (native SQL or MBQL) to a warehouse table the user can read from cards, dashboards, and other transforms. It runs on a schedule (via `transform-job`) or on-demand (`transform run`).
+
+This skill covers the create-and-run flow. The general flag conventions, body-input precedence, and output flags live in the `core` skill (`mb skills get core`). If you're authoring a transform inside a workspace, also load the `workspace` skill for the canonical-vs-isolation-schema rule.
+
+## Body shape
+
+A transform has two halves:
+
+- `source` — the query to run (`type: "query"`, with `query.type` of `native` or `mbql`).
+- `target` — the warehouse destination (`type: "table"`, with `database`, `schema`, `name`).
+
+Native SQL is the simplest source and the easiest to author by hand (see "Create + run" below). MBQL is what the Metabase UI emits and is more verbose; pull a sample with `mb transform get <id> --full --json` if you need its shape.
+
+For an **MBQL 5** `source.query` (`lib/type: "mbql/query"`), the body shape, the "options object is always second" clause rule, UUID minting, aggregation/order-by refs, naming aggregation output columns, and the `--print-schema` → `--dry-run` validation loop are all in the `mbql` skill — **`mb skills get mbql`**. The MBQL-5 pre-flight on `transform create`/`update` is documented there too (legacy MBQL 4 and native sources skip it). For a transform target, naming your aggregation output columns matters more than usual — a bare `count` / `avg_2` becomes the warehouse column name; see the `mbql` skill's "Naming aggregation output columns".
+
+## Create + run (native SQL)
+
+```bash
+cat > /tmp/transform.json <<'EOF'
+{
+  "name": "user_counts_by_signup_year",
+  "description": "Sample transform: counts users by year of signup",
+  "source": {
+    "type": "query",
+    "query": {
+      "type": "native",
+      "database": <db-id>,
+      "native": {
+        "query": "SELECT date_trunc('year', created_at)::date AS signup_year, COUNT(*)::int AS user_count FROM public.users GROUP BY 1 ORDER BY 1"
+      }
+    }
+  },
+  "target": {
+    "type": "table",
+    "database": <db-id>,
+    "schema": "public",
+    "name": "user_counts_by_signup_year"
+  }
+}
+EOF
+
+TRANSFORM_ID=$(mb transform create --file /tmp/transform.json --profile <name> --json | jq -r '.id')
+mb transform run "$TRANSFORM_ID" --wait --profile <name> --json
+```
+
+Notes:
+
+- `<db-id>` comes from `mb database list --profile <name> --json`. Database ids are per-instance — a workspace child re-numbers them independently of the parent.
+- Target `schema` is the **canonical** name (e.g. `public`). In a workspace, the QP rewrites it to the per-workspace isolation schema (`mb__isolation_<hash>_<ws-id>`) at execution time — don't hard-code that prefix.
+- `--wait` on `transform run` polls until status is `succeeded` or `failed`. Without it you only get `{message: "Transform run started", run_id, final: null}` and have to poll yourself.
+- The `--json` envelope is shape-stable: `{message, run_id, final}`. `final` is always present — `null` when `--wait` is omitted or the run never started, otherwise a full `TransformRun` object with `status` and `message`. On a failed run (`final.status` ∈ {`failed`, `timeout`, `canceled`}) the CLI exits 1 and writes a one-line summary `transform run <id> failed` to stderr; the failure detail lives only in `final.message` on stdout, so `jq -r '.final.message'` is where to look.
+- The heredoc with single-quoted `'EOF'` prevents shell from interpolating any `$vars` inside the SQL.
+- `transform create --json` returns the agent-facing compact projection: `{id, name, description, source_type, target: {type, database, schema, name}, target_db_id}`. Read `target.schema`/`target.name` directly off the create output — no follow-up `transform get` needed to verify where the transform will write.
+- If a transform with the same `name` already has a YAML representation on disk under the configured remote-sync repo, `create` mints a `_2` suffix on the exported filename (the new transform gets a fresh `entity_id`; the prior one isn't touched). For "iterate on the same concept" workflows, prefer `transform update <id>` — see "Iterating on a failing transform" below.
+
+## Inspect
+
+```bash
+mb transform list --profile <name> --json
+mb transform get <id> --profile <name> --full --json     # full transform incl. last run summary
+```
+
+After a run, the materialized table is queryable via `mb` (`card create` against it, native query against `<schema>.<name>`, etc.). Columns and types are inferred from the result set; if you change the SELECT shape, drop the table first or the next run will fail on a column-mismatch error.
+
+## Inspect runs and cancel an in-flight run
+
+```bash
+# Recent runs across all transforms (drains all pages by default; cap with --limit):
+mb transform runs --profile <name> --json
+mb transform runs --transform-id <id> --limit 10 --profile <name> --json
+
+# Fetch one run by RUN id (NOT transform id — the run id comes from `transform run` or `transform runs`):
+mb transform get-run <run-id> --profile <name> --json
+
+# Cancel the currently-running run for a transform:
+mb transform cancel <id> --profile <name> --json
+```
+
+Notes:
+
+- `transform runs` and `transform get-run` parse against the same `TransformRun` schema, so `get-run` returns the same per-run shape as one entry of `runs`. The compact projection is `{id, transform_id, status, run_method, start_time, end_time, message}`. Pass `--full` on `get-run` for the hydrated row including `is_active`, `user_id`, `transform_name`, `transform_entity_id`, `checkpoint_*` fields, and a nested `transform: {id, name, …}` block.
+- `transform cancel` takes the **transform** id and 404s with `Endpoint not found — is this a Metabase instance?` if there is no active run. The response shape is `{canceled: true, id: <transform-id>}`.
+- For native-SQL transforms, cancel marks the run as `canceling` but does **not** kill the warehouse query mid-flight — the query runs to completion, then the run lands as `canceled` (or stays `succeeded` if the cancel arrived after the writer committed). For Python transforms the worker is interrupted directly. Don't expect cancel to free warehouse resources instantly on long native queries; expect it to flip state and prevent downstream consumers from treating the result as good.
+- The `--transform-id` filter on `runs` accepts a single integer; the CLI translates to the server's `transform-ids` query vector. To cross-filter multiple transforms, run `transform runs --json` and `jq` post-hoc.
+
+## Update body: send only writable keys, never round-trip the GET body
+
+`transform update <id>` is **PATCH semantics** — only send the fields you actually want to change. The endpoint accepts exactly these writable keys:
+
+```
+name, description, source, target, run_trigger,
+tag_ids, collection_id, owner_user_id, owner_email
+```
+
+**Don't paste the output of `transform get` into a `transform update` body.** The GET response carries server-side fields (`id`, `entity_id`, `created_at`, `updated_at`, `creator_id`, `last_run`, `target_db_id`, `target_table_id`, `source_type`, `source_database_id`, `source_readable`, `creator`, `owner`, `table`, …) that the PUT endpoint isn't built to handle. Currently, unknown top-level keys flow into `t2/update!` and produce a leaked H2 SQL error like:
+
+```
+Column "TAGS" not found; SQL statement:
+UPDATE "TRANSFORM" SET "TAGS" = (), "UPDATED_AT" = NOW() WHERE "ID" = ? [42122-214]
+```
+
+Two specific footguns:
+
+- **`tags` is not a key on the REST API.** The serdes/YAML representation uses `tags`; the REST contract uses `tag_ids` (an array of integer ids). If you pulled a YAML representation and want to PUT it, translate `tags: [...]` → `tag_ids: [...]` first (or omit it entirely if you're not changing tag membership).
+- **`source_type`, `target_db_id`, `target_table_id`, `entity_id`** are derived/computed by the server. They appear in GET responses for the agent's benefit; the server doesn't accept them on update.
+
+Right shape — patch only what changes:
+
+```bash
+# Rename only:
+mb transform update <id> --body '{"name":"renamed"}' --profile <name> --json
+
+# Rewrite the SQL only:
+cat > /tmp/patch.json <<'EOF'
+{ "source": { "type": "query", "query": { "type": "native",
+    "database": <db-id>,
+    "native": { "query": "SELECT … FROM public.orders" } } } }
+EOF
+mb transform update <id> --file /tmp/patch.json --profile <name> --json
+
+# Change tag membership (note: tag_ids, not tags):
+mb transform update <id> --body '{"tag_ids":[1,3]}' --profile <name> --json
+```
+
+If you really must round-trip, project to the writable subset:
+
+```bash
+mb transform get <id> --full --profile <name> --json \
+  | jq '{name, description, source, target, run_trigger, tag_ids, collection_id, owner_user_id, owner_email}
+        | with_entries(select(.value != null))' \
+  > /tmp/patch.json
+```
+
+## Iterating on a failing transform
+
+When `transform run` fails and you want to retry with a fixed body, **prefer `transform update <id> --file body.json` over `transform delete <id>` + `transform create`.** Update keeps the same row, the same `entity_id`, the same materialized table, and the same on-disk YAML filename. Concretely this means:
+
+- `git-sync export` produces **one** clean commit containing only the fix, instead of "broken transform" + "remove broken transform" landing as two commits in `git log`.
+- You don't have to chase `_2` suffixes minted when two YAMLs share a `name` on disk (see the `transform create` notes above).
+- The materialized output table either updates in place or, if the SELECT shape changed incompatibly, errors loudly on the next run rather than landing in a parallel `..._2` table the agent has to clean up. (`transform delete-table <id>` resets the column shape if you need a clean slate.)
+
+Recipe:
+
+```bash
+# 1. Try once
+ID=$(mb transform create --file /tmp/t.json --profile <n> --json | jq -r '.id')
+mb transform run "$ID" --wait --profile <n> --json     # → failed
+
+# 2. Fix the body in place; PATCH only what changed.
+#    Source-only patch — keeps name, target, tags untouched on the server.
+cat > /tmp/source-patch.json <<'EOF'
+{ "source": { "type": "query", "query": { "type": "native",
+    "database": <db-id>,
+    "native": { "query": "<fixed SQL here>" } } } }
+EOF
+mb transform update "$ID" --file /tmp/source-patch.json --profile <n> --json
+
+# 3. Re-run
+mb transform run "$ID" --wait --profile <n> --json     # → succeeded
+```
+
+If you really must `create + delete` instead, do the `delete` **before** the first `git-sync export` so the failed entity never lands in git history. Order matters: agents reflex to "export to checkpoint progress," but for transforms an export of a soft-failed state is mostly noise that needs a follow-up cleanup commit. See the `git-sync` skill, "Read state before mutating" for the ordering rule.
+
+## Drop the materialized table (keep the transform)
+
+```bash
+mb transform delete-table <id> --yes --profile <name>
+```
+
+Useful when you've changed the SELECT and want a fresh `CREATE TABLE` on the next run. **`--yes` is required** in non-interactive contexts; without it the command exits with `--yes required to delete non-interactively`.
+
+## Delete the transform
+
+```bash
+mb transform delete <id> --yes --profile <name>
+```
+
+Removes the definition. Whether the materialized table is dropped depends on the server — check with `mb table list --db-id <db-id> --profile <name> --json` if it matters. Same `--yes` rule as `delete-table`.
+
+## Transform jobs (schedules)
+
+A schedule lives in a separate resource (`transform-job`) and references one or more transform ids. Create with the same body-input pattern (`--file body.json`); see `mb transform-job --help` for the verb list. Most ad-hoc agent work is one-off `transform run`, not job authoring.
+
+## Don't (transform-specific)
+
+- Don't put `transform run` calls in tight polling loops — pass `--wait` and let the CLI handle the polling. Manual loops without `--wait` will hammer the server.
+- Don't author MBQL 4 (the legacy nested `{ type: "query", query: {...} }` shape) by hand — pull a sample with `mb transform get <id> --full --json`. MBQL 5 (`lib/type: "mbql/query"`) **is** authorable by hand thanks to the `mb query --print-schema` + `--dry-run` feedback loop; for non-trivial pipelines you may still prefer building in the UI and exporting.
+- Don't write the workspace isolation schema into `target.schema` or SQL. See the `workspace` skill for the canonical-name rule.
+- Don't paste a `transform get` body into `transform update` — the PUT endpoint only accepts writable keys, and unknown keys (notably `tags`, `source_type`, `entity_id`, `created_at`, `last_run`) leak as raw SQL errors. See "Update body: send only writable keys" above. Use `tag_ids` (not `tags`) on the REST contract.

package/skill-data/viz/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: viz
+description: Author Metabase `visualization_settings` and pick the right `display` for cards via the `mb` CLI. Covers the display → settings-namespace map (graph.*, pie.*, funnel.*, scalar.*, table.*, …), the column-name-vs-numeric-field-id rule, the `column_settings` JSON-string-key footgun, worked API-form examples per chart family, and the pull-from-UI escape hatch for complex charts. Load whenever shaping how a card renders by hand — "create a bar chart", "make this a line chart", "format this column as currency", "set the pie dimension and metric", "the card renders as a table instead of a chart", "add conditional formatting", or any `visualization_settings` work.
+allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
+---
+
+# Visualization settings
+
+A card has two presentation fields alongside its `dataset_query`:
+
+- **`display`** — the chart type (`bar`, `line`, `pie`, `scalar`, `table`, …). One closed set of values; pick from the enum below.
+- **`visualization_settings`** — a free-form map whose keys are **namespaced by `display`** (`graph.*` for bar/line, `pie.*` for pie, …). The server stores almost anything and **silently ignores keys that don't apply** to the chosen `display`.
+
+The MBQL pre-flight does **not** validate `visualization_settings` — there is no `--skip-validate` to fail past, because nothing checks it. A `display` typo or a misnamed key is accepted by the API and the card just renders as a default table or drops the setting. So **the feedback loop is read-back, not pre-flight**: after `card create`/`update`, confirm with `mb card get <id> --full --json` (or open the card) that it rendered as intended.
+
+The general flag conventions and body-input precedence live in the `core` skill (`mb skills get core`); the `dataset_query` body itself is the `mbql` skill's job (`mb skills get mbql`). This skill is only about how the result is displayed.
+
+## `display` decides everything
+
+`display` selects which setting namespace is read. Pick `display` first, then only the matching namespace's keys matter.
+
+| `display`                                   | Settings namespace(s)                                     | Key columns are named by |
+| ------------------------------------------- | --------------------------------------------------------- | ------------------------ |
+| `bar` `line` `area` `combo` `row` `scatter` | `graph.*`, `series_settings`, `column_settings`           | output column **name**   |
+| `waterfall`                                 | `graph.*` + `waterfall.*`                                 | output column name       |
+| `boxplot`                                   | `graph.*` + `boxplot.*`                                   | output column name       |
+| `pie`                                       | `pie.*`, `column_settings`                                | output column name       |
+| `scalar` `number`                           | `scalar.*`                                                | output column name       |
+| `smartscalar`                               | `scalar.comparisons`                                      | output column name       |
+| `funnel`                                    | `funnel.*`                                                | output column name       |
+| `gauge`                                     | `gauge.*`                                                 | —                        |
+| `map`                                       | `map.*`                                                   | output column name       |
+| `pivot`                                     | `pivot_table.*`, `table.*`                                | output column name       |
+| `sankey`                                    | `sankey.*`                                                | output column name       |
+| `table`                                     | `table.*`, `column_settings`                              | output column name       |
+| `object` `list`                             | `column_settings`                                         | output column name       |
+| `progress`                                  | `progress.goal`, `progress.color` (sparse — pull from UI) | —                        |
+| `heading` `text` `link` `iframe` `action`   | dashcard-only `virtual_card` (see references)             | —                        |
+
+Closed `display` enum (card-level): `table`, `bar`, `line`, `area`, `row`, `pie`, `scalar`, `smartscalar`, `number`, `combo`, `pivot`, `funnel`, `map`, `scatter`, `waterfall`, `progress`, `gauge`, `object`, `list`, `sankey`, `boxplot`. (`heading`/`text`/`link`/`iframe`/`action` are dashcard virtuals, not standalone cards.) An unknown value is accepted by the API but renders nothing useful — typos like `bargraph`/`linechart` are the most common cause of a "why is my chart blank" report.
+
+## The rule that trips everyone: settings name **output columns**, by name
+
+`graph.dimensions`, `graph.metrics`, `pie.dimension`, `pie.metric`, `scalar.field`, `funnel.metric`, `map.latitude_column`, … all take **output column-name strings** — the names the query _produces_, not field ids. A `count` aggregation outputs the column `count`; a breakout on a field outputs that field's name; a named aggregation outputs its `name`. These strings are **identical in the API form and the portable (git-sync) form** — no numeric-vs-name footgun here.
+
+So the names you put in `visualization_settings` come from the query's output, not from `mb field`/`mb table`. If you set `name` on an aggregation (see the `mbql` skill, "Naming aggregation output columns"), use that same string here.
+
+## Minimum-viable settings per chart family (API form)
+
+Each example is the `visualization_settings` block to pair with the given `display` on a `card create`/`update` body. The `dataset_query` is elided — build it per the `mbql` skill. The output columns referenced (`CATEGORY`, `count`) are whatever the query's breakout/aggregation produce.
+
+**Bar / line / area** — one dimension on the x-axis, one or more metrics:
+
+```json
+"display": "bar",
+"visualization_settings": {
+  "graph.dimensions": ["CATEGORY"],
+  "graph.metrics": ["count"]
+}
+```
+
+(Switch `display` to `line` or `area` with the same `graph.*` keys. Multiple metrics: `"graph.metrics": ["count", "sum"]`. Stacked: add `"stackable.stack_type": "stacked"`.)
+
+**Pie** — one dimension, one metric:
+
+```json
+"display": "pie",
+"visualization_settings": { "pie.dimension": "CATEGORY", "pie.metric": "count" }
+```
+
+**Scalar** (single big number) — the field to surface:
+
+```json
+"display": "scalar",
+"visualization_settings": { "scalar.field": "count" }
+```
+
+**Table** — column order/visibility plus per-column formatting:
+
+```json
+"display": "table",
+"visualization_settings": {
+  "table.columns": [
+    { "name": "CATEGORY", "enabled": true },
+    { "name": "count", "enabled": true }
+  ],
+  "column_settings": {
+    "[\"name\",\"count\"]": { "column_title": "Orders" }
+  }
+}
+```
+
+An **empty** `"visualization_settings": {}` is valid for any `display` — Metabase falls back to sensible defaults (it auto-picks dimensions/metrics for a simple aggregate). Set keys only to override the defaults.
+
+## `column_settings`: the JSON-string-key footgun
+
+`column_settings` is a map **whose keys are themselves JSON-encoded arrays** — so inside a JSON body the inner quotes must be escaped. The key is a _string_, never an object.
+
+- **Prefer the name form:** `["name", "<output column name>"]` → in a JSON body, `"[\"name\",\"count\"]"`. This is the canonical key Metabase writes (`getColumnKey`), and it's **identical in API and portable form**. Use it unless you have a reason not to.
+- **Ref form (legacy order!):** `["ref", ["field", <id>, <opts>]]`. The inner field ref here uses the **legacy MBQL-4 order** `["field", id, options]` (id **second**) — _not_ the MBQL-5 order `["field", {options}, id]` you use in `dataset_query`. In the API form `<id>` is the **numeric** field id; the portable form uses a name path. Because the order differs from MBQL 5, this form is easy to get wrong — reach for the name form instead.
+
+```json
+"column_settings": {
+  "[\"name\",\"TOTAL\"]": { "number_style": "currency", "currency": "USD", "decimals": 2 },
+  "[\"name\",\"CREATED_AT\"]": { "date_style": "MMMM D, YYYY" }
+}
+```
+
+The exhaustive per-column key list (number/date/link formatting, `view_as`, click behavior) is in the references file.
+
+## Escape hatch: pull a real card instead of authoring from scratch
+
+For anything beyond a single dimension + metric — combo charts, conditional formatting, pivot splits, click behavior, series colors — the cheapest **correct** path is to build it once in the Metabase UI and copy the result:
+
+```bash
+mb card get <id> --full --json | jq '.visualization_settings'
+```
+
+Paste that block into your `card create`/`update` body. The server produced it, so it's guaranteed valid for that `display`. This beats guessing keys from memory, and it's token-cheap (no schema dump).
+
+## Full key catalog
+
+The body above covers the high-frequency 90%. The complete per-display key tables — every `graph.*`/`pie.*`/`table.*`/… key, series settings, conditional formatting rules, pivot splits, the full `column_settings` formatting vocabulary, virtual-card (heading/text/link/iframe) settings, and click behavior — live in this skill's references file. Load it on demand, not by default:
+
+```bash
+mb skills get viz --full          # appends references/settings.md to this body
+mb skills path viz                # → the skill dir; then Read references/settings.md
+```
+
+## Don't
+
+- Don't invent `display` values (`bargraph`, `linechart`, `histogram`) — use the closed enum; the API accepts the typo and renders nothing.
+- Don't put numeric field ids in `graph.dimensions`/`pie.metric`/`scalar.field` etc. — they take **output column-name strings**.
+- Don't write a `column_settings` key as an object — it's a JSON **string** (`"[\"name\",\"COL\"]"`), inner quotes escaped.
+- Don't use the MBQL-5 field-ref order inside a `column_settings` `["ref", …]` key — that key uses the **legacy** `["field", id, opts]` order. Prefer the `["name", …]` form and sidestep it.
+- Don't expect a pre-flight to catch viz mistakes — there is none. Verify by reading the card back.
+- Don't hand-author complex charts when you can pull a working `visualization_settings` from a UI-built card.

package/skill-data/viz/references/settings.md

@@ -0,0 +1,312 @@
+# visualization_settings — full key catalog
+
+Exhaustive reference for `visualization_settings`. The SKILL.md body covers the
+common cases; this file is the long tail. Keys are grouped by the `display` they
+apply to (see the display → namespace map in the body).
+
+**Form note.** Every key name and value enum below is identical in the API/numeric
+form (`mb card create`) and the portable git-sync YAML form. The only form-specific
+constructs are (1) `column_settings` `["ref", …]` keys, where the inner field id is
+numeric in the API form and a name-path in the portable form, and (2) click-behavior
+dimension targets, same rule. All the column-naming keys (`graph.dimensions`,
+`pie.dimension`, `table.columns[].name`, …) are output column-name strings in both.
+
+JSON-body reminder: examples here are shown as YAML/JSON fragments. In a real
+`--body`/`--file` JSON payload, `column_settings` keys are JSON **strings** with
+escaped inner quotes: `"[\"name\",\"TOTAL\"]"`.
+
+---
+
+## Common
+
+| Setting               | Type    | Description                                                         |
+| --------------------- | ------- | ------------------------------------------------------------------- |
+| `column_settings`     | map     | Per-column formatting, keyed by column-reference string (see below) |
+| `card.title`          | string  | Override the card's display title on a dashboard                    |
+| `card.description`    | string  | Override the description                                            |
+| `dashcard.background` | boolean | Show/hide the dashcard background (dashcards only)                  |
+
+## Graph (`bar`, `line`, `area`, `combo`, `scatter`, `waterfall`, `row`, `boxplot`)
+
+| Setting                                 | Type           | Values / notes                                                           |
+| --------------------------------------- | -------------- | ------------------------------------------------------------------------ |
+| `graph.dimensions`                      | array          | Dimension (x-axis) output column names                                   |
+| `graph.metrics`                         | array          | Metric (y-axis) output column names                                      |
+| `graph.series_order`                    | array          | Explicit series display order                                            |
+| `graph.show_values`                     | boolean        | Show value labels on data points                                         |
+| `graph.label_values_frequency`          | string         | `"fit"`, `"all"`                                                         |
+| `graph.show_stack_values`               | string         | `"total"`, `"individual"`, `"all"`                                       |
+| `graph.x_axis.title_text`               | string         | X-axis title                                                             |
+| `graph.x_axis.scale`                    | string         | `"ordinal"`, `"histogram"`, `"timeseries"`, `"linear"`, `"pow"`, `"log"` |
+| `graph.x_axis.axis_enabled`             | boolean/string | `true`, `false`, `"compact"`, `"rotate-45"`, `"rotate-90"`               |
+| `graph.y_axis.title_text`               | string         | Y-axis title                                                             |
+| `graph.y_axis.scale`                    | string         | `"linear"`, `"pow"`, `"log"`                                             |
+| `graph.y_axis.auto_range`               | boolean        | Auto-scale Y axis                                                        |
+| `graph.y_axis.min` / `graph.y_axis.max` | number         | Y bounds when `auto_range` is false                                      |
+| `graph.show_goal`                       | boolean        | Show goal line                                                           |
+| `graph.goal_value`                      | number         | Goal line value                                                          |
+| `graph.goal_label`                      | string         | Goal line label                                                          |
+| `graph.show_trendline`                  | boolean        | Show trend line                                                          |
+| `graph.max_categories_enabled`          | boolean        | Limit number of categories                                               |
+| `graph.max_categories`                  | number         | Maximum categories shown                                                 |
+| `graph.other_category_aggregation_fn`   | string         | `"sum"`, `"avg"`, `"min"`, `"max"`                                       |
+| `stackable.stack_type`                  | string         | `null`, `"stacked"`, `"normalized"`                                      |
+
+### Series settings
+
+Per-series overrides keyed by series name (the metric column name, or the breakout
+value for a split series):
+
+```yaml
+series_settings:
+  Revenue:
+    display: line # override this series' type in a combo chart
+    color: "#509EE3"
+    "line.style": solid # "solid", "dashed", "dotted"
+    "line.size": normal # "S", "M", "L"
+    "line.interpolate": linear # "linear", "cardinal", "step-before", "step-after"
+    "line.missing": interpolate # "interpolate", "zero", "none"
+    "line.marker_enabled": true
+    axis: left # "left", "right"
+    show_series_values: true
+```
+
+### Waterfall extras (`display: waterfall`)
+
+| Setting                    | Type    | Description             |
+| -------------------------- | ------- | ----------------------- |
+| `waterfall.increase_color` | string  | Color for increases     |
+| `waterfall.decrease_color` | string  | Color for decreases     |
+| `waterfall.total_color`    | string  | Color for the total bar |
+| `waterfall.show_total`     | boolean | Show the total bar      |
+
+### BoxPlot extras (`display: boxplot`)
+
+| Setting                | Type    | Values                                 |
+| ---------------------- | ------- | -------------------------------------- |
+| `boxplot.whisker_type` | string  | `"min-max"`, `"tukey"`, `"percentile"` |
+| `boxplot.points_mode`  | string  | `"none"`, `"outliers"`, `"all"`        |
+| `boxplot.show_mean`    | boolean | Show mean marker                       |
+
+## Pie (`display: pie`)
+
+| Setting                  | Type    | Values                                    |
+| ------------------------ | ------- | ----------------------------------------- |
+| `pie.dimension`          | string  | Dimension column name                     |
+| `pie.metric`             | string  | Metric column name                        |
+| `pie.show_legend`        | boolean |                                           |
+| `pie.show_total`         | boolean | Show total in center                      |
+| `pie.percent_visibility` | string  | `"off"`, `"legend"`, `"inside"`, `"both"` |
+| `pie.slice_threshold`    | number  | Min percentage to show as its own slice   |
+| `pie.colors`             | object  | Color map keyed by dimension value        |
+
+## Scalar / Number (`display: scalar`, `number`)
+
+| Setting                           | Type    | Values                          |
+| --------------------------------- | ------- | ------------------------------- |
+| `scalar.field`                    | string  | Output column to display        |
+| `scalar.switch_positive_negative` | boolean | Invert positive/negative colors |
+| `scalar.compact_primary_number`   | string  | `"auto"`, `"yes"`, `"no"`       |
+
+### Smart scalar (`display: smartscalar`)
+
+```yaml
+scalar.comparisons:
+  - id: comp1
+    type: previousPeriod # vs. previous time period
+  - id: comp2
+    type: previousValue # vs. previous value
+  - id: comp3
+    type: periodsAgo # vs. N periods ago
+    value: 12
+  - id: comp4
+    type: staticNumber # vs. fixed number
+    value: 1000
+    label: Target
+```
+
+## Funnel (`display: funnel`)
+
+| Setting            | Type   | Values                |
+| ------------------ | ------ | --------------------- |
+| `funnel.dimension` | string | Dimension column      |
+| `funnel.metric`    | string | Metric column         |
+| `funnel.type`      | string | `"funnel"` or `"bar"` |
+| `funnel.rows`      | array  | Row order definitions |
+
+## Gauge (`display: gauge`)
+
+| Setting                | Type  | Description                                 |
+| ---------------------- | ----- | ------------------------------------------- |
+| `gauge.segments`       | array | Segments, each `{ min, max, color, label }` |
+| `gauge.segment_colors` | array | Segment colors                              |
+
+## Map (`display: map`)
+
+| Setting                                        | Type   | Values                           |
+| ---------------------------------------------- | ------ | -------------------------------- |
+| `map.type`                                     | string | `"region"`, `"pin"`, `"grid"`    |
+| `map.latitude_column`                          | string | Latitude column name             |
+| `map.longitude_column`                         | string | Longitude column name            |
+| `map.metric_column`                            | string | Metric column for coloring       |
+| `map.region`                                   | string | Region map identifier            |
+| `map.pin_type`                                 | string | `"tiles"`, `"markers"`, `"heat"` |
+| `map.colors`                                   | array  | Color scale                      |
+| `map.zoom`                                     | number | Initial zoom level               |
+| `map.center_latitude` / `map.center_longitude` | number | Map center                       |
+
+## Table (`display: table`)
+
+| Setting                   | Type    | Description                                               |
+| ------------------------- | ------- | --------------------------------------------------------- |
+| `table.columns`           | array   | Column order + visibility; each entry `{ name, enabled }` |
+| `table.column_formatting` | array   | Conditional formatting rules (see below)                  |
+| `table.pivot`             | boolean | Enable in-table pivot mode                                |
+| `table.pivot_column`      | string  | Column to pivot on                                        |
+| `table.cell_column`       | string  | Column used for cell values (pivot mode)                  |
+
+### Conditional formatting (`table.column_formatting`)
+
+```yaml
+table.column_formatting:
+  - columns: [Total]
+    type: single # "single" or "range"
+    operator: ">" # "=", "!=", "<", ">", "<=", ">=", "is-null", "not-null"
+    value: 100
+    color: "#84BB4C"
+    highlight_row: false
+  - columns: [Rating]
+    type: range
+    colors: ["#ED6E6E", "#F9CF48", "#84BB4C"]
+    min_type: custom # "min", "max", "custom"
+    min_value: 1
+    max_type: custom
+    max_value: 5
+```
+
+## Pivot table (`display: pivot`)
+
+| Setting                          | Type    | Description                                                     |
+| -------------------------------- | ------- | --------------------------------------------------------------- |
+| `pivot_table.column_split`       | object  | `{ rows: [...names], columns: [...names], values: [...names] }` |
+| `pivot_table.collapsed_rows`     | object  | `{ rows: [...collapsed_keys], value: [] }`                      |
+| `pivot_table.show_row_totals`    | boolean |                                                                 |
+| `pivot_table.show_column_totals` | boolean |                                                                 |
+
+## Sankey (`display: sankey`)
+
+| Setting                   | Type    | Values                                       |
+| ------------------------- | ------- | -------------------------------------------- |
+| `sankey.source`           | string  | Source column                                |
+| `sankey.target`           | string  | Target column                                |
+| `sankey.value`            | string  | Value column                                 |
+| `sankey.node_align`       | string  | `"left"`, `"right"`, `"center"`, `"justify"` |
+| `sankey.show_edge_labels` | boolean |                                              |
+
+## Column settings
+
+`column_settings` is keyed by a JSON-encoded column reference. Prefer the
+`["name", "<output column name>"]` form — it is the canonical key Metabase writes and
+is identical across forms. The `["ref", ["field", <id>, <opts>]]` form uses the
+**legacy** field-ref order (id second); in the API form `<id>` is the numeric field id.
+
+Per-column keys (apply under any column key):
+
+| Key                 | Type        | Values                                                 |
+| ------------------- | ----------- | ------------------------------------------------------ |
+| `column_title`      | string      | Override the column header                             |
+| `number_style`      | string      | `"decimal"`, `"currency"`, `"percent"`, `"scientific"` |
+| `currency`          | string      | ISO code, e.g. `"USD"`                                 |
+| `currency_style`    | string      | `"symbol"`, `"code"`, `"name"`                         |
+| `number_separators` | string      | e.g. `".,"` (decimal + thousands)                      |
+| `decimals`          | number      | Fixed decimal places                                   |
+| `scale`             | number      | Multiply values by this factor                         |
+| `prefix` / `suffix` | string      | Affixes around the value                               |
+| `date_style`        | string      | moment.js format, e.g. `"MMMM D, YYYY"`                |
+| `date_separator`    | string      | e.g. `"/"`                                             |
+| `date_abbreviate`   | boolean     |                                                        |
+| `time_enabled`      | string/null | `null`, `"minutes"`, `"seconds"`, `"milliseconds"`     |
+| `time_style`        | string      | e.g. `"HH:mm"`, `"h:mm A"`                             |
+| `view_as`           | string      | `"link"`, `"image"`, `"email"`, `"auto"`               |
+| `link_text`         | string      | Display text when `view_as: link`                      |
+| `link_url`          | string      | URL template; `{{value}}` interpolates the cell value  |
+| `click_behavior`    | object      | Per-column click behavior (see below)                  |
+
+```yaml
+column_settings:
+  '["name","TOTAL"]':
+    number_style: currency
+    currency: USD
+    currency_style: symbol
+    decimals: 2
+    column_title: "Total Revenue"
+  '["name","CREATED_AT"]':
+    date_style: "MMMM D, YYYY"
+    time_enabled: null
+  '["name","EMAIL"]':
+    view_as: link
+    link_text: "Send email"
+    link_url: "mailto:{{value}}"
+```
+
+## Virtual card settings (dashcards only, `card_id: null`)
+
+| `virtual_card.display` | Extra keys                                                                                                        |
+| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `heading`              | `text` (the heading string)                                                                                       |
+| `text`                 | `text` (markdown; `{{param}}` placeholders wired via dashcard `parameter_mappings`, target `[text-tag, name]`)    |
+| `link`                 | `link.url`, or `link.entity` `{ id, model }` where model ∈ `question`/`dashboard`/`collection`/`database`/`table` |
+| `iframe`               | `iframe` (the `<iframe …>` HTML string)                                                                           |
+| `placeholder`          | —                                                                                                                 |
+
+```yaml
+visualization_settings:
+  virtual_card:
+    display: text
+  text: "**Bold** and _italic_ markdown content"
+```
+
+## Click behavior
+
+Stored at `visualization_settings.click_behavior` (whole dashcard) or per column at
+`column_settings[<key>].click_behavior`.
+
+| `type`        | Description                                  |
+| ------------- | -------------------------------------------- |
+| `actionMenu`  | Default drill-through menu (no config)       |
+| `crossfilter` | Filter the dashboard using the clicked value |
+| `link`        | Navigate to a URL, question, or dashboard    |
+
+```yaml
+# Link to URL — {{column}} = clicked row value, {{filter:param}} = dashboard parameter
+click_behavior:
+  type: link
+  linkType: url
+  linkTemplate: "https://example.com/orders/{{ORDER_ID}}?status={{filter:status}}"
+  linkTextTemplate: "View Order {{ORDER_ID}}"
+
+# Link to another dashboard/question — targetId is the entity_id of the target
+click_behavior:
+  type: link
+  linkType: dashboard            # or "question"
+  targetId: Q_jD-f-9clKLFZ2TfUG2h
+  parameterMapping:
+    target-param-uuid:
+      id: target-param-uuid
+      source: { id: USER_ID, name: User ID, type: column }
+      target: { id: target-param-uuid, type: parameter }
+
+# Crossfilter — map a clicked column to dashboard parameters
+click_behavior:
+  type: crossfilter
+  parameterMapping:
+    param-uuid:
+      id: param-uuid
+      source: { id: CATEGORY, name: Category, type: column }
+      target: { id: param-uuid, type: parameter }
+```
+
+`parameterMapping` entries: `source` is where the value comes from
+(`{ id, name, type }`, type `"column"`/`"parameter"`); `target` is where it goes
+(`{ id, type }`, type `"parameter"`/`"dimension"`/`"variable"`). A `dimension` target
+carries a `dimension` array — the same target shape as a dashboard parameter mapping.