こんにちは、六本木アナリティクスエンジニアのTaku（@aelabdata ）です。
dbt入門の第10回です。前回は、dbtのマテリアライゼーションに焦点を当て、モデルを物理的にどのようにデータウェアハウス上に構築するか（viewにするのかtableにするのかなど）という「作り方」を学びました。
dbtでデータモデルを実体化：Materializations
今回は、モデルの「使い方」と「信頼性」を高めるためのドキュメンテーションに焦点を当てます。
ドキュメンテーションは、地味で手間のかかる作業だと思われがちですが、このステップこそがプロジェクトの価値を長期的に高め、チーム全体の生産性を向上させる鍵となります。
それでは、dbtにおけるドキュメンテーションの重要性から見ていきましょう。
dbtにおけるドキュメンテーションの重要性
dbtにおけるドキュメンテーションとは、具体的にはモデルやカラムの定義、関連情報などを記述したYAMLファイル（例：schema.yml）のことを指します。
なぜドキュメンテーションが重要なのでしょうか。その理由は、主に以下の3つの観点から説明できます。
- 属人化の解消とコラボレーションの促進
- ドキュメントが整備されていれば、プロジェクトに新しく参加したメンバーや、他のチームのメンバーがモデルを見ても、その目的や各カラムの意味を迅速に理解できます。
- 「このカラムは何を表しているんだろう？」と作成者を探し回る必要がなくなり、チーム全体の開発がスムーズになります。
- データ品質と信頼性の向上
- モデルやカラムの定義が明確になることで、意図しない使われ方を防ぐことができます。
- 例えば、「
order_totalというカラムは税込み金額なのか、税抜き金額なのか」といった曖昧さがなくなり、分析結果の誤りを未然に防ぎ、データの信頼性を向上させます。
- データディスカバリの効率化
- BIツールなどでデータを探索する際、データアナリストやビジネスユーザーは、どのデータを使えば良いか迷うことがよくあります。
- dbt Docsを参照することで、各データモデルの定義やビジネス上の意味を理解し、必要なデータを迅速に見つけられるようになります。
ドキュメンテーションの重要性を理解したところで、次はいよいよ、この重要な作業を効率的に実践する方法を見ていきましょう。
実践：dbtプロジェクトにドキュメントを追加しよう
ドキュメンテーションの重要性は理解できても、全てのモデルとカラムに対して手作業でYAMLファイルを作成し、記述していくのは大変な労力がかかります。特にプロジェクトの初期段階や、カラム数が多いモデルを扱う場合、この作業は大きなハードルとなりがちです。
しかし、このハードルを劇的に下げてくれるツールが存在します。それがdbt-osmosisです。このツールを活用することで、面倒な定型作業を自動化し、より本質的な「説明を書く」作業に集中することができます。
dbtプロジェクトにおいて、モデルのメタデータ（説明やテストなど）は.ymlファイルに記述します。しかし、モデルやカラムが増えるたびにこれを手作業で作成・更新するのは非常に手間がかかり、記述ミスの原因にもなります。
そこで役立つのがdbt-osmosisです。これはdbtプロジェクトのYAMLファイル管理を自動化するためのツールで、modelsディレクトリ内の.sqlファイルを解析し、対応する.ymlファイルの雛形を自動で生成してくれます。これにより、ドキュメントの構造ではなく、その内容に集中できます。
YAMLファイルの命名と保存先の設定を、dbt_project.ymlファイルに追記します。
...
models:
jaffle_shop_tutorial:
staging:
+materialized: view
+dbt-osmosis: "_{parent}.yml"
marts:
+materialized: table
+dbt-osmosis: "_{model}.yml"
# Configuring seeds
seeds:
jaffle_shop_tutorial:
+schema: raw
+dbt-osmosis: "_seed.yml"
プロジェクトのルートディレクトリで以下のコマンドを実行してください。
dbt-osmosis yaml refactorこのコマンドは、modelsディレクトリ内のすべての.sqlファイルをスキャンし、まだ.ymlファイルに定義されていないモデルやカラムを検出し、対応するYAMLファイルを自動で生成または更新します。
自動生成されたYAMLファイルはあくまで雛形であり、各カラムのdescription（説明）など、ビジネス的な意味合いを持つ情報は自動では入力されないので、各項目に適切な説明を追記していきましょう。
dbt-osmosisは多機能なツールです。プロジェクトが成長するにつれて役立つ他のコマンドも覚えておきましょう。
dbt-osmosis yaml organize: 既存のYAMLファイルを、設定したルールに従って整理・整形したいだけの場合に使います。dbt-osmosis yaml document:sourceに記載したドキュメントを、それを参照しているstagingモデルに伝播させたい場合などに使うコマンドです。
.ymlファイルに直接長い説明を書くと、ファイルが肥大化し、可読性が低下することがあります。特に、複数のモデルで共通して使われるカラムの定義などを記述する場合、同じ説明を何度もコピー＆ペーストすることになり、管理が煩雑になります。
この問題を解決するのがdoc blocksです。doc blocksを使うと、Markdownファイル（.md）に記述したドキュメントを.ymlファイルから参照できます。これにより、ドキュメントとモデル定義をDRY（Don’t Repeat Yourself）の原則に則って分離し、管理しやすくするメリットがあります。
具体的な手順は以下の通りです。jaffle_shopプロジェクトのsku（商品説明）を例に進めます。
Step1: Markdownファイルにdoc blockを定義
dbtプロジェクトのベストプラクティスとして、関連するメタデータファイルは先頭にアンダースコアを付けてグルーピングします。これにより、特定のソースに関連するドキュメントやモデル定義を簡単に見つけることができます。
models/staging/jaffle_shop/_jaffle_shop__docs.md というパスにファイルを作成し、以下のようにskuの説明を記述します。
{% docs item_sku %}
One of the following values:
| sku | name | description |
|----------|-----------------------------|-----------------------------------------------------------------------------------------------|
| JAF-001 | nutellaphone who dis? | nutella and banana jaffle |
| JAF-002 | doctor stew | house-made beef stew jaffle |
| JAF-003 | the krautback | lamb and pork bratwurst with house-pickled cabbage sauerkraut and mustard |
| JAF-004 | flame impala | pulled pork and pineapple al pastor marinated in ghost pepper sauce, kevin parker's favorite!|
| JAF-005 | mel-bun | melon and minced beef bao, in a jaffle, savory and sweet |
| BEV-001 | tangaroo | mango and tangerine smoothie |
| BEV-002 | chai and mighty | oatmilk chai latte with protein boost |
| BEV-003 | vanilla ice | iced coffee with house-made french vanilla syrup |
| BEV-004 | for richer or pourover | daily selection of single estate beans for a delicious hot pourover |
| BEV-005 | adele-ade | a kiwi and lime agua fresca, hello from the other side of thirst |
{% enddocs %}Step2: .ymlファイルからdoc()関数で参照
次に、models/staging/jaffle_shop/_jaffle_shop__sources.yml のようなYAMLファイルで、skuカラムのdescriptionを以下のように記述します。
...
- name: sku
description: "{{ doc('item_sku') }}"
...このようにすることで、skuというドキュメントを複数のモデルから再利用でき、修正が必要な場合もMarkdownファイルを一箇所変更するだけで済みます。
以下のコマンドを実行して、stagingモデル以降にskuカラムのdesctiptionを反映させます。--use-unrendered-descriptionsオプションを指定することで、{{ doc('item_sku') }}が展開せずに、参照のまま保持できます。
dbt-osmosis yaml document --use-unrendered-descriptions作成したドキュメントは、ローカルでWebサーバーを立ち上げてブラウザからインタラクティブに閲覧できます。これにより、モデル間の依存関係（リネージ）を視覚的に確認したり、定義した説明やテストを一覧したりすることが可能です。
Step 1: ドキュメントを生成する (dbt docs generate)
まず、プロジェクトの情報を集約したドキュメントサイトの元となるファイルを生成します。
dbt docs generateこのコマンドは、プロジェクト内のすべてのリソース（モデル、カラム、テスト、ドキュメントなど）を解析し、静的サイトの元となる2つの重要なJSONファイルをtarget/ディレクトリ内に生成します。
manifest.json: プロジェクトの構造、リソース間の依存関係（DAG）、メタデータを含みます。catalog.json: データウェアハウスから直接取得した情報（テーブルやビューの列名、データ型など）を含みます。
Step 2: ドキュメントサイトを起動する (dbt docs serve)
次に、生成されたファイルを元にローカルWebサーバーを起動します。
dbt docs serveこのコマンドを実行すると、ターミナルに表示されるURL（デフォルトでは http://localhost:8080）にアクセスすることで、ドキュメントサイトをブラウザで閲覧できます。このサイトでは、モデルの定義、カラムの説明、そしてモデル間の依存関係を示すDAGが視覚的に確認でき、データプロジェクト全体の理解を深めるのに非常に役立ちます。
これでドキュメントの作成から閲覧までの一連の流れを体験できました。最後に、今回の学びをまとめ、次のステップに進みましょう。
まとめと次のステップ
本記事では、dbtにおけるドキュメンテーションの価値と、dbt-osmosisやdoc blocksといったツールを使った具体的な実践方法について学びました。ドキュメントは、一度作って終わりではなく、プロジェクトの進化とともに育てていくものです。
- dbtにおけるドキュメンテーションは、チームのコラボレーションとデータ品質を向上させるための重要な活動であること。
dbt-osmosisを使えば、.ymlファイルの雛形を効率的に自動生成し、構造の標準化を図れること。doc blocksを活用することで、Markdownファイルで管理された、よりリッチで保守性の高いドキュメントを作成できること。dbt docs generateとdbt docs serveコマンドで、インタラクティブなドキュメントサイトをローカルで簡単に閲覧できること。
さて、ドキュメントが整備され、モデルの定義が明確になったところで、次に見据えるべきは「データの品質保証」です。実は、今回作成したドキュメンテーション用のYAMLファイルは、モデルのメタデータを一元管理する中心的な役割を担っており、descriptionの隣にtestsキーを追記するだけで、そのままデータ品質テストの定義を追加できるのです。
次回の記事では、このYAMLファイルにtestsキーを追加し、データの整合性や期待される値の範囲などをチェックする方法について解説します。ドキュメントとテストを同じ場所で管理することで、dbtプロジェクトの信頼性をさらに一段階引き上げることができます。
