@metabase/cli 0.3.1-alpha.versioning.9ac5f50 → 0.3.2-alpha.fix-transform-test-ee-path.041c793

package/skill-data/mbql/references/operators.md

@@ -1,268 +1,109 @@
 # MBQL operator reference
 
-The complete clause vocabulary the bundled schema accepts, in the CLI's API/numeric
-form. The clause _structure_ and the slot-1-options rule are in the SKILL.md body —
-this file is the catalog of which operators exist and their arguments.
-
-**Reading the tables.** Every clause is `[op, {options}, ...args]`. Below, `{…}`
-abbreviates the slot-1 options object — usually empty (`{}`), since `lib/uuid` is
-optional and the server generates it (see the SKILL body). It carries a value only
-when noted: an operator-specific option named in the row, or an explicit `lib/uuid`
-you mint to reference the clause. Field refs are numeric: `["field", {…}, <field-id>]`.
-Everything here passes `mb query --dry-run`; when in doubt, that loop is the authority.
-
-**Contents**
-
-- [Filter operators](#filter-operators) — Logical, Comparison, Null/empty, String match, Temporal, Segment
-- [Aggregation functions](#aggregation-functions) — including naming and the `offset` window function
-- [Expression operators](#expression-operators) — Arithmetic, Math, String, Temporal, Type conversion, Conditional
-- [References (within clauses)](#references-within-clauses) — field, expression, aggregation
-- [Field option: temporal bucketing](#field-option-temporal-bucketing)
-- [Field option: binning](#field-option-binning)
-
-> For relative date filters, prefer **`time-interval`** / **`relative-time-interval`**
-> (below). `relative-datetime` / `absolute-datetime` literals (e.g. from a UI-built
-> query) also work.
-
----
-
-## Filter operators
-
-A stage's `filters` is a list of boolean clauses, implicitly ANDed. Nest an explicit
-`["or", {…}, …]` for OR.
-
-### Logical
-
-| Op    | Args               | Notes                                                 |
-| ----- | ------------------ | ----------------------------------------------------- |
-| `and` | 2+ boolean clauses | Logical AND (usually implicit via the `filters` list) |
-| `or`  | 2+ boolean clauses | Logical OR                                            |
-| `not` | 1 boolean clause   | Logical NOT                                           |
-
-### Comparison
-
-| Op                | Args                                                     | Notes                   |
-| ----------------- | -------------------------------------------------------- | ----------------------- |
-| `=`               | field, 1+ values                                         | Multi-value = IN        |
-| `!=`              | field, 1+ values                                         | Multi-value = NOT IN    |
-| `<` `>` `<=` `>=` | 2 orderable                                              |                         |
-| `between`         | field, min, max                                          | Inclusive               |
-| `inside`          | lat-field, lon-field, lat-max, lon-min, lat-min, lon-max | Geographic bounding box |
-
-```json
-["between", {…}, ["field", {…}, 12], 10, 100]
-["=", {…}, ["field", {…}, 7], "Widget", "Gadget"]
-```
-
-### Null / empty
-
-| Op          | Args                | Notes                 |
-| ----------- | ------------------- | --------------------- |
-| `is-null`   | 1 expression        |                       |
-| `not-null`  | 1 expression        |                       |
-| `is-empty`  | 1 string expression | NULL or `""`          |
-| `not-empty` | 1 string expression | not NULL and not `""` |
-
-### String match
-
-N-ary (multiple values OR'd). Accept a `case-sensitive` option (default `true`) in the
-options object.
-
-| Op                 | Args              |
-| ------------------ | ----------------- |
-| `contains`         | field, 1+ strings |
-| `does-not-contain` | field, 1+ strings |
-| `starts-with`      | field, 1+ strings |
-| `ends-with`        | field, 1+ strings |
-
-```json
-["contains", { "case-sensitive": false }, ["field", {…}, 9], "widget"]
-```
-
-### Temporal
-
-| Op                       | Args                                                       | Notes                                               |
-| ------------------------ | ---------------------------------------------------------- | --------------------------------------------------- |
-| `time-interval`          | temporal-field, n, unit                                    | `n` = integer, or `"current"` / `"last"` / `"next"` |
-| `relative-time-interval` | temporal-field, value, bucket, offset-value, offset-bucket | interval with offset                                |
-
-Units (truncation only): `millisecond`, `second`, `minute`, `hour`, `day`, `week`,
-`month`, `quarter`, `year`.
-
-```json
-["time-interval", {…}, ["field", {…}, 22], -30, "day"]      // last 30 days
-["time-interval", {…}, ["field", {…}, 22], "current", "month"]
-```
-
-### Segment
-
-| Op        | Args       | Notes                     |
-| --------- | ---------- | ------------------------- |
-| `segment` | segment id | Reference a saved segment |
-
----
-
-## Aggregation functions
-
-A stage's `aggregation` is a list of aggregation clauses.
-
-| Op                      | Args                       | Notes                         |
-| ----------------------- | -------------------------- | ----------------------------- |
-| `count`                 | none, or 1 expression      | with arg: count non-NULL      |
-| `sum` `avg` `min` `max` | 1 numeric/orderable        |                               |
-| `distinct`              | 1 expression               | count of distinct values      |
-| `cum-count`             | none or 1 expression       | running count                 |
-| `cum-sum`               | 1 numeric                  | running sum                   |
-| `stddev` `var` `median` | 1 numeric                  |                               |
-| `percentile`            | numeric, p (0.0–1.0)       |                               |
-| `count-where`           | 1 boolean clause           |                               |
-| `sum-where`             | numeric, boolean clause    |                               |
-| `distinct-where`        | expression, boolean clause |                               |
-| `share`                 | 1 boolean clause           | proportion 0–1                |
-| `metric`                | metric id                  | reference a saved metric card |
+Every clause is `[op, {options}, ...args]` with `{}` when there are no options. `<field>` is `["field", {}, <field id>]`, or any expression of the right type; `<pred>` is a filter clause. Clause heads are lowercase and hyphenated, exactly as written here.
+
+## Filters
+
+A stage's `filters` are ANDed.
+
+- `["and", {}, <pred>, <pred>, …]` / `["or", …]`: two or more
+- `["not", {}, <pred>]`
+- `["=", {}, <field>, <v1>, <v2>, …]` / `["!=", …]`: several values mean any of them / none of them
+- `["in", {}, <field>, <v1>, <v2>, …]` / `["not-in", …]`: multi-value membership
+- `["<", {}, <a>, <b>]` / `["<=", …]` / `[">", …]` / `[">=", …]`
+- `["between", {}, <field>, <min>, <max>]`: inclusive; dates as `"2024-01-01"`
+- `["inside", {}, <lat>, <lon>, <lat-max>, <lon-min>, <lat-min>, <lon-max>]`: bounding box
+- `["is-null", {}, <field>]` / `["not-null", …]`
+- `["is-empty", {}, <field>]` / `["not-empty", …]`: NULL or `""`
+- `["contains", {}, <field>, "a", "b", …]` / `["does-not-contain", …]` / `["starts-with", …]` / `["ends-with", …]`: any of the strings (`does-not-contain`: none of them); `{"case-sensitive": false}` in options
+- `["time-interval", {}, <field>, <n>, "<unit>"]`: the `n` whole units before the current one (`n` negative) or after it, or `"current"` / `"last"` / `"next"` for a single unit; `{"include-current": true}` in options adds the current unit
+- `["relative-time-interval", {}, <field>, <n>, "<unit>", <offset n>, "<offset unit>"]`: a window shifted from now: last 3 months, a year ago
+- `["during", {}, <field>, "2024-03-15", "<unit>"]`: the whole unit containing the date
+- `["segment", {}, <segment id>]`: a saved segment, on its table
+
+Units for `time-interval` and friends: `millisecond`, `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
+
+## Aggregations
+
+- `["count", {}]` / `["count", {}, <field>]`: rows / non-NULL values
+- `["sum", {}, <field>]` / `["avg", …]` / `["median", …]` / `["stddev", …]` / `["var", …]`: numeric
+- `["min", {}, <field>]` / `["max", …]`: any orderable
+- `["distinct", {}, <field>]`: count of distinct values
+- `["percentile", {}, <field>, 0.9]`: 0 to 1
+- `["count-where", {}, <pred>]`
+- `["sum-where", {}, <field>, <pred>]`
+- `["distinct-where", {}, <field>, <pred>]`
+- `["share", {}, <pred>]`: fraction of rows, 0 to 1
+- `["cum-count", {}]` / `["cum-sum", {}, <field>]`: running totals over the breakout
+- `["offset", {}, <aggregation>, <n>]`: the value n breakout rows back (negative) or ahead; in `aggregation` only
+- `["metric", {}, <card id>]`: a saved metric, on its table
 
 <!-- requires: measures -->
 
-`measure` takes a measure id and references a saved measure.
+`["measure", {}, <measure id>]` is a saved measure, on its table.
 
 <!-- /requires -->
 
-```json
-["count", {…}]
-["sum", {…}, ["field", {…}, 42]]
-["count-where", {…}, [">", {…}, ["field", {…}, 42], 100]]
-```
-
-**Naming** — set `name` (warehouse column) and/or `display-name` (UI header) in the
-options object: `["sum", { "name": "revenue", "display-name": "Revenue" }, …]`.
-
-**Window function** — `offset` is only valid inside `aggregation`:
-
-| Op       | Args          | Notes                                             |
-| -------- | ------------- | ------------------------------------------------- |
-| `offset` | expression, n | value n rows before (negative) / after (positive) |
-
----
-
-## Expression operators
+Name the output in options: `["sum", {"name": "revenue", "display-name": "Revenue"}, <field>]`.
 
-Used in `expressions` (named, via `lib/expression-name` in options) and inline.
+## Expressions
 
-### Arithmetic
+Named in `expressions` by `{"lib/expression-name": "<name>"}` in the options, or used inline anywhere a value goes.
 
-| Op  | Args                               | Notes                |
-| --- | ---------------------------------- | -------------------- |
-| `+` | 2+ numeric, or temporal + interval |                      |
-| `-` | 1+ numeric, or temporal − interval | unary = negation     |
-| `*` | 2+ numeric                         |                      |
-| `/` | 2+ numeric                         | always returns float |
+**Math:** `["+", {}, a, b, …]`, `["-", …]`, `["*", …]`, `["/", …]` (always a float), `["abs", {}, x]`, `["ceil", …]`, `["floor", …]`, `["round", …]`, `["sqrt", …]`, `["exp", …]`, `["log", …]`, `["power", {}, base, exponent]`. `round` takes one argument and rounds to an integer.
 
-### Math
+**Conversion:** `["integer", {}, <text or number>]`, `["float", {}, <text>]`, `["text", {}, <any>]`, `["date", {}, <text or datetime>]`, `["datetime", {}, <ISO text>]`, `["datetime", {"mode": "simple"}, <text>]`, `["datetime", {"mode": "unix-seconds"}, <number>]` (number modes `unix-seconds`, `unix-milliseconds`, `unix-microseconds`, `unix-nanoseconds`).
 
-| Op                           | Args           |
-| ---------------------------- | -------------- |
-| `abs` `ceil` `floor` `round` | 1 numeric      |
-| `power`                      | base, exponent |
-| `sqrt` `exp` `log`           | 1 numeric      |
+**Text:** `["concat", {}, a, b, …]`, `["substring", {}, s, <start from 1>, <length>?]`, `["replace", {}, s, "find", "replacement"]`, `["regex-match-first", {}, s, "<regex>"]`, `["split-part", {}, s, "<delimiter>", <position from 1>]`, `["length", {}, s]`, `["trim", …]`, `["ltrim", …]`, `["rtrim", …]`, `["upper", …]`, `["lower", …]`, `["host", {}, <url>]`, `["domain", …]`, `["subdomain", …]`, `["path", …]`.
 
-### String
-
-| Op                                 | Args                            |
-| ---------------------------------- | ------------------------------- |
-| `concat`                           | 2+ expressions                  |
-| `substring`                        | str, start (1-indexed), length? |
-| `replace`                          | str, find, replace              |
-| `regex-match-first`                | str, regex                      |
-| `split-part`                       | str, delimiter, position        |
-| `trim` `ltrim` `rtrim`             | 1 string                        |
-| `upper` `lower`                    | 1 string                        |
-| `length`                           | 1 string                        |
-| `host` `domain` `subdomain` `path` | 1 URL string                    |
-
-### Temporal
-
-| Op                                                                                  | Args                            | Notes                      |
-| ----------------------------------------------------------------------------------- | ------------------------------- | -------------------------- |
-| `now`                                                                               | none                            | datetime                   |
-| `today`                                                                             | none                            | date                       |
-| `interval`                                                                          | amount, unit                    | a temporal interval        |
-| `datetime-add`                                                                      | temporal, amount, unit          |                            |
-| `datetime-subtract`                                                                 | temporal, amount, unit          |                            |
-| `datetime-diff`                                                                     | datetime1, datetime2, unit      |                            |
-| `convert-timezone`                                                                  | temporal, target-tz, source-tz? |                            |
-| `get-year` `get-quarter` `get-month` `get-day` `get-hour` `get-minute` `get-second` | 1 temporal                      | integer component          |
-| `get-day-of-week`                                                                   | temporal, mode?                 | mode `iso`/`us`/`instance` |
-| `get-week`                                                                          | temporal, mode?                 | mode `iso`/`us`/`instance` |
-| `temporal-extract`                                                                  | temporal, unit, mode?           | generic extraction         |
-| `month-name` `quarter-name` `day-name`                                              | 1 integer                       | name from number           |
-
-Add/subtract/interval units: `year`, `quarter`, `month`, `week`, `day`, `hour`,
-`minute`, `second`, `millisecond`. `datetime-diff` units: same minus `millisecond`.
-`temporal-extract` units: `year-of-era`, `quarter-of-year`, `month-of-year`,
-`week-of-year-iso`, `week-of-year-us`, `week-of-year-instance`, `day-of-month`,
-`day-of-week`, `day-of-week-iso`, `hour-of-day`, `minute-of-hour`, `second-of-minute`.
-
-### Type conversion
-
-| Op        | Args              |
-| --------- | ----------------- |
-| `integer` | string or numeric |
-| `float`   | string            |
-| `text`    | 1 expression      |
-
-### Conditional
-
-| Op         | Args                           | Notes                                                |
-| ---------- | ------------------------------ | ---------------------------------------------------- |
-| `case`     | `[[cond, value], …]`, default? | if/then/else; default is the trailing positional arg |
-| `if`       | same as `case`                 | alias for `case`                                     |
-| `coalesce` | 2+ expressions                 | first non-null                                       |
+**Conditional:** `["case", {}, [[<pred>, <value>], [<pred>, <value>]], <default>?]` (alias `if`), `["coalesce", {}, a, b, …]`.
 
 ```json
-["case", { "lib/expression-name": "Tier" },
-  [[[">", {…}, ["field", {…}, 14], 100], "Premium"],
-   [["<=", {…}, ["field", {…}, 14], 20], "Budget"]],
-  "Standard"]
+[
+  "case",
+  { "lib/expression-name": "Tier" },
+  [
+    [[">", {}, ["field", {}, 14], 100], "Premium"],
+    [["<=", {}, ["field", {}, 14], 20], "Budget"]
+  ],
+  "Standard"
+]
 ```
 
-(`case`'s first arg is a list of `[condition, value]` pairs; the optional 4th
-positional arg is the default.)
-
----
+**Dates:**
 
-## References (within clauses)
+- `["now", {}]` / `["today", {}]`
+- `["datetime-add", {}, <date>, <n>, "<unit>"]` / `["datetime-subtract", …]`: `n` an integer
+- `["datetime-diff", {}, <from>, <to>, "<unit>"]`: units `second` … `year`; the way to subtract two dates
+- `["interval", {}, <n>, "<unit>"]`: added to a date with `+`
+- `["get-year", {}, <date>]` / `get-quarter` / `get-month` / `get-day` / `get-hour` / `get-minute` / `get-second`: an integer; a quarter is `1`–`4`
+- `["get-week", {}, <date>]` / `["get-day-of-week", {}, <date>]`: a fourth argument `"iso"`, `"us"` or `"instance"` sets the week convention
+- `["temporal-extract", {}, <date>, "<extract unit>"]`: `year-of-era`, `quarter-of-year`, `month-of-year`, `week-of-year-iso`, `week-of-year-us`, `week-of-year-instance`, `day-of-month`, `day-of-week`, `day-of-week-iso`, `hour-of-day`, `minute-of-hour`, `second-of-minute`
+- `["month-name", {}, <1–12>]` / `["quarter-name", {}, <1–4>]` / `["day-name", {}, <1–7>]`
+- `["convert-timezone", {}, <date>, "America/New_York", "<from tz>"?]`
+- `["relative-datetime", {}, <n>, "<unit>"]` / `["relative-datetime", {}, "current"]`: a point relative to now, for comparisons
+- `["absolute-datetime", {}, "2024-03-15T00:00:00", "<unit>"]`: the unit is required, `"default"` keeps the literal; a date literal (`"2024-03-15"`) takes a date unit (`day` … `year`) or `"default"`
 
-| Ref         | Shape                                | Notes                                                                          |
-| ----------- | ------------------------------------ | ------------------------------------------------------------------------------ |
-| field       | `["field", {…}, <field-id>]`         | numeric id; options may carry `base-type`, `temporal-unit`, `binning`          |
-| expression  | `["expression", {…}, "<name>"]`      | by the expression's `lib/expression-name` string                               |
-| aggregation | `["aggregation", {…}, "<agg-uuid>"]` | 3rd arg is the **string** `lib/uuid` of the target aggregation, not a position |
+Add, subtract, diff and interval units: `millisecond` (not diff), `second`, `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`.
 
-## Field option: temporal bucketing
+## Field option: `temporal-unit`
 
-`temporal-unit` in a field ref's options buckets a datetime.
+On a date field ref, mostly in `breakout`:
 
-- Truncation: `default`, `millisecond`, `second`, `minute`, `hour`, `day`, `week`,
-  `month`, `quarter`, `year`.
-- Extraction (returns an integer): `minute-of-hour`, `hour-of-day`, `day-of-week`,
-  `day-of-month`, `day-of-year`, `week-of-year`, `month-of-year`, `quarter-of-year`,
-  `year-of-era`, `second-of-minute`. (The `*-iso`/`*-us` variants are `temporal-extract`
-  operator modes, not field-option bucketing units.)
+- Truncation: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year` (and `millisecond`, `second`).
+- Extraction, an integer: `minute-of-hour`, `hour-of-day`, `day-of-week`, `day-of-month`, `day-of-year`, `week-of-year`, `month-of-year`, `quarter-of-year`, `year-of-era`, `second-of-minute`.
+- `default` lets Metabase pick.
 
-```json
-["field", { "temporal-unit": "month" }, 22]
-```
+## Field option: `binning`
 
-## Field option: binning
+On a numeric or coordinate field ref in `breakout`:
 
-`binning` in a field ref's options groups a numeric/coordinate column.
+- `{"strategy": "num-bins", "num-bins": 10}`: equal-width bins.
+- `{"strategy": "bin-width", "bin-width": 5}`: a fixed width.
+- `{"strategy": "default"}`: Metabase picks.
 
-| `strategy`  | Extra property       | Notes                            |
-| ----------- | -------------------- | -------------------------------- |
-| `num-bins`  | `num-bins` (integer) | fixed number of equal-width bins |
-| `bin-width` | `bin-width` (number) | fixed bin width                  |
-| `default`   | —                    | Metabase chooses                 |
+## References
 
-```json
-["field", { "binning": { "strategy": "num-bins", "num-bins": 10 } }, 14]
-```
+- field: `["field", {…}, <field id>]`, or `["field", {"base-type": "type/…"}, "<column name>"]` for a previous stage's or a source card's column
+- expression: `["expression", {}, "<expression name>"]`, same stage
+- aggregation: `["aggregation", {}, "<lib/uuid>"]`, the `lib/uuid` (from `mb uuid`) set in the options of an aggregation of the same stage

package/skill-data/native-sql/SKILL.md

@@ -8,7 +8,7 @@ allowed-tools: Read, Write, Edit, Bash, AskUserQuestion
 
 **Prefer a structured query.** Native SQL is a Metabase query whose single stage is raw SQL (`mbql.stage/native`) instead of structured MBQL (`mbql.stage/mbql`) — both are the same query envelope (`mbql`). Reach for a native stage only when a structured query genuinely can't express it — engine-specific functions, CTEs, window logic beyond `offset`, hairy hand-tuned SQL — or when the user asks for SQL. If you can write it as a structured stage, do.
 
-General flag conventions, body-input precedence, `./.scratch`, and `mb uuid` mechanics live in `core` (`mb skills get core`).
+General flag conventions, body-input precedence and `./.scratch` live in `core` (`mb skills get core`).
 
 ## The shape
 
@@ -28,13 +28,13 @@ A native `dataset_query` is a query with one **native stage** — the `lib/type:
 }
 ```
 
-This is the form a card stores and returns — author it. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `--print-schema → --dry-run → run` loop (`mbql`), and a saved card **round-trips** in exactly this shape: `mb card get <id> --full --json`, edit the `stages[0].native` string, send it straight back. Only the SQL string is opaque to pre-flight — a **SQL** syntax error surfaces just when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
+This is the form a card stores and returns — author it. The CLI **pre-flight-validates** it — the envelope, the template-tag shapes, the field refs — through the usual `--print-schema → --dry-run → run` loop (`mbql`), and a saved card **round-trips** in exactly this shape: `mb card get <id> --full --json`, edit the `stages[0].native` string, send it straight back. Only the warehouse parses the SQL string, so a **SQL** syntax error surfaces when you run it, not at `--dry-run`. A parameterless query needs no `template-tags` — just the `native` string.
 
 You may see an older flat form in cards created long ago — `{database, type:"native", native:{query}}`. The server still accepts it (it normalizes to the above) but it skips pre-flight and doesn't round-trip — **don't author it**.
 
 ## Parameters are template tags
 
-Every `{{name}}` in the SQL must have a matching entry in the stage's `template-tags`, keyed by that name. **The three must agree exactly:** the `{{name}}` in SQL = the map key = the entry's `"name"` field. Names are case-sensitive (`{{Cat}}` ≠ `{{cat}}`). A `{{name}}` with no entry fails at run time; an unused entry is ignored.
+Every `{{name}}` in the SQL must have a matching entry in the stage's `template-tags`, keyed by that name. **The three must agree exactly:** the `{{name}}` in SQL = the map key = the entry's `"name"` field. Names are case-sensitive (`{{Cat}}` ≠ `{{cat}}`). A `{{name}}` with no entry fails at run time; an unused entry is ignored. `--dry-run` and a run fail on a raw variable with no value or `default` outside an optional `[[ … ]]` clause, and on any `"required": true` tag with no value; a field filter with no value compiles to `1 = 1` and matches every row.
 
 Four kinds of tag, by `type`:
 
@@ -45,7 +45,7 @@ Four kinds of tag, by `type`:
 | **Snippet**        | `snippet`                        | `{{snippet: Active Rows}}`    | a reusable SQL fragment (`mb snippet`)       |
 | **Card reference** | `card`                           | `{{#42}}` or `{{#42-slug}}`   | another saved query, as a subquery           |
 
-Give each tag an `id` — mint one per tag with `mb uuid` (never hand-write one). Wrap any clause that should be droppable when its value is empty in **`[[ … ]]`**, keyword and all: `[[AND {{status}}]]`, not `AND [[{{status}}]]`. Only one level of nesting; a query using several optional `[[AND …]]` blocks needs a real `WHERE` first (e.g. `WHERE true [[AND {{a}}]] [[AND {{b}}]]`).
+Give each tag an `id`, unique among the tags; the tag's name serves. Wrap any clause that should be droppable when its value is empty in **`[[ … ]]`**, keyword and all: `[[AND {{status}}]]`, not `AND [[{{status}}]]`. Only one level of nesting; a query using several optional `[[AND …]]` blocks needs a real `WHERE` first (e.g. `WHERE true [[AND {{a}}]] [[AND {{b}}]]`).
 
 ## The decision that matters: field filter vs. raw variable
 
@@ -62,7 +62,7 @@ Field filters only bind to a **real, connected database column** — not an expr
 
 ```json
 "status": {
-  "id": "9ddca4ca-3906-83fd-bc6b-8480ae9ab05e",
+  "id": "status",
   "name": "status",
   "display-name": "Status",
   "type": "dimension",
@@ -71,7 +71,7 @@ Field filters only bind to a **real, connected database column** — not an expr
 }
 ```
 
-**`dimension` is a field ref: `["field", {options}, <field-id>]`** — options object **second**, id **third**, exactly the `mbql` rule. The legacy `["field", <id>, null]` shape (id first) that the UI and older docs show is **rejected by pre-flight** here (`must be the field options object`). Send `{}` for the options; the server fills in a `lib/uuid`. The field id comes from `table get <id> --include fields`.
+**`dimension` is a field ref: `["field", {options}, <field-id>]`** — options object **second**, id **third**, exactly the `mbql` rule. Send `{}` for the options. The field id comes from `table get <id> --include fields`.
 
 `widget-type` must suit the column's type and is a closed enum (same vocabulary as dashboard filter `type`): string ops (`string/=`, `string/!=`, `string/contains`, `string/starts-with`, …), number ops (`number/=`, `number/between`, `number/>=`, …), dates (`date/all-options`, `date/range`, `date/relative`, `date/month-year`, …), plus `category`, `id`, `boolean/=`, and the `location/*` set. Text column → a `string/*` or `category`; datetime → a `date/*`; numeric → a `number/*`. `date/all-options` is the most flexible date widget.
 
@@ -79,7 +79,7 @@ Field filters only bind to a **real, connected database column** — not an expr
 
 ```json
 "min_total": {
-  "id": "35f1ecd4-d622-6d14-54be-750c498043cb",
+  "id": "min_total",
   "name": "min_total",
   "display-name": "Minimum total",
   "type": "number",
@@ -98,7 +98,7 @@ Snippet and card-reference bodies (and the full field list for every kind) are i
 
 ## Wiring, defaults, and running
 
-**Give a tag a default or a dropdown source** by declaring it in the card's `parameters` array (alongside `dataset_query`) — this is where `default`, and a `values_source_type` (`static-list` / `card`) live. Its `target` links back to the tag: `["dimension", ["template-tag", "status"]]` for a field filter, `["variable", ["template-tag", "min_total"]]` for a raw variable. (Metabase auto-derives basic `parameters` from the template tags, so you only declare them to add defaults or a value source.)
+**A tag's default is the tag's own `default`.** Metabase derives the card's `parameters` from the template tags; declare one in the card's `parameters` array (alongside `dataset_query`) only to give it a dropdown source, `values_source_type` (`static-list` / `card`). The declared parameter's `id` is the tag's `id`, and its `target` links back to the tag: `["dimension", ["template-tag", "status"]]` for a field filter, `["variable", ["template-tag", "min_total"]]` for a raw variable.
 
 **Run a saved card with values** via `card query`, whose `--parameters` is a JSON array of `{type, target, value}` — same `target` grammar:
 
@@ -111,7 +111,6 @@ mb card query 12 --parameters '[{"type":"string/=","target":["dimension",["templ
 ## Don't
 
 - Don't wrap a field filter in an operator (`WHERE col = {{ff}}`) — write it bare (`WHERE {{ff}}`).
-- Don't write the field-filter `dimension` in the legacy `["field", id, null]` shape — use `["field", {}, id]` (options second).
 - Don't author the flat `{type:"native", …}` form — send the native stage above.
 - Don't use native SQL for DDL or multiple statements — the editor is read-only, single-statement; `CREATE`/`UPDATE`/`;`-chained SQL is unsupported. To materialize a table, use a `transform`.
 - Don't expect `[[ ]]` to save you from a case/type mismatch — `WHERE plan = {{p}}` returns zero rows on a case-sensitive engine if the value's case is off; that's a value problem, not syntax.

package/skill-data/native-sql/references/template-tags.md

@@ -4,13 +4,13 @@ Every template-tag body, the widget-type vocabulary, and the parameter-object sh
 
 ## Template-tag bodies by `type`
 
-The `template-tags` value is a map keyed by tag name; each entry's `name` must equal its key and the `{{name}}` in the SQL. `id` is a UUID — mint with `mb uuid`.
+The `template-tags` value is a map keyed by tag name; each entry's `name` must equal its key and the `{{name}}` in the SQL. `id` is any string unique among the tags; the tag's name serves.
 
 ### Raw variable — `text` / `number` / `date` / `boolean`
 
 ```json
 "min_total": {
-  "id": "<uuid>",
+  "id": "min_total",
   "name": "min_total",
   "display-name": "Minimum total",
   "type": "number",
@@ -24,7 +24,7 @@ The `template-tags` value is a map keyed by tag name; each entry's `name` must e
 | `name`         | ✓   | equals map key and `{{name}}`                |
 | `display-name` | ✓   | label shown in the widget                    |
 | `type`         | ✓   | `text` \| `number` \| `date` \| `boolean`    |
-| `id`           | —   | UUID; supply one                             |
+| `id`           | ✓   | unique among the tags; the tag's name        |
 | `required`     | —   | `true` blocks the run until a value is given |
 | `default`      | —   | value used when none passed (string form)    |
 
@@ -34,34 +34,31 @@ SQL: `{{min_total}}`, spliced literally — you write the operator (`total > {{m
 
 ```json
 "status": {
-  "id": "<uuid>",
+  "id": "status",
   "name": "status",
   "display-name": "Status",
   "type": "dimension",
   "dimension": ["field", {}, 141],
-  "widget-type": "string/=",
-  "default": null,
-  "options": null,
-  "alias": null
+  "widget-type": "string/="
 }
 ```
 
-| Field         | Req | Notes                                                                                                                                                  |
-| ------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `type`        | ✓   | `"dimension"`                                                                                                                                          |
-| `dimension`   | ✓   | field ref `["field", {}, <id>]` — options object second, id third (the `mbql` rule); the legacy `["field", <id>, null]` form is rejected by pre-flight |
-| `widget-type` | ✓   | the widget/operator; must suit the column type (table below)                                                                                           |
-| `default`     | —   | e.g. a value, or a `["2024-01-01","2024-12-31"]` range                                                                                                 |
-| `options`     | —   | filter options map (e.g. case sensitivity), usually `null`                                                                                             |
-| `alias`       | —   | set when the column comes from an aliased table in the SQL                                                                                             |
+| Field         | Req | Notes                                                                               |
+| ------------- | --- | ----------------------------------------------------------------------------------- |
+| `type`        | ✓   | `"dimension"`                                                                       |
+| `dimension`   | ✓   | field ref `["field", {}, <id>]` — options object second, id third (the `mbql` rule) |
+| `widget-type` | ✓   | the widget/operator; must suit the column type (table below)                        |
+| `default`     | —   | e.g. a value, or a `["2024-01-01","2024-12-31"]` range                              |
+| `options`     | —   | filter options map (e.g. case sensitivity)                                          |
+| `alias`       | —   | set when the column comes from an aliased table in the SQL                          |
 
-SQL: bare — `WHERE {{status}}`. Never `WHERE status = {{status}}`. On write, send `{}` for the ref's options; the server fills a `lib/uuid` and the card reads back `["field", {"lib/uuid": "…"}, <id>]`.
+SQL: bare — `WHERE {{status}}`. Never `WHERE status = {{status}}`.
 
 ### Snippet — `snippet`
 
 ```json
 "snippet: Active Rows": {
-  "id": "<uuid>",
+  "id": "snippet: Active Rows",
   "name": "snippet: Active Rows",
   "display-name": "Snippet: Active Rows",
   "type": "snippet",
@@ -76,7 +73,7 @@ SQL: `{{snippet: Active Rows}}`. Create/manage the fragment with `mb snippet` (`
 
 ```json
 "#42": {
-  "id": "<uuid>",
+  "id": "#42",
   "name": "#42",
   "display-name": "#42",
   "type": "card",
@@ -96,7 +93,7 @@ A niche type that references a warehouse table by id (`{type: "table", table-id:
 
 ### Temporal unit — `temporal-unit`
 
-A widget that lets the viewer pick the time bucket (day/week/month/…) for a datetime column. Body mirrors a field filter (`dimension` legacy ref, optional `alias`) with `type: "temporal-unit"`.
+A widget that lets the viewer pick the time bucket (day/week/month/…) for a datetime column. Body mirrors a field filter (`dimension` field ref, optional `alias`) with `type: "temporal-unit"`.
 
 ## `widget-type` by column type
 
@@ -117,16 +114,15 @@ Closed enum — same vocabulary as a dashboard parameter `type`. Pick one whose
 
 Same object, two contexts. `target` links the parameter to a template tag: `["dimension", ["template-tag", "<name>"]]` for a field filter, `["variable", ["template-tag", "<name>"]]` for a raw variable.
 
-**Declared** — in the card's `parameters` array, to set a default or a dropdown source:
+**Declared** — in the card's `parameters` array, to set a dropdown source. Its `id` is the tag's `id`; the default is the tag's `default`:
 
 ```json
 {
-  "id": "<uuid>",
+  "id": "status",
   "name": "status",
   "slug": "status",
   "type": "string/=",
   "target": ["dimension", ["template-tag", "status"]],
-  "default": "active",
   "values_source_type": "static-list",
   "values_source_config": { "values": ["active", "churned", "trial"] }
 }
@@ -160,14 +156,14 @@ What `mb card create --file` consumes:
         "native": "SELECT status, count(*) FROM orders WHERE total > {{min_total}} [[AND {{status}}]] GROUP BY status",
         "template-tags": {
           "min_total": {
-            "id": "<uuid>",
+            "id": "min_total",
             "name": "min_total",
             "display-name": "Minimum total",
             "type": "number",
             "default": "0"
           },
           "status": {
-            "id": "<uuid>",
+            "id": "status",
             "name": "status",
             "display-name": "Status",
             "type": "dimension",