Open7

【dbt】ベストプラクティス

YuichiYuichi

https://docs.getdbt.com/best-practices/how-we-structure/5-the-rest-of-the-project#yaml-in-depth
⚠️ Generated by ChatGPT.

YAMLファイルの構成方法

YAMLファイルの配置は柔軟ですが、一貫性と管理のしやすさが重要です。

✅ 推奨: ディレクトリごとにYAMLを管理

方法:

  • 各ディレクトリに _[directory]_models.yml を作成し、そのフォルダ内のモデルの設定を記述する
  • stagingフォルダ では _[directory]_sources.yml も作成し、ソース情報を記述する
  • ドキュメントブロック (docs) を使う場合は、_[directory]_docs.md を作成する

メリット:
✔ YAMLファイルがフォルダの先頭に来るので、見つけやすい
✔ ファイル名にディレクトリ名を含めることで、ファジーファインドがしやすい
✔ モデルの設定・テストが一箇所にまとまり、管理しやすい

❌ 非推奨: プロジェクト全体で1つのYAMLに集約

方法:

  • schema.yml に全てのモデル・ソースを記述する

デメリット:
✖ ファイルが大きくなりすぎて、個別の設定を見つけにくい
✖ スクロールや検索が頻繁に必要になり、開発速度が落ちる

⚠️ 個別モデルごとにYAMLファイルを作成

方法:

  • モデルごとに model_name.yml を作成し、個別に管理

メリット:
✔ モデルごとの設定をすぐに見つけられる
✔ 設定が抜けているモデルをファイルツリーで視覚的に把握しやすい

デメリット:
✖ ファイル数が増えすぎて管理が煩雑に
✖ 開発時にタブを開いたり閉じたりする手間が増える

✅ dbt_project.yml でのカスケード設定

  • dbt_project.yml でディレクトリごとにデフォルトの設定を定義する
  • 例えば:
    • marts 配下はデフォルトで table にする
    • staging 配下はスキーマを別に設定する
    • 特定のモデルのみ incremental にする

メリット:
✔ デフォルト設定を適用しつつ、例外的なモデルのみ個別設定ができる
✔ フォルダ構造を活かしたスコープ設定が可能

YuichiYuichi

⚠️ Generated by ChatGPT.

✅ seeds/：ルックアップテーブルの管理

  • 主な用途: 参照データ（例: 郵便番号→都道府県マッピング、UTMパラメータ→マーケティングキャンペーン）
  • 例: seeds/employees.csv → 従業員と customer_id のマッピング
  • 理由: データソースに存在しないが、モデルの変換で必要なデータを管理するため

❌ seeds/ をソースデータの取り込みに使わない

  • 理由: ソースデータのロードは ETLツール を使い、データウェアハウスに直接取り込むべき
  • 代替: ELツール（Fivetran, Airbyte など）を使用し、raw スキーマへロード

✅ analyses/：監査クエリ・一時的な分析用SQLの管理

  • 主な用途:
    • Jinjaを活用した一時的なクエリのバージョン管理
    • dbt audit helper パッケージを活用したデータ移行時の検証
  • ポイント:
    • analyses/ 内のSQLは モデルとしてデプロイされない
    • 限定的なデータ検証やアドホックな分析で活用

✅ tests/：複数のテーブルをまたぐテストの管理

  • 主な用途:
    • 既存の generic test（カラム単位のテスト） でカバーできないケース
    • 特定のモデル同士の関係性をテスト（例: 異なるモデル間の集計値の一致）
  • ポイント:
    • 単体テスト（generic test） と 統合テスト（singular test） の違いを意識
    • dbt-utils や dbt-expectations に既存のテストがないか確認

例:

  • tests/assert_positive_value_for_total_amount.sql
    • total_amount の値が負にならないかをチェック

✅ snapshots/：Type 2 Slowly Changing Dimension (SCD) の管理

  • 主な用途:
    • 過去のデータを保持するスナップショット（データが上書きされる Type 1 を Type 2 に変換）
  • ポイント:
    • dbtのスナップショット機能を活用し、変更履歴を管理
    • 詳細はdbtの公式ドキュメントを参照

✅ macros/：汎用的な変換処理の管理

  • 主な用途:
    • 繰り返し使用するSQLロジックを**DRY（Don't Repeat Yourself）**にする
  • ポイント:
    • マクロごとに _macros.yml を作成し、目的や引数を明記
    • 例: cents_to_dollars.sql → セントをドルに変換するマクロ

✅ まとめ（フォルダ別の適切な用途）

フォルダ 主な用途 避けるべきこと
seeds/ ルックアップテーブル（変換用） ソースデータのロード
analyses/ 一時的な分析クエリ・監査クエリ モデル化するデータの保存
tests/ 特定のモデル同士の関係性のテスト 不要なカスタムテストの増加
snapshots/ Type 2 SCDの管理 スナップショット不要なテーブルの保存
macros/ 繰り返し使う変換処理 ドキュメントなしのマクロ作成

ポイント:

  • モデル以外のフォルダにも明確な役割を持たせる
  • 適切なフォルダに適切なデータを置くことで、プロジェクトの管理が容易に
YuichiYuichi

⚠️ Generated by ChatGPT.

dbtプロジェクトの分割戦略

dbtプロジェクトを分割するかどうかは、組織の規模・ガバナンス要件・プロジェクトの複雑さ によって決まります。近年、dbt Mesh の採用が進んでおり、複数のdbtプロジェクトを連携させる形で分割するのが推奨されます。

✅ プロジェクトを分割するべきケース

1️⃣ ビジネス部門・チームごとの分割

  • 各 ビジネスドメインごとにプロジェクトを分割 し、それぞれがデータプロダクトを管理
  • dbt Mesh を活用することで、独立性を保ちつつ連携が可能
  • 例:
    • marketing_dbt → 広告費やキャンペーンのデータモデル
    • finance_dbt → 売上や経費のデータモデル

2️⃣ データガバナンス・セキュリティ要件

  • PII（個人情報）や機密データ を取り扱う場合、ガバナンス上の要件により分割が必要
  • 例:
    • staging_dbt (個人情報を含む生データ) はアクセス制限
    • analytics_dbt (加工済みのデータ) は広く利用可能

具体例:
医療系企業では、個人情報を含むraw_dataは機密プロジェクト で管理し、集計済みの指標のみを別のプロジェクトで提供 する

3️⃣ プロジェクトサイズが大きくなりすぎた場合

  • モデル数が 数千を超える場合、開発やCI/CDの負荷が増大
  • サブプロジェクト化して、モジュールごとに管理（dbt deps で依存関係を管理）

具体例:

dbt_projects/
├── core_dbt  （共通モデル: ユーザー・商品・売上）
├── marketing_dbt  （マーケティング分析）
└── finance_dbt  （財務データ分析）

❌ プロジェクト分割を推奨しないケース

1️⃣ ML用とBI用の分離

  • 一般的なBIとML（機械学習）を別のプロジェクトにするのは非推奨
  • 同じデータマート・メトリクスを利用するべき ため、一貫性が失われる
  • 代替: BI/MLの両方が利用できる統一データモデルを構築

例:

  • marts/ 内に ml_ready/ サブフォルダを作成し、機械学習用のデータを準備
YuichiYuichi

⚠️ Generated by ChatGPT.

最終的な考慮事項

最も重要なのは 一貫性 です。
どんなルールやベストプラクティスも、プロジェクト内での統一性を保つこと が最優先となります。

プロジェクトが成長し、dbtの経験が深まるにつれ、本ガイドの内容を変更したくなることがあるでしょう。基本的には本ガイドのアプローチを推奨しますが、すべての組織が同じである必要はありません。

✅ カスタマイズする場合の注意点

  • なぜ変更するのかを明確にする
    • 変更の背景や目的をチームで共有
    • 例: 「現在のルールではXが不便なので、Yのように変更する」
  • READMEやWikiにドキュメント化する
    • チーム全体で一貫したルールを適用できるようにする
    • 例: CONTRIBUTING.md にカスタムルールを記載

📌 このガイドの活用方法

  • 必要に応じて フォークし、プロジェクトのREADMEやWikiに追加
  • 独自のカスタマイズを加え、チームの標準として整備
  • 変更の背景や理由を明確に記載することで、後から見直しやすくする

🚀 このガイドは進化し続ける

dbtの進化に伴い、本ガイドの内容も変化していきます。
dbtのベストプラクティスを学び、チームで議論しながら、最適な形にカスタマイズしてください！

YuichiYuichi

https://techblog.cartaholdings.co.jp/entry/snowflake-dbt-data-platform-vision

知らなかった項目

利用しているdbtパッケージ

  • yu-iskw/dbt_unittest
    • マクロのユニットテストを容易にするパッケージ。信頼性の高いマクロ開発を支援。

Visual Studio Code (VS Code)のプラグイン

  • 地味便利
  • YAML - Visual Studio Marketplace
    • dbtスキーマ読み込ませて使ってます。
  • Code Spell Checker - Visual Studio Marketplace
    • カラム、モデル名のtypoを防ぐ。
  • Copy file name - Visual Studio Marketplace
    • モデル名のコピペに地味便利です。

yamlフォーマットチェック

github.com/lyz-code/yamlfix

warningチェック

dbt --warn-error ls
Warnings | dbt Developer Hub