documenting-dbt-models

dbt ドキュメント

WHAT だけでなく WHY を記載します。粒度、ビジネスルール、注意事項を含めてください。

ワークフロー

1. 既存のドキュメントパターンを確認する

重要：新しいドキュメントを追加する前に、プロジェクトのドキュメントスタイルに合わせてください。

# Find all schema.yml files with documentation
find . -name "schema.yml" | head -5

# Read well-documented models to learn patterns
cat models/marts/schema.yml | head -150
cat models/staging/schema.yml | head -150

既存のドキュメントから以下を確認します：

• 説明の長さ（簡潔か詳細か）
• 書式スタイル（プレーンテキストか、見出し付きの Markdown か）
• 含まれる情報（粒度、ビジネスルール、注意事項など）
• カラムの説明の詳しさ（すべてのカラムか、主要なカラムか）
• meta タグやカスタムプロパティの使用状況

2. モデルの SQL を読む

cat models/<path>/<model_name>.sql

変換、ビジネスロジック、結合、フィルターを把握します。

3. このモデルの既存ドキュメントを確認する

# Find existing schema.yml
find . -name "schema.yml" -exec grep -l "<model_name>" {} \;

# Read existing docs
cat models/<path>/schema.yml | grep -A 100 "<model_name>"

4. ドキュメント化が必要な内容を特定する

各モデルについて、以下を記載します：

• モデルの説明：目的、粒度、主要なビジネスルール
• カラムの説明：データ型だけでなく、ビジネス上の意味

各カラムについて、以下を検討します：

• どのようなビジネス概念を表しているか？
• 注意事項や特別な値はあるか？
• このデータのソースは何か？

5. ドキュメントを作成する

ステップ 1 で確認したスタイルに合わせます。形式の例（プロジェクトに合わせて調整してください）：

version: 2

models:
  - name: orders
    description: |
      Order transactions at the order line item grain.
      Each row represents one product in one order.

      **Business Rules:**
      - Revenue recognized on ship_date, not order_date
      - Cancelled orders excluded (status != 'cancelled')
      - Returns processed as negative line items

      **Grain:** One row per order_id + product_id combination

    columns:
      - name: order_id
        description: |
          Unique identifier for the order.
          Source: orders.id from Stripe webhook

      - name: customer_id
        description: |
          Foreign key to customers table.
          NULL for guest checkouts (pre-2023 only)

      - name: revenue
        description: |
          Net revenue for this line item in USD.
          Calculation: unit_price * quantity - discount_amount
          Excludes tax and shipping

      - name: order_status
        description: |
          Current status of the order.
          Values: pending, processing, shipped, delivered, cancelled, returned

6. ドキュメントを生成する

dbt docs generate
dbt docs serve  # Optional: preview locally

ドキュメントのパターン

注：以下はデフォルトのテンプレートです。必ずプロジェクトの既存のスタイルに合わせて調整してください。

モデル説明のテンプレート

description: |
  [One sentence: what this model contains]

  **Grain:** [What does one row represent?]

  **Business Rules:**
  - [Key rule 1]
  - [Key rule 2]

  **Caveats:**
  - [Important limitation or edge case]

カラム説明のパターン

カラムの種類	ドキュメントで説明する内容
主キー	ソースシステム、一意性の保証
外部キー	結合先、NULL の扱い
指標	計算式、単位、除外対象
日付	タイムゾーン、表すイベント
ステータス／カテゴリ	すべての値、ビジネス上の意味
ブール値／フラグ	true／false がビジネス上で意味する内容

計算フィールドのドキュメント化

- name: gross_margin
  description: |
    Gross margin percentage.
    Calculation: (revenue - cogs) / revenue * 100
    NULL when revenue = 0 to avoid division by zero

避けるべきパターン

• プロジェクトの既存パターンを確認せずにドキュメントを追加する
• 既存のドキュメントと異なる書式スタイルを使う
• WHY／背景ではなく WHAT を説明する（例：「注文 ID」）
• 粒度の説明がない
• NULL の扱いを記載しない
• カラムの説明を記載しない
• カラム名をそのまま説明としてコピーする