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 の起動とメタデータの読み込みだけでおよそ 1 分かかり、さらにクエリのコンパイル時間がツリーの規模に応じて加わります。

チェッカーは Metabase Enterprise JAR に含まれており、--mode checker を指定して実行します。デフォルトの Docker イメージは metabase/metabase-enterprise:latest です。metabase/metabase-enterprise-head:latest は、未リリースのチェッカー変更のテストなど、ユーザーが開発中ビルドを明示的に希望する場合にのみ使用してください。

入力

必須の入力は 2 つです。

• Representation ツリー — collections/、databases/、transforms/、python_libraries/ を含むリポジトリのルートです。これがチェック対象です。
• データベースのメタデータ — Metabase インスタンスからエクスポートした JSON ファイルです。デフォルトの場所は .metadata/table_metadata.json です。 チェッカーはクエリ内の列やテーブルの参照解決にこのファイルを使用します。ファイルがない場合、クエリレベルのチェックは実行できません。

.metadata/table_metadata.json がない場合は、チェッカーを実行しないでください。 まず Metabase インスタンスからエクスポートする必要があることをユーザーに伝え、メタデータファイルがディスク上に存在するようになってからチェッカーを実行してください。

実行するタイミング

編集時にセマンティックチェッカーをデフォルトで実行しないでください。 実行には時間がかかり（1 回あたり 1 分以上）、ほとんどのプロジェクトでは、すべての push や PR で実行される CI ステップとして組み込まれています。実行する場所は CI です。ローカルでの実行は、日常的な検証ではなく、対象を絞った問題の診断に使用します。

次のいずれかをユーザーが明示的に依頼した場合にのみ、ローカルで実行してください。

• すべてのエンティティ参照（コレクション、ダッシュボード、カード、スニペット、変換タグなど）が解決されることを確認する。
• クエリ内の列参照（MBQL または SQL）がすべて正しいことを確認する。

明示的な依頼とみなされる表現の例：「セマンティックチェック」「参照をチェック」「スキーマに照らしてクエリを検証」「列がまだ存在することを確認」、または、ユーザーがすでに疑っている参照切れの診断です。単に「チェッカーを実行して」と言われただけでは該当しません。デフォルトで「チェッカー」は高速なスキーマチェッカー（npx @metabase/representations validate-schema）を意味します。参照やクエリを明示する表現がある場合に限り、セマンティックチェッカーを実行してください。

それ以外の場合は実行しないでください。YAML を編集した後は、ローカルでの確認に npx @metabase/representations validate-schema を使用し、セマンティックチェックは CI に任せてください。セッション開始時に先回りして実行したり、ユーザーから依頼されていないのに編集後の「仕上げ」として実行したりしないでください。

実行する場合は、まとめて実行してください。 YAML の変更をすべて完了してから、チェッカーを 1 回実行します。実行のたびに 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 はそのままユーザーに提示してください。問題のある参照箇所をユーザーが特定する手がかりとなるため、具体的なパスやエンティティ名を要約で省かないでください。

よくある失敗の原因

• 「Database metadata not found」／スキーマ読み込みエラー — .metadata/table_metadata.json が存在しない、古い、または形式が正しくありません。ユーザーに Metabase インスタンスから再度エクスポートするよう依頼してください。
• 不明なコレクション／カード／ダッシュボード／スニペット／タグの参照 — 参照先の entity_id または名前がツリーに存在しません。対象の YAML がないか、参照に誤記があります。ツリー内で ID／名前を grep して、どちらかを確認してください。
• クエリ内の不明なテーブルまたはフィールド — クエリが、データベースメタデータに登録されていない列を参照しています。データウェアハウスのスキーマに変更があった（メタデータを再取得してください）か、クエリ自体に誤りがあります。
• Docker イメージが見つからない／取得されていない — まず docker pull metabase/metabase-enterprise:latest を実行してください。ネットワークが遅い場合はユーザーに伝えてください。イメージのサイズは数百 MB あります。