dbt のプロジェクトからカラムレベルリネージを単一 HTML で生成する Claude Code Skill「dbt-lineage-docs」を試作しました

クラウド事業本部の石川です。dbt プロジェクトのカラムレベルリネージ（Column-Level Lineage、以下 CLL）を、Web サーバー不要の単一 HTML ファイルとして出力する Claude Code Skill「dbt-lineage-docs」を作成しました。

target/manifest.json とコンパイル済み SQL からリネージを抽出し、file:// で直接開ける自己完結 HTML を生成するため、生成物をそのまま Slack や社内 Wiki で共有できます。

https://github.com/ishikawa-satoru-classmethod/data-analytics-skills/tree/main/dbt-lineage-docs

dbt-lineage-docs とは

dbt-lineage-docs は、dbt のアーティファクト（manifest.json + compiled/*.sql）を sqlglot で解析し、カラム間の依存関係を抽出して、dbt docs ライクな UI を持つ単一 HTML ファイルを生成する Claude Code Skill です。

レイアウトは、左にモデルツリー、中央に詳細パネル、右にリネージグラフという dbt docs を踏襲した 3 ペイン構成で、各エッジには信頼度（Confidence）ラベルが付与されます。

主な特徴

主な特徴は以下のとおりです。

• 単一 HTML ファイル出力: ベンダー JS（Cytoscape など）を全てインライン化。file:// で開けるためサーバー不要
• カラムレベルリネージ（CLL）: テーブル間だけでなくカラム間の依存関係を可視化
• 信頼度ラベル: 各エッジに exact / inferred / unresolved / failed の 4 段階ラベルを付与
• dbt docs ライクな UI: 左ツリー + 中央詳細 + 右リネージグラフの 3 ペイン構成
• ハッシュフラグメント共有: #node=...&col=...&mode=cll 形式で特定のカラムを指す URL を共有可能
• マルチアダプタ対応: Athena / Trino / Postgres / Redshift / Snowflake / BigQuery / Spark / Databricks / DuckDB / ClickHouse
• 機密データ保護: 正規表現マスキング、SQL 埋め込み除外、メタデータ除外オプション

なぜ作ったか

dbt 公式の dbt docs generate も優れたドキュメント機能を備えていますが、カラムレベルのリネージは標準では対応していません。また、配布の際は HTTP サーバーの起動か、外部 SaaS への登録が必要になるケースが多くあります。

社内のレビュー会や顧客への共有を想定すると、メールに添付したり社内ストレージに置いて、受信側がブラウザで開くだけで完結する 1 ファイル成果物が欲しい、というニーズが背景にあります。

アーキテクチャ概要

スキル内部は以下のようなパイプライン構成になっています。

リネージ抽出には sqlglot.lineage を使用しており、AST レベルでカラムの依存を辿ります。adapter_type は dbt の adapter から sqlglot の dialect へマッピングされます（例: athena → trino、bigquery → bigquery）。

使い方

インストール

cp -r dbt-lineage-docs ./claude/skills/

実行

dbt_project ディレクトリで、Claude Code Skill /dbt-lineage-docs をを実行してください。

/dbt-lineage-docs

事前に dbt compile または dbt build を実行して target/manifest.json と target/compiled/ を生成しておく必要があります。SELECT * の展開には dbt docs generate で生成される target/catalog.json も必要です。

事前に dbt docs generate を実行しておくと、SOURCEのテーブル定義も参照できるようになります。

よく使うオプション

dbt-lineage-docs --project-dir DIR \
  --output OUT.html \
  --select marts+ \             # marts 配下のみ
  --layout dagre \              # dagre | elk
  --threads 4 \
  --strip-sql \                 # SQL を埋め込まない
  --redact 'AKIA[0-9A-Z]{16}' \ # 機密パターン（複数指定可）
  --security-report sec.json \
  --warnings-report warn.json \
  --max-html-mb 10 \
  --compress-data auto          # auto | off | gzip-base64

リネージグラフ（lineage.html）の例

以下の例では、Amazon Athena（dbt-athena）のリネージグラフを生成した例です。

左にSource、Seed、Model、右がリネージグラフが表示されます。最初からカラムレベルリネージだと見えにくいので、デフォルトではテーブルレベルリネージで表示します。

Source、Seed、Model等を選択して、上部の CCL（Column Level Lineage）ボタンを押すと展開されます。

以下、簡単なデモです。

信頼度モデル（Confidence Model）

このスキルの最大の特徴のひとつが、各エッジに付与される信頼度ラベルです。CLL は本質的にベストエフォートであり、誤った関係性をあたかも正しいかのように見せてしまうリスクが最も大きい、という設計思想に基づいています。

カラムの変換種別は transform_kind として direct / derived / aggregate / window / constant / star_expanded / unknown が記録されます。

UI 上では各カラムの信頼度がバッジで表示され、グラフのエッジは信頼度に応じて色とスタイルが変わります。unresolved や failed を含むモデルは、警告アイコン（⚠）から一覧表示できます。

対応する dbt アダプタ

dbt の adapter から sqlglot の dialect へのマッピングは以下のとおりです。

未知のアダプタは ansi にフォールバックします。--dialect オプションで明示的に上書き可能です。

既知の制約事項

CLL はベストエフォートであり、以下のケースでは unresolved 等になることを承知の上でご利用ください（詳細は references/sqlglot_pitfalls.md を参照）。

• BigQuery STRUCT/UNNEST 内部、Snowflake FLATTEN/QUALIFY、Trino lambda は unresolved になりうる
• SELECT * は catalog.json がある場合は star_expanded に展開、ない場合は unresolved
• incremental モデルの {{ this }} 自己参照はベストエフォート（自己ループとして表示）
• 集約の GROUP BY のみに登場するカラムは sqlglot の SELECT リスト追跡対象外のためリネージに現れない
• lineage_status: failed のモデルは TLL のみ表示し、コンパイル済み SQL を確認して対処

最後に

dbt-lineage-docs は、dbt プロジェクトから単一 HTML ファイルとしてカラムレベルリネージを生成し、file:// で直接配布できる Claude Code Skill です。各エッジに信頼度ラベルを付与することで、ベストエフォートな CLL を「正しく見えてしまう」リスクを抑えながら、社内の影響分析やレビューでカラム間依存を共有しやすくしています。

dbt プロジェクトのドキュメンテーションを社内・社外に配布する場面でお困りの方は、興味半分でお試しください。