dbt プロジェクト構造ガイド: models / seeds / macros の実務レイアウト

dbt はフォルダ構成と命名規約がそのまま開発体験や運用コストに跳ね返ります。特に models・seeds・macros のレイアウトは、DAG の見通し、レビュー容易性、CI 選択性に直接影響します。

この記事では、安定機能を前提に公式ドキュメントの挙動に沿って、最小驚きで運用できる構造を提示します。最後に資格試験向けのポイントも織り込みます。

なぜ構造が重要か

dbt は「ファイル配置 = リソース定義」という流儀です。models は SQL からデータベースオブジェクトを作り、seeds は CSV をテーブル化し、macros は Jinja でロジックを再利用します。配置が曖昧だと、DAG の境界が崩れ、レビューと影響範囲の切り分けが困難になります。

資格試験でも、staging → intermediate → marts の分離、seeds の用途、macros の役割とスコープが頻出です。まずは役割と粒度を固定し、dbt_project.yml で一貫したスキーマ付与とタグ運用を行いましょう。

• DAG の層分けはテストと所有権を明確化する
• ディレクトリは命名規約とペアで運用する
• dbt_project.yml の階層設定でスキーマ・マテリアライズ・タグを一括適用

推奨レイアウト: models / seeds / macros の実務構成

最小驚き原則に従い、models を層とドメインで二段分け、seeds は用途別、macros は汎用ユーティリティとアダプタ分岐を分けます。各層ごとにスキーマとマテリアライズを dbt_project.yml で明示し、CI 選択子やタグと連動させます。

下のツリーは小規模から中規模まで伸びる汎用構成です。stg/int/marts の3層、seeds は mappings などの機能別、macros は util と tests を分離しています。

• models は層(staging, intermediate, marts)→ドメインの順にディレクトリを切る
• seeds は変更頻度と参照対象でサブフォルダを分ける（mappings 等）
• macros は util、tests、materializations など責務単位に分解

標準的な dbt プロジェクト構造と DAG の層分け

project/
  dbt_project.yml
  packages.yml
  models/
    staging/
      src__app/
        stg_app__users.sql
        stg_app__orders.sql
    intermediate/
      int__orders_enriched.sql
    marts/
      sales/
        dim_customer.sql
        fct_order.sql
  seeds/
    mappings/
      country_codes.csv
  macros/
    util/
      surrogate_key.sql
      cast_to_boolean.sql
    tests/
      relationships_if.sql
  snapshots/
    app/
      orders_snapshot.sql
  tests/
    generic/
      not_null_if.sql

DAG(概念):
[raw.sources] --> [staging: stg_*] --> [intermediate: int_*] --> [marts: dim_*/fct_*]

dbt_project.yml とモデル/マクロ例

# dbt_project.yml (抜粋)
name: my_project
version: 1.0.0
profile: my_profile
model-paths: ["models"]
seed-paths: ["seeds"]
macro-paths: ["macros"]
snapshot-paths: ["snapshots"]
test-paths: ["tests"]

models:
  +materialized: view
  my_project:
    staging:
      +schema: stg
      +tags: ["staging"]
    intermediate:
      +schema: int
      +tags: ["transform"]
    marts:
      +schema: mart
      +materialized: table
      sales:
        +schema: mart_sales

seeds:
  my_project:
    +schema: seed
    +quote_columns: false
    mappings:
      country_codes:
        +column_types:
          country_code: varchar(2)
          country_name: varchar(64)

# macros/util/surrogate_key.sql
{% macro surrogate_key(cols) %}
md5({{ cols | map('string') | join(" || '-' || ") }})
{% endmacro %}

# models/marts/sales/dim_customer.sql
{{ config(materialized='table') }}
with src as (
  select * from {{ ref('int__orders_enriched') }}
), dedup as (
  select distinct customer_id, customer_name from src
)
select
  {{ surrogate_key(["customer_id"]) }} as customer_sk,
  customer_id,
  customer_name
from dedup;

dbt_project.yml の設定要点

プロジェクト設定は階層適用が基本です。上位でデフォルト、下位ディレクトリで差分を上書きすることで、層ごとのスキーマ、マテリアライズ、タグを安定させます。materialized のデフォルトは view、marts のみ table とするのが保守的です。

seeds は schema、quote_columns、column_types を明示。特に列型はターゲット DWH ごとのデフォルト型に依存しないよう、主キーやコード列に長さを付けます。

• 階層適用で +schema, +materialized, +tags をセット
• selectors.yml とタグを合わせ、CI の部分実行を可能にする
• seeds は column_types を明示し、型不一致による差分を回避

命名規約と DAG の分割: stg / int / marts

ファイル名は層を示す接頭辞で統一します。stg_ は生データの型揃え・列名正規化、int_ は結合・ビジネスロジックの集約、dim_ と fct_ は最終提供物です。層を跨いだ参照を避け、ref は一層下流のみを指すのが安全です。

スキーマは層単位に分けると、テーブル一覧や権限設計が明確になります。DAG の可視化では、層間のエッジが右肩上がりになるように循環を防ぎます。

• stg_: 型揃え・命名規約・PK 生成
• int_: 複数ソース統合・集約・ウィンドウ計算
• dim_/fct_: 分析テーブル。上流層への逆参照は禁止

seeds の使いどころと落とし穴

seeds は小さな参照テーブル向けです。コード体系、ラベル、しきい値など、変更頻度は低いが JOIN されるデータを CSV 管理します。dbt seed でデータベースにテーブルとしてロードされ、モデルと同様にテストを適用できます。

落とし穴はサイズ・型・変更管理です。大容量 CSV は適しません。column_types で明示型を付け、リポジトリのレビューで差分を確認。運用では権限とロケール(区切り・改行コード)にも注意します。

• 小規模・安定的な参照データに限定
• column_types と主キーのテストをセットで管理
• 環境ごとの差異(文字コード・区切り)を最小化

macros の設計指針と再利用

macros はコンパイル時に SQL を生成する仕組みです。ビジネスロジックを隠しすぎず、SQL 可読性が落ちない粒度で関数化します。サロゲートキー生成や型変換、条件付きテストなどが好例です。

アダプタ差異は dispatch で吸収できますが、安定運用の観点からは汎用化しすぎず、ターゲット DWH 毎の軽量分岐に留めるとデバッグが容易です。外部パッケージ(macros)の導入時はバージョンを固定します。

• 粒度は「3行以上繰り返すなら関数化」程度から開始
• test マクロや materialization は責務を分離
• 外部パッケージのバージョン固定と変更点の検証

試験対策と実務チェックリスト

Analytics Engineer 試験では、models/seeds/macros の使い分け、dbt_project.yml の階層設定、ref/source、テストの適用範囲が狙われます。特に seeds の用途、モデル層の分離、マクロの責務は押さえます。

実務では CI セレクタ(タグ/パス)で部分ビルド、スキーマ分離で権限とカタログを整理、レビューでは層逸脱や過剰マクロ化をチェックします。

• ref は1層下流参照を基本にして循環防止
• seeds は CSV の型・主キー・テストをセットで
• macros は副作用なし・可観測性を担保

問題で確認

よくある質問