dbt-osmosisとは：descriptionを自動継承してドキュメント運用を楽にする

dbtでデータパイプラインを書いていると、必ずある作業が地味に時間を取ります。schema.ymlのdescription入力です。「customer_id」は顧客ID、「order_total」は注文金額、と同じカラムをBronze→Silver→Goldで何度も説明する必要があります。実装よりドキュメント整理の方が時間がかかる、という本末転倒もよくあります。

dbt-osmosisは、この問題を「上流のdescriptionを下流に自動継承する」アプローチで解決するOSSです。Z3Z1ed Loedeman氏らが中心となって開発、いまや多くのdbt組織で標準ツールになっています。基本機能と運用設計を整理します。

主要機能

最小の使い方

# インストール
pip install dbt-osmosis

# プロジェクトでschema.ymlを整える
dbt-osmosis yaml refactor --project-dir . --profiles-dir ~/.dbt

# 上流からdescriptionを継承
dbt-osmosis yaml propagate --project-dir . --profiles-dir ~/.dbt

`refactor`はschema.ymlの構造化、`propagate`はdescription継承。CIで両方を流すと、dbtプロジェクトのドキュメント状態は常にきれいに保たれる。

継承の動作例

# models/silver/orders.yml（上流）
version: 2
models:
  - name: silver_orders
    columns:
      - name: customer_id
        description: "顧客の一意識別子。CRM上のcustomer.id"
      - name: order_total
        description: "注文金額の合計（税込）"

# models/gold/fct_orders_daily.yml（下流、refactor前）
version: 2
models:
  - name: fct_orders_daily
    columns:
      - name: customer_id
      - name: order_total
      - name: order_count

# dbt-osmosis propagate 実行後
version: 2
models:
  - name: fct_orders_daily
    columns:
      - name: customer_id
        description: "顧客の一意識別子。CRM上のcustomer.id"
      - name: order_total
        description: "注文金額の合計（税込）"
      - name: order_count
        # 上流に無いカラムは継承されない

下流の同名カラムに、上流のdescriptionが自動的に入る。「同じ意味のカラムは同じ説明」という運用ルールが、ツール側で強制される。

運用パターン

CIで自動実行するのが最も効果が高い運用。「PRレビュー時にschema.ymlが整っていない」という典型的な揉め事が、ツールで自動解決される。

運用上のハマりどころ

• 自動継承の正しさは保証されない：上流が間違っていれば、下流も同じ間違いを継承する。レビュー文化との組み合わせが前提。
• カラム名の意味のずれ：上流の「amount」と下流の「amount」が違う意味（税抜きvs税込みなど）の場合、誤った継承を生む。命名規約での予防が必要。
• dbt本体バージョンへの依存：dbt-osmosisはdbtの内部APIに依存。dbtメジャーバージョン変更時に挙動確認が必須。
• 大規模プロジェクトの初回実行：propagate初回は大量変更が生じる。レビュー可能な単位に分けて段階的に実行。

向く・向かない場面

• 向く：dbtで多数のレイヤーを運用、schema.ymlのdescription整備が日常的な作業、組織で一貫したカラム説明を持ちたい
• 向かない：小規模で5〜10モデル程度、業務文脈ごとにdescriptionが大きく違うべき領域、dbt未使用

まとめ

• dbt-osmosisは上流descriptionを下流に自動継承するOSS。
• schema.ymlの整形、未定義スケルトン生成、未使用カラム検知も対応。
• CI自動実行・pre-commit hookでの運用が効果的。
• 誤った継承を防ぐため、レビュー文化と命名規約と組み合わせる。
• 中〜大規模dbtプロジェクトでドキュメント運用を劇的に楽にする。

全体像はdbt周辺ツール選定、隣接はdbt-checkpoint とは・SQLMesh vs dbt。dbt周辺整理の壁打ちは、DE-STKの初回相談（30分・無料）もご利用ください。

よくある質問（FAQ）

Q. dbt-osmosisを入れるタイミングは？

A. dbtプロジェクトのモデル数が50を超えたあたりから恩恵が大きくなります。小規模ならschema.ymlを手動で書く方が制御が効きます。「同じカラムを3層以上で説明している」「PRレビューでdescription指摘が多発」がシグナルです。

Q. カタログツール（DataHub等）との関係は？

A. dbt-osmosisで整えたschema.ymlのdescriptionは、そのままカタログツールに反映されます。「カタログに良いdescriptionを載せる」前提として、schema.ymlを整えるdbt-osmosisが有用です。カタログの選定はデータガバナンスとカタログを参照してください。

Q. propagate実行後のdiffが大きすぎてレビューが大変

A. 初回実行時のあるあるです。プロジェクト全体ではなく、モデル単位（–select オプション）で段階的に実行し、PRを小分けにすると現実的です。「Bronze層から始めて、Silver、Goldと進める」という順序が、レビュー負担を分散できます。

Q. 業務文脈ごとにdescriptionを変えたい場合は？

A. propagateで「下流のdescriptionが既にある場合は上書きしない」モードを使えば、明示的に上書きした下流のdescriptionは保持されます。「基本は自動継承、業務文脈で必要なら手動で上書き」の併用が現実的です。