metabase-semantic-checker

Metabase semantic checker

The semantic checker validates a tree of Metabase Representation Format YAML files for referential integrity. Schema-level validation (shape of each file, required fields, enum values) is handled separately by npx @metabase/representations validate-schema; the semantic checker runs after schema validation and focuses on cross-file and cross-system consistency.

It compiles every MBQL query down to SQL against the database metadata and checks that each entity reference and each column reference resolves to something that actually exists. Concretely, it answers:

• Does every collection_id, parent_id, dashboard_id, document_id, based_on_card_id, transform tag, snippet name, etc. resolve to an entity that actually exists in the tree?
• For each MBQL query, do every source-table, field reference, join target, segment, measure, and expression resolve against the database schema? (Verified by compiling the query to SQL.)
• For each native query, do the referenced tables, columns, and snippets exist?
• Do dashboards' and documents' embedded card references point at real cards?

Each run takes 1 minute or more — roughly a minute of fixed JVM + metadata-loading overhead before any checks start, plus query-compilation time that scales with the tree.

The checker ships inside the Metabase Enterprise JAR and is invoked via --mode checker. Default Docker image: metabase/metabase-enterprise:latest. Use metabase/metabase-enterprise-head:latest only when the user explicitly wants the in-development build — e.g. testing unreleased checker changes.

Inputs

Two inputs, both required: