metabase-database-metadata

Metabase データベースメタデータ形式

Metabase は、同期されたデータベース、そのテーブル、フィールドなどのデータベースメタデータを、YAML ファイルのツリーとして表します。ファイルは差分を確認しやすい形式です。数値 ID はすべて省略され、外部キーにはデータベース識別子の代わりに、["Sample Database", "PUBLIC", "ORDERS"] のような自然キーのタプルを使用します。

この形式は、このファイルと同梱されている仕様書 spec.md で定義されています（上流ソース：metabase/database-metadata）。同じプロジェクトでは、Metabase インスタンスからエクスポートした生の JSON を、仕様で定義された YAML ツリーに変換する CLI（npm の @metabase/database-metadata）も提供しています。

標準的なレイアウト

プロジェクトのすべてのメタデータは、最上位の .metadata/ ディレクトリに置かれます。

• .metadata/databases/ — YAML ツリーです。エージェントの標準的なデータソースです。 スキーマ、列、型、外部キーの関係を把握するには、これらのファイルを読み取ってください。
• .metadata/table_metadata.json — Metabase インスタンスからエクスポートした生の JSON です。databases／tables／fields のフラットな配列を含む、数メガバイト、場合によっては数ギガバイトの JSON になる可能性があります。絶対に開いたり、grep したり、ツールに渡したりしないでください。 抽出処理への入力としてのみ使用します。

.metadata/ ディレクトリは gitignore に追加してください。大規模なデータウェアハウスでは、抽出したメタデータが数ギガバイトに達することがあります。これをコミットすると、リポジトリの扱いが困難になるか、使用できなくなります。

初回セットアップ

セッション開始時に、以下の手順を先回りして実行しないでください。ユーザーがメタデータの取得やワークフローの設定を明示的に依頼した場合、またはデータベーススキーマの知識が明らかに必要な依頼（例：「ORDERS に対するクエリを書いて」「どんなテーブルがあるか説明して」）をした場合にのみ実行してください。

セットアップを開始する場合：

1. .metadata/ が gitignore に追加されていることを確認する

リポジトリの .gitignore を読み取り、.metadata/ が記載されていることを確認してください。記載されていない場合は、.gitignore を変更する前にユーザーに確認してください。たとえば次のように伝えます。

.metadata/ が .gitignore に含まれていません。これをコミットするとリポジトリが肥大化します（メタデータは数ギガバイトになることがあります）。追加してもよいですか？

ユーザーの確認後にのみ .gitignore を編集してください。

2. Metabase からメタデータをエクスポートする

Metabase インスタンスに対して POST /api/ee/serialization/metadata/export を呼び出し、レスポンスを .metadata/table_metadata.json に書き込んで table_metadata.json を取得します。このエンドポイントには、セクションを含めるかどうかを指定する 3 つのブール型クエリパラメーターがあります。いずれもデフォルトは false のため、含めたいセクションを明示的に指定する必要があります。

• with-databases — databases 配列を含めます。
• with-tables — tables 配列を含めます。
• with-fields — fields 配列を含めます。

通常、すべてをエクスポートする場合は、3 つすべてを true に設定します。ユーザーからベース URL と API キーを提供してもらいます（例：環境変数 METABASE_URL と METABASE_API_KEY）。

mkdir -p .metadata
curl -sf -X POST "$METABASE_URL/api/ee/serialization/metadata/export?with-databases=true&with-tables=true&with-fields=true" \
  -H "X-API-Key: $METABASE_API_KEY" \
  -o .metadata/table_metadata.json

ユーザーから認証情報が提供されていない場合は、呼び出しを実行する前に確認してください。

3. 抽出する

.metadata/table_metadata.json を配置したら、次を実行します。

rm -rf .metadata/databases
npx @metabase/database-metadata extract-table-metadata .metadata/table_metadata.json .metadata/databases

その後、.metadata/databases/ 以下の YAML ツリーを読み取り、ユーザーの質問に回答してください。

セッション開始時の動作

セッション開始時には、フェッチコマンドを実行しないでください。ディスク上の状態を確認するだけにしてください。

• .metadata/table_metadata.json と .metadata/databases/ の両方が存在する場合は、ツリーが十分に最新であるとみなし、そのまま使用してください。再フェッチしないでください。
• ツリーがない、または一部しかない場合は、ユーザーから必要な依頼があるまで何もせず、その後、上記の初回セットアップ手順に従ってください。

ツリーが古い、または整合していないように見える場合は、使用中にユーザーへ伝え、再フェッチするかどうかを判断してもらってください。黙って更新してはいけません。

更新（ユーザーから依頼された場合のみ）

ユーザーがメタデータの更新を明示的に依頼した場合は、エクスポートの呼び出しを再実行して .metadata/table_metadata.json を上書きし、その後、抽出手順を再実行してください。古いファイルが残らないよう、再抽出の前に必ず .metadata/databases を削除してください。

エンティティ

3 種類のエンティティと 2 種類のファイルがあります。

エンティティ	ファイル	説明
データベース	.metadata/databases/{db}/{db}.yaml	接続されたデータソース（Postgres、MySQL、BigQuery など）です。名前で識別されます。
テーブル	.metadata/databases/{db}/schemas/{schema}/tables/{table}.yaml（または、スキーマレスのデータベースでは .../tables/{table}.yaml）	物理テーブルまたはビューです。すべての列をインラインでネストした fields 配列を含みます。
フィールド	（テーブルの YAML 内にネストされ、個別のファイルはありません）	列です。base_type、database_type と、任意で effective_type、semantic_type、coercion_strategy、parent_id、fk_target_field_id を含みます。

外部キー

外部キーには数値 ID ではなく、自然キーのタプルを使用します。

• データベースの外部キー：データベース名（文字列）。例："Sample Database"
• テーブルの外部キー：[database, schema_or_null, table]。例：["Sample Database", "PUBLIC", "ORDERS"]
• フィールドの外部キー：[database, schema_or_null, table, field, ...nested_field_names]。例：JSON 展開された列 DATA.user.name の場合は ["Sample Database", "PUBLIC", "EVENTS", "DATA", "user", "name"]

フィールドレベルの外部キーは、parent_id（ネストされたフィールドの親）および fk_target_field_id（外部キー列が参照する主キー）として現れます。

フィールドの型属性

• database_type — ドライバーから取得したネイティブ型の生の文字列（BIGINT、VARCHAR、JSONB など）です。データベース固有です。
• base_type — ネイティブ型に対応する Metabase の型（type/BigInteger、type/Text、type/Structured など）です。
• effective_type — クエリ実行時に Metabase が列に適用する型です。base_type と異なる場合（つまり、型変換が設定されている場合）にのみ出力されます。
• coercion_strategy — base_type から effective_type を生成するルールです（例：Coercion/ISO8601->DateTime、Coercion/UNIXMilliSeconds->DateTime）。
• semantic_type — ビジネスドメインのラベル（type/PK、type/FK、type/Email、type/Category、type/Latitude など）です。UI と一部の分析動作を制御します。

型の階層と利用可能な型変換戦略の詳細については、同梱の仕様を参照してください。

仕様を読む

このスキルには、SKILL.md とともに、仕様のローカルスナップショットが spec.md として同梱されています。

必要になったときに読み、先回りして読み込まないでください。 SKILL.md の要約を超える詳細が実際に必要な場合にのみ、spec.md を開いてください。たとえば、base 型／semantic 型の階層全体、型変換戦略の完全な一覧、正確なフォルダーパスのルールなどです。セッションの開始時には開かず、メタデータツリーに関係のないタスクでは開かないでください。

同梱されたコピーが上流パッケージより古いようであれば、スキル自体の README.md に、extract-spec を使って更新する方法が記載されています。