metabase 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 (seembql). - 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 alistcolumn'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_typeto cast — it's a label. Usecoercion_strategy, or atransform. - Don't edit
name,base_type, oreffective_type— they're read-only from sync. - Don't treat
visibility_type: hiddenas 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/Statefilter and expect a map or clean dropdown if the values are inconsistent (abbreviations mixed with full names) — fix the values first (atransform), then the metadata. - Don't blame the data when a dashboard linked filter misbehaves — check the FK is set here first.