dbt catalog.json の活用ガイド: ドキュメントとカタログ連携を極める

dbt で生成される catalog.json は、実データベース上のリレーションとカラムの物理情報を集約したアーティファクトです。schema.yml で書いた説明や tests などのロジカルな情報（manifest.json）と組み合わせることで、信頼できるデータカタログを構築できます。

本稿では、catalog.json の正しい位置づけと生成・運用、外部カタログとの連携パターン、そして Analytics Engineer 試験で問われやすいポイントを、実務目線で整理します。

catalog.json とは何か、どう生成されるか

catalog.json は、dbt docs generate 実行時に target ディレクトリへ出力されるアーティファクトで、アダプタ（Snowflake、BigQuery、Databricks など）が提供するメタデータ API を用いて、実スキーマ上のリレーションとカラム情報を収集します。含まれる代表的情報は、データベース/スキーマ/テーブル名、カラム名・型、コメント、（アダプタにより）行数や統計の一部です。フィールドはバージョンやアダプタにより増減しますが、物理メタデータの集約という役割は安定しています。

docs サイトの生成には manifest.json（ロジカル情報）と catalog.json（物理情報）の両方が使われます。catalog.json 単体ではリネージやドキュメント（description）は不十分で、manifest.json と突き合わせて初めて完全なカタログになります。

• 出力先: target/catalog.json（同階層に manifest.json も出力）
• 前提: プロファイル認証が有効。対象アダプタがメタデータ取得に対応していること
• 注意: 一部アダプタでは統計（row_count 等）が null になることがある
• docs サイト: dbt docs serve でローカル提供可能。CI/CDで成果物を保管すると外部連携が容易

docs generate によるアーティファクト生成の流れ

catalog.json の生成と確認（CLI）

dbt deps
# 必要に応じてモデルを実行（catalog は実テーブル照会。未作成だと取得できない場合あり）
dbt run --select my_model
# ドキュメント生成（manifest.json と catalog.json を出力）
dbt docs generate --target-path target
# ローカルで閲覧
dbt docs serve --port 8080 --target-path target
# 生成物を確認
ls -1 target | grep -E 'manifest|catalog'

ドキュメント記述と catalog.json の結びつき

モデルやカラムの説明は schema.yml に記述します。説明文や tests、meta は manifest.json に入り、catalog.json は実スキーマを照会して取得したカラム型やコメントなどを持ちます。docs サイトでは、両者がマージされ、カラム説明（ロジカル）とカラム型（物理）が同一画面に表示されます。

docs ブロック（.md で定義し doc() で参照）も manifest.json 側の情報です。結果として、catalog.json は"事実の自動収集"、manifest.json は"意図の宣言"という役割分担になります。

• schema.yml: description、columns[].description、tests、meta などを定義
• catalog.json: columns[].type、comment、table-level metadata を保持（アダプタ依存）
• docs サイトは両ファイルを突き合わせて表示
• 説明の正は schema.yml、型の正はデータベースという心構えが運用を安定させる

ロジカル情報と物理情報のマージ

 schema.yml (description/tests)   catalog.json (types/comments)
                \                      /
                 \                    /
                  v                  v
                 manifest.json   catalog.json
                         \        /
                          v      v
                           docs site

schema.yml と docs ブロックの例

# models/orders/schema.yml
version: 2
models:
  - name: fct_orders
    description: "受注のファクトテーブル。日次の粒度で集計される"
    columns:
      - name: order_id
        description: "受注ID（ユニーク）"
        tests:
          - unique
          - not_null
      - name: order_total
        description: "受注金額（税抜）"
        meta:
          pii: false
    docs:
      node_color: blue

# docs/blocks.md
{% docs fct_orders_notes %}
リファレンス: 売上確定ロジックは会計チーム合意済み。
{% enddocs %}

# models/orders/fct_orders.sql
select * from {{ ref('stg_orders') }}
-- description は manifest.json、型は catalog.json に載る

catalog.json と manifest.json の使い分けと比較

外部データカタログ連携では、基本的に manifest.json と catalog.json の両方を取り込みます。catalog.json からは物理名・カラム型を、manifest.json からは説明・所有者・リネージ・tests・exposures を取得し、統合して登録します。

注意点として、ephemeral モデルは実テーブルを作らないため、catalog.json には現れません。一方、manifest.json にはノードとして存在します。リネージ上は重要でも、物理カタログには載らないケースがある点を押さえてください。

• 物理の正: catalog.json（ただしアダプタの取得範囲に依存）
• ロジカルの正: manifest.json（プロパティ、リネージ、exposures）
• ephemeral は catalog.json に現れないが、manifest.json には存在
• 外部連携は両者の"ジョイン"が基本

三位一体で docs を構成

catalog.json のノード例（抜粋）

{
  "nodes": {
    "model.my_proj.fct_orders": {
      "database": "ANALYTICS",
      "schema": "MART",
      "name": "fct_orders",
      "resource_type": "model",
      "relation_name": "ANALYTICS.MART.FCT_ORDERS",
      "columns": {
        "ORDER_ID": {"name": "ORDER_ID", "type": "NUMBER", "comment": "受注ID"},
        "ORDER_TOTAL": {"name": "ORDER_TOTAL", "type": "NUMBER", "comment": "受注金額"}
      }
    }
  }
}

外部データカタログ連携パターン

多くのデータカタログ（例: DataHub、Amundsen、Collibra、Alation）は、dbt アーティファクトの取り込みに対応またはコミュニティ実装を持ちます。一般的には manifest.json と catalog.json のセットをアップロードまたは参照し、モデルの説明・所有者（manifest）とカラム型・コメント（catalog）を統合してエンティティを更新します。

連携方式は大きく、ポーリング（ファイル置き場を定期取得）、プッシュ（CI/CDからAPI呼出）、和解（既存スキーマメタデータに dbt 情報をマージ）の3パターン。最初はプッシュが扱いやすく、差分更新は manifest の node_version やチェックサム、ファイル更新時刻などをキーに実装します。

• プッシュ方式: CI の docs generate 後にAPIへ送信（再現性と失敗検知が容易）
• ポーリング方式: ストレージ（S3/GCS/ADLS）に定期出力し、外部が取得
• 和解: 既存カタログのスキーマ情報を基準に、dbt の説明・リネージをマージ
• 機微情報は meta で明示しつつ、外部公開前にフィルタリングする

外部カタログ連携のデータフロー

catalog.json を読み込み API へプッシュ（最小例）

import json, os, requests

ARTIFACT_DIR = os.environ.get("ARTIFACT_DIR", "target")
CAT_PATH = os.path.join(ARTIFACT_DIR, "catalog.json")
MANI_PATH = os.path.join(ARTIFACT_DIR, "manifest.json")

with open(CAT_PATH, "r", encoding="utf-8") as f:
    catalog = json.load(f)
with open(MANI_PATH, "r", encoding="utf-8") as f:
    manifest = json.load(f)

# 例: カラム定義を抽出して送信（適宜スキーマ合わせ）
payload = []
for node_id, node in catalog.get("nodes", {}).items():
    cols = node.get("columns", {})
    for c in cols.values():
        payload.append({
            "node_id": node_id,
            "relation": node.get("relation_name"),
            "column": c.get("name"),
            "type": c.get("type"),
            "comment": c.get("comment")
        })

resp = requests.post("https://catalog.example.com/api/dbt/columns", json=payload, timeout=30)
resp.raise_for_status()
print("uploaded:", len(payload))

運用とガバナンス: 更新頻度・品質・セキュリティ

catalog.json はデータベースの現況を反映します。更新頻度はモデルの更新頻度と利用部門のニーズに合わせ、少なくとも日次での再生成を推奨します。CI ではプルリク時に docs generate を走らせて差分を可視化し、本番リリース後に本番環境の catalog.json を確定させます（環境ごとに分離して保存）。

セキュリティ面では、PII カラムに対するコメント公開の可否を決め、外部連携前にフィルタリングします。統計情報はアダプタ依存であり、row_count 等が欠損することもあるため、SLA 監視には run_results.json など別のソースと併用します。

• 環境別に target を分けて保存（dev, staging, prod）
• PR で docs 差分をチェック、本番リリース後に本番 catalog.json を確定
• PII/機微コメントは除去マスクして外部連携
• 統計の有無はアダプタに依存。欠損はエラーではなく仕様の場合がある

CI/CD でのアーティファクト運用

CI で docs 生成と成果物保管（例: Bash）

# 環境変数で接続先を切替
export DBT_TARGET=prod
export DBT_PROFILES_DIR=.

# 依存取得と実行（必要に応じて）
dbt deps
# 生成（出力先を明示）
dbt docs generate --target ${DBT_TARGET} --target-path artifacts/${DBT_TARGET}/$(date +%F)

# 成果物をアップロード（擬似コマンド）
aws s3 sync artifacts/${DBT_TARGET}/$(date +%F) s3://my-bucket/dbt-artifacts/${DBT_TARGET}/$(date +%F)

試験対策の要点と落とし穴

Analytics Engineer 試験では、dbt ドキュメンテーションとアーティファクトの役割理解が頻出です。catalog.json と manifest.json の違い、docs generate/serve の挙動、exposures によるダッシュボードの記述、tests の定義範囲などを整理しましょう。

落とし穴として、ephemeral モデルが catalog.json に現れない点、run_results.json と catalog.json の混同、docs ブロックと description の使い分けが挙げられます。どの情報がどのファイルに入るかを即答できる状態にしておくと安心です。

• catalog.json = 物理、manifest.json = ロジカル、run_results.json = 実行結果
• exposures は manifest.json に入り、BI 連携のメタを表現する
• ephemeral は物理に現れない（catalog.json には出ない）
• docs generate はDB照会で物理情報を取得。認証や権限が不足すると欠落する

どの質問にどのファイルで答えるか

 物理型は? ------> catalog.json
 説明/所有者は? -> manifest.json
 実行は成功? ---> run_results.json

jq で catalog.json から特定テーブルのカラム型を抽出

TABLE_ID="model.my_proj.fct_orders"
cat target/catalog.json \
 | jq -r --arg id "$TABLE_ID" '.nodes[$id].columns | to_entries[] | "\(.value.name),\(.value.type)"'

問題で確認

よくある質問