dbt_project.yml の読み方：主要設定と命名を最短で掴む

dbt_project.yml はプロジェクト全体の“設計図”です。モデルの既定マテリアライゼーション、スキーマ命名、パス構成、マクロのディスパッチ戦略など、実行時の挙動を大きく左右します。

本記事では、Analytics Engineer 試験対策にも直結する安定的な概念に絞って解説します。バージョン固有の仕様に依存せず、公式ドキュメントの一般的な前提に沿って説明します。

全体像と最小構成：まず“何を決めるファイル”かを掴む

dbt_project.yml はプロジェクトのメタ情報と既定設定を宣言します。最低限、プロジェクト名、バージョン、使用するプロファイル名、設定ファイルのフォーマットバージョン（一般的には 2）を定義します。

パス系（models, seeds, snapshots, tests, macros など）は既定値があるため省略可能ですが、チームでの可読性や CI の安定性を考えると明示しておくのが無難です。

• name はユニークで、ノードの unique_id（resource_type.package.name）にも影響
• profile は接続情報（profiles.yml 側）と紐づくため環境切替の要
• config-version は 2 を使うのが一般的
• require-dbt-version で dbt の要求バージョン範囲を固定可能

dbt_project.yml からリレーション名が決まるまで

最小〜基本の dbt_project.yml 例

name: my_dbt_proj
version: 1.0.0
config-version: 2
profile: warehouse_default

model-paths: ["models"]
seed-paths: ["seeds"]
snapshot-paths: ["snapshots"]
test-paths: ["tests"]
macro-paths: ["macros"]

require-dbt-version: ">=1.3.0"
quoting:
  database: false
  schema: false
  identifier: false

models:
  my_dbt_proj:
    +materialized: view

命名とパス設計：models/seeds/snapshots/tests をどう切るか

命名規約はクエリ可読性と運用コストに直結します。特にモデル名（ファイル名）、alias、schema の整合を意識し、ディレクトリごとに既定設定（materialized, schema など）を与えると管理しやすくなります。

seeds や snapshots も dbt_project.yml のブロックで既定設定をまとめておくと、方針のズレを防げます。

• models 下は階層で絞り込み設定可能（例: models/staging, models/marts）
• seeds は delimiter・quote_columns・column_types をプロジェクト既定化すると事故が減る
• snapshots は target_schema / target_database をプロジェクト側で束ねやすい

推奨ディレクトリ構成（例）

project_root/
  models/
    staging/
    intermediate/
    marts/
  seeds/
  snapshots/
  tests/
  macros/
  target/   (生成物)
  dbt_packages/ (依存パッケージ)

パスと命名規約の例（プロジェクト既定）

models:
  my_dbt_proj:
    +materialized: view
    staging:
      +schema: stg
      +tags: [staging]
    marts:
      +materialized: table
      +schema: marts
      +tags: [prod]

seeds:
  my_dbt_proj:
    +schema: seed
    quote_columns: true
    delimiter: ","

snapshots:
  my_dbt_proj:
    target_schema: snap

設定の優先度とモデル命名の決定ルール

dbt の設定は“どこに書いたか”で優先度が異なります。試験で狙われやすいのは、この優先度と alias/schema の解決順序です。

基本原則として、より近い（ローカルな）定義が強く、CLI での明示指定が最優先になります。

• 優先度（高→低）：CLI フラグ > リソースファイル内 config() > dbt_project.yml > 依存パッケージの設定 > 既定値
• alias はデータベース上の識別子（identifier）を置き換えるが、ref('name') の参照名はモデル名（ノード名）のまま
• schema は generate_schema_name マクロの結果で決まる。+schema を与えた場合、既定では target.schema に結合される

設定優先度の“段々畑”イメージ

優先度の違いが分かるサンプル

# models/marts/orders.sql
{{ config(materialized='table', alias='fct_orders') }}
select * from {{ ref('int_orders') }}

# dbt_project.yml（抜粋）
models:
  my_dbt_proj:
    marts:
      +materialized: view   # ← リソース内 config がこれを上書き
      +schema: marts

スキーマ命名：+schema と generate_schema_name の正しい使い方

スキーマは target（profiles.yml の target 設定）とプロジェクト側の +schema、それを束ねるマクロ generate_schema_name で決まります。既定の実装では、+schema を与えると target.schema に接尾して結合する挙動が一般的です。

チームで“接尾結合”か“完全置換”かを明示し、必要であればマクロを上書きすると事故を防げます。

• 既定：+schema があると target.schema_カスタム のように連結されることが多い
• 完全置換にしたい場合は generate_schema_name をプロジェクトで上書き
• 環境差（dev/prod）のサフィックスは target 側で吸収するのがシンプル

環境とカスタムスキーマの組み合わせ例

target.schema = analytics
+schema = stg

既定: analytics_stg
完全置換: stg
環境サフィックス例: analytics_dev_stg

generate_schema_name の上書き例（完全置換）

{% macro generate_schema_name(custom_schema_name, node) %}
  {# 完全置換：custom_schema_name があればそれを使い、なければ target.schema #}
  {% if custom_schema_name is not none %}
    {{ custom_schema_name }}
  {% else %}
    {{ target.schema }}
  {% endif %}
{% endmacro %}

# dbt_project.yml（例）
models:
  my_dbt_proj:
    staging:
      +schema: stg

拡張の基礎：vars・dispatch・互換性設定を押さえる

vars はマクロ・モデルから参照するパラメータ置き場です。dispatch はマクロ解決の探索順を制御し、アダプタや自作パッケージとの共存を助けます。

互換性と安全性のために require-dbt-version で実行バージョンを固定し、quoting・on-run-*・clean-targets なども明示しましょう。

• dispatch で dbt 標準マクロを自作に差し替える順序を定義
• vars は env_var と組み合わせて環境差を吸収
• quoting はアダプタごとの識別子ポリシー差異を平準化

マクロ解決のディスパッチ順序

拡張系設定の例

dispatch:
  - macro_namespace: dbt
    search_order: [my_pkg, dbt]

vars:
  country: "JP"
  run_ts: "{{ var('override_ts', env_var('RUN_TS', '1970-01-01')) }}"

require-dbt-version: ">=1.3.0,<2.0.0"

quoting:
  database: false
  schema: false
  identifier: false

on-run-start:
  - "{{ log('Run started at ' ~ run_started_at, info=True) }}"
clean-targets: ["target", "dbt_packages"]
packages-install-path: "dbt_packages"

試験対策と落とし穴チェックリスト

Analytics Engineer 試験では、設定優先度・スキーマ/識別子命名・seeds/snapshots の既定と上書きの関係が頻出です。以下のチェックで理解の穴を塞ぎましょう。

特に alias と ref の関係、+schema と generate_schema_name の既定挙動、seeds の quote_columns 既定は混同しやすいポイントです。

• ref はノード名で解決。alias を変えても ref('ノード名') は変えない
• models の既定 materialized は view。上書きはリソース内または dbt_project.yml で可能
• seeds は quote_columns の既定が true である実装が一般的。必要に応じて明示設定
• snapshots の target_schema はプロジェクトでも指定可能。個別 snapshot の設定があればそちらが強い
• quoting は database/schema/identifier 別に制御できる。アダプタ差異に留意

実行フローのざっくり像

seeds と tests の実務設定例

seeds:
  my_dbt_proj:
    +schema: seed
    quote_columns: true
    delimiter: ","
    column_types:
      id: integer
      amount: numeric

tests:
  +severity: warn
  +store_failures: true
  +schema: test_audit

問題で確認

よくある質問