| name | metadata |
| description | Set Metabase field and table metadata via the `mb` CLI — semantic types, foreign-key targets, dropdown/scan behavior, column visibility, and display names. The point is the causal chain — one metadata edit unlocks a downstream feature (a FK target enables joins and linked filters; `has_field_values` picks the filter widget; `visibility_type` can block queries). Covers `field update` / `table update`, the writable-vs-read-only split, the semantic-type catalog, why semantic types are labels not casts (and how to actually cast), and sync-vs-scan-vs-fingerprint. Triggers — "set this column as currency / email / a category", "mark this as a foreign key", "make this column a dropdown", "why doesn't the query builder suggest a join", "hide this column", "set the entity key". |
| allowed-tools | Read, Write, Edit, Bash, AskUserQuestion |
Metadata
Metabase reads the raw column types from your warehouse; metadata is the layer you edit on top to make columns behave well — the right filter widget, joins, formatting, maps. You set it per-column with mb field update <id> and per-table with mb table update <id>. Both are PATCH — send only the keys you're changing.
Metadata is a small set of fields with large, indirect effects. Get the field ids from mb table get <id> --include fields (or mb table fields <id>); inspect a column's shape with mb field get <id>, its live cardinality with mb field summary <id>, its cached distinct set with mb field values <id>. General flag/output/body mechanics live in core.
The causal chain — set X, unlock Y
This is the whole point of the skill. Each edit below is a key in the field update (or table update) body; the value change is what turns a feature on.
Set (via field update) | Unlocks / does |
|---|
semantic_type: "type/PK" | marks the row's identity key — enables record/detail view, and lets other tables' FKs point here |
semantic_type: "type/FK" + fk_target_field_id: <pk field id> | the join relationship — implicit FK joins in queries (mbql source-field), query-builder join suggestions, and dashboard linked filters |
semantic_type: "type/Currency" / type/Email / type/City / … | correct display formatting and the matching filter widget (and region/pin maps for location types) |
has_field_values: "list" (or "auto-list") | a dropdown filter widget, backed by a scanned distinct-value set |
has_field_values: "search" | a search box (no value set stored) — for high-cardinality columns |
has_field_values: "none" | a plain input box, no dropdown |
visibility_type: "sensitive" or "retired" | blocks queries that touch the field — not a UI hint, an error |
visibility_type: "hidden" | removes the column from the query builder and data reference (SQL can still read it — not access control) |
visibility_type: "details-only" | hidden in table views, shown in the single-record detail view (for long blobs) |
coercion_strategy: <strategy> | actually casts the column — the only entry here that changes the value's type (below) |
display_name / description | the human label and help text shown everywhere |
table update carries the table-level equivalents: display_name, description, visibility_type (hidden / technical / cruft — hides the whole table from the builder), field_order, and entity_type.
Foreign keys are the highest-leverage edit
A FK relationship is what makes a warehouse browsable. Set it in two keys on the FK column, in one PATCH:
mb field update 1711 --body '{"semantic_type":"type/FK","fk_target_field_id":1684}' --profile <n> --json
1711 is orders.customer_id; 1684 is customers.id (which should itself be type/PK). Once set:
- Queries can pull columns from the related table with no explicit join —
["field", {"source-field": 1711}, 1682] in MBQL (see mbql).
- Dashboard linked filters become possible (a State filter narrowing a City filter). Linked filters read only these table-metadata FKs — never a join you wrote inside a saved question — which is why a linked filter that "shows values it shouldn't" almost always means the FK isn't set in metadata. (See
dashboard.)
Removing the type/FK semantic type auto-clears fk_target_field_id. Point a FK only at a field in the same database — v60+ rejects a cross-database target; v58–v59 accept it silently and leave a broken relationship.
Semantic types are labels, not casts
The commonest misconception. semantic_type: "type/Quantity" on a text column does not make it a number — it changes formatting and widget choice, nothing about the stored value. Sorting still sorts as text.
To genuinely change the type, use coercion_strategy, which casts base_type → an effective_type (e.g. a Unix-epoch integer read as a timestamp, or a numeric string read as a number):
mb field update 42 --body '{"coercion_strategy":"Coercion/UNIXSeconds->DateTime"}' --profile <n> --json
base_type, effective_type, and the physical name are read-only — set by warehouse sync, never editable here. For a durable transformation (splitting, combining, recomputing columns), build a transform rather than leaning on coercion.
The full semantic-type catalog — every value grouped by the base type it attaches to, plus the has_field_values and visibility_type value tables and the exact writable-key lists — is in references/semantic-types.md (mb skills get metadata --full).
Sync, scan, fingerprint — three different refreshes
When a column looks stale or missing, know which one you need (db verbs, mechanics in core):
- Sync (
mb db sync-schema <id> --wait) — re-reads table/column structure (new tables, new columns, types). Run after a schema change.
- Scan / rescan (
mb db rescan-values <id>) — refreshes the distinct-value sets behind dropdown filters. Run when a list column's values changed but its dropdown is stale.
- Fingerprint — value-distribution stats (min/max, null count) computed on a sample; drives smart defaults. Refreshed by sync; not a separate CLI verb.
A newly connected database or a missing expected column usually just needs a sync-schema --wait before you conclude anything.
Don't
- Don't expect a
semantic_type to cast — it's a label. Use coercion_strategy, or a transform.
- Don't edit
name, base_type, or effective_type — they're read-only from sync.
- Don't treat
visibility_type: hidden as security — it only hides from the builder; native SQL still reads the column. Real restriction is a permissions concern, outside the CLI.
- Don't set a
type/City / type/State filter and expect a map or clean dropdown if the values are inconsistent (abbreviations mixed with full names) — fix the values first (a transform), then the metadata.
- Don't blame the data when a dashboard linked filter misbehaves — check the FK is set here first.
