metabase-semantic-checker

Metabase 语义检查器

语义检查器会验证一棵 Metabase Representation Format YAML 文件树中的引用完整性。架构级验证（每个文件的结构、必填字段、枚举值）由 npx @metabase/representations validate-schema 单独处理；语义检查器在架构验证之后运行，重点检查跨文件和跨系统的一致性。

它会根据数据库元数据将每个 MBQL 查询编译为 SQL，并检查每个实体引用和列引用是否都能解析到实际存在的对象。具体来说，它会检查：

• 每个 collection_id、parent_id、dashboard_id、document_id、based_on_card_id、转换标签、代码片段名称等，是否都能解析到树中实际存在的实体？
• 对于每个 MBQL 查询，source-table、字段引用、联接目标、分段、度量和表达式是否都能根据数据库架构解析？（通过将查询编译为 SQL 进行验证。）
• 对于每个原生查询，引用的表、列和代码片段是否都存在？
• 仪表板和文档中嵌入的卡片引用是否指向实际存在的卡片？

每次运行都需要 1 分钟或更久——在开始任何检查之前，大约需要一分钟来完成固定的 JVM 和元数据加载开销，之后的查询编译时间则会随文件树规模增长。

检查器包含在 Metabase Enterprise JAR 中，通过 --mode checker 调用。默认 Docker 镜像：metabase/metabase-enterprise:latest。只有用户明确需要开发中的版本（例如测试尚未发布的检查器改动）时，才使用 metabase/metabase-enterprise-head:latest。

输入

需要两个输入，缺一不可：

• 表示文件树——包含 collections/、databases/、transforms/、python_libraries/ 的仓库根目录。这是待检查的内容。
• 数据库元数据——从 Metabase 实例导出的 JSON 文件。**默认位于 .metadata/table_metadata.json。**检查器会用它解析查询中的列和表引用；没有该文件，就无法运行查询级检查。

如果缺少 .metadata/table_metadata.json，不要运行检查器。请告知用户需要先从其 Metabase 实例导出该文件，并且只有在磁盘上存在元数据文件后才能运行检查器。

何时运行

**默认情况下，进行编辑时不要运行语义检查器。**它运行缓慢（每次至少 1 分钟），而且在大多数项目中，它已配置为 CI 步骤，会在每次推送或 PR 时运行——这才是它应该运行的地方。本地运行用于有针对性的诊断，而非例行验证。

只有在用户明确要求执行以下操作之一时，才在本地运行：

• 验证所有实体引用是否都能解析（集合、仪表板、卡片、代码片段、转换标签等）；或
• 验证查询中的所有列引用（MBQL 或 SQL）是否正确。

以下说法算作明确要求：“语义检查”“检查引用”“根据架构验证查询”“确保这些列仍然存在”，或者诊断用户已怀疑存在的引用错误。单独说“运行检查器”不算——默认情况下，“检查器”指快速架构检查器（npx @metabase/representations validate-schema）。只有明确提到引用或查询的说法才应触发语义检查器。

否则，跳过它。编辑 YAML 后，使用 npx @metabase/representations validate-schema 获取本地反馈，并将语义检查留给 CI。不要在会话开始时主动运行它，也不要在编辑后把它当作自设的“收尾步骤”运行，除非用户提出了要求。

**如果确实要运行，请合并批量处理。**先完成所有 YAML 更改，再运行一次检查器。每次调用都会产生至少 1 分钟的固定开销；在编辑过程中反复运行会成倍增加这项开销。如果检查发现问题，请先一次性修复所有可见问题，再重新运行。

运行检查器

.metadata/table_metadata.json 文件存在且 Docker 可用后：

docker pull metabase/metabase-enterprise:latest

docker run --rm \
  -v "$PWD:/workspace" \
  --entrypoint "" \
  -w /app \
  metabase/metabase-enterprise:latest \
  java -jar metabase.jar \
    --mode checker \
    --export /workspace \
    --schema-dir /workspace/.metadata/table_metadata.json \
    --schema-format concise

标志参考：

• --mode checker — 选择语义检查模式（跳过服务启动、导入等操作）。
• --export /workspace — 表示树根目录在容器内的路径。通过上面的 -v "$PWD:/workspace" 挂载，它映射到主机上的当前仓库根目录。
• --schema-dir /workspace/.metadata/table_metadata.json — 数据库元数据 JSON 文件的路径。尽管标志名称带有 -dir 后缀，但它接受的是单个 JSON 文件。只有当用户将元数据存储在非默认路径时，才应将其指向其他位置。
• --schema-format concise — 输入元数据的格式。concise 与 Metabase 实例导出的格式一致。除非用户明确使用了其他转储格式，否则不要更改。

检查本身不需要容器访问网络；如果主机网络可能不稳定，请先拉取镜像。

发现问题时，退出代码为非零。请将检查器的 stdout/stderr 原样呈现给用户；不要省略具体路径或实体名称，因为用户需要根据这些信息定位错误引用。

常见故障模式

• “未找到数据库元数据”／架构加载错误 — .metadata/table_metadata.json 缺失、已过时或格式错误。请用户从其 Metabase 实例重新导出该文件。
• 未知集合／卡片／仪表板／片段／标签引用 — 被引用的 entity_id 或名称在树中不存在。可能是目标 YAML 缺失，也可能是引用中的拼写错误；请在树中 grep 该 ID／名称以确认具体原因。
• 查询中存在未知表或字段 — 查询引用了数据库元数据中不存在的列。可能是数据仓库架构已发生变化（重新获取元数据），也可能是查询本身有误。
• 缺少 Docker 镜像／尚未拉取 — 先运行 docker pull metabase/metabase-enterprise:latest。网络较慢时请提醒用户；该镜像有数百 MB 大。