dbt build の使い方：run/test/snapshot を一括で安全に回す

dbt build はモデル・シード・スナップショットを構築し、その結果に対するテストを依存順にまとめて実行します。個別に dbt run → dbt test → dbt snapshot を分けるより、パイプラインを壊しにくく CI に載せやすいのが利点です。

本稿は dbt 公式ドキュメントの安定機能を前提に、Analytics Engineer 試験で問われやすい比較観点（run/test/snapshot と build の違い、セレクタ、state/defer）を実務目線で整理します。

dbt build の概要：一発実行とそのメリット

dbt build は選択されたリソース（models、seeds、snapshots）を DAG に沿って構築し、完了後に tests（generic/singular）を実行します。依存関係が満たされていないテストは自動的にスキップされ、失敗した上流ノードにぶら下がるテストも走りません。

ポイントは順序制御と原子性です。単一コマンドで「構築→検証」までを一気通貫に回すため、個別コマンドの順序ミスや取りこぼしを防げます。CI では build を既定のエントリポイントにすると運用が安定します。

• 対象に含まれるもの: models、seeds、snapshots、tests（tests は最後）
• DAG に基づき並列実行。依存未解決のノードは待機、失敗分岐は以降スキップ
• 単体の dbt run/test/snapshot よりも一貫した結果（構築結果に対するテスト）
• CI/CD での既定: dbt build をまず選択し、必要に応じてセレクタで絞る

dbt build の実行フロー（概念図）

最小の実行例

dbt build
# profiles.yml と dbt_project.yml が設定済みであれば、この1行で
# models/seeds/snapshots を構築し、最後に tests を実行します。

実行順序と依存関係のポイント

dbt build は選択済みノードの DAG を解決し、models/seeds/snapshots を先に構築します。tests は常にその後で、親ノード（対象テーブル/ビュー/スナップショット/シード）が成功している場合のみ実行されます。ephemeral モデルは物理化されず、親クエリへインライン展開されます。

インクリメンタルモデルは既定で差分更新、--full-refresh を付けた場合は再作成します。tests は更新後の状態に対して走るため、品質検証は常に最新の構築結果に対して行われます。

• tests はリソース構築の後に実行（失敗や未構築の親がある tests はスキップ）
• ephemeral はビルド対象にならない（親にインライン展開）
• --full-refresh はインクリメンタル models にのみ適用されるのが一般的（snapshots は通常の差分更新）
• シードは依存するモデルより先にロードされる

順序を意識した基本（何も指定しない）

dbt build
# DAG に基づいて seeds/models/snapshots → tests の順で動く

セレクタで run/test/snapshot を的確に絞る

dbt build は --select/--exclude で柔軟に範囲指定できます。タグ、ファイルパス、モデル名、リソースタイプ（model:, snapshot:, seed:, test:）に加えて、state:modified などの状態セレクタも利用可能です。末尾に + を付けると子孫、先頭に + を付けると祖先を含めます。

大規模リポジトリでは、タグやパス、リソースタイプを組み合わせて対象を最小化すると CI 実行時間を短縮できます。

• タイプ指定: model:my_model, snapshot:, seed:, test:
• タグ指定: tag:core, tag:critical
• パス指定: path:models/marts/
• 状態指定: state:modified, state:new
• 近傍指定: +my_model（祖先）、my_model+（子孫）、+my_model+（両方）

代表的なセレクタ例

# 重要タグのモデルとその子孫だけを構築し、最後に tests
dbt build --select tag:critical+

# スナップショットだけを更新し、関連 tests のみ実行
dbt build --select snapshot:

# マート配下と依存元（祖先）を含めて構築
dbt build --select +path:models/marts/

# 変更点とその下流のみ（state ディレクトリの指定は別途）
dbt build --select state:modified+ --state target/

並列実行、失敗時の停止、スキップの挙動

dbt build はスレッド数に応じて独立ノードを並列実行します。あるノードが失敗した場合、そのノードに依存する下流ノードと紐づく tests はスキップされます。--fail-fast を付けると最初の失敗で全体を停止します。

分岐が多い DAG では --threads を適切に設定して全体時間を短縮しつつ、クリティカルな検証では --fail-fast を使って早期に失敗を検知するのが実務的です。

• 並列度は profiles.yml の threads もしくは --threads で制御
• 失敗ノードの下流はスキップ（tests も含む）
• --fail-fast は最初の失敗で停止（CI の早期失敗に有効）
• 再実行時はセレクタで問題領域に絞る（例: model:orders+ や tag:data_quality）

並列と早期失敗

# 8 並列で実行し、最初の失敗で停止
dbt build --threads 8 --fail-fast

CI/PR で効く差分ビルド：state と defer の組み合わせ

差分ビルドの定番は、プロダクションのアーティファクト（manifest.json など）を --state で参照し、変更のあったノードとその下流だけを --select state:modified+ で選ぶパターンです。さらに --defer を併用すると、未選択の上流 ref はプロダクションの構築物に委譲されるため、CI で最小限の構築に抑えられます。

この組み合わせは PR 単位の検証時間を大幅に短縮できます。プロダクション側のアーティファクトは本番ジョブで都度出力し、CI から参照するように整備します。

• state:modified はコードやコンパイル結果の差分を基準に変更ノードを抽出
• 末尾の + で変更ノードの下流も含める（影響範囲の検証）
• --defer は未選択の ref を --state 先の成果物へ委譲（本番依存）
• PR では build を基本に、フルリフレッシュは避けるのが安全

典型的な CI コマンド

# プロダクションのアーティファクトを参照し、変更点とその下流のみを検証
# artifacts/ に本番の manifest.json 等がある前提
dbt build --select state:modified+ --state artifacts/ --defer

落とし穴とベストプラクティス

dbt build は強力ですが、インクリメンタルモデルのフルリフレッシュや大量スナップショットを無闇に混ぜると時間・コストが膨らみます。CI では差分とテスト重視、本番ではスケジュールとワークロード分離が有効です。

品質面では critical なテストに severity:error、補助的なものに severity:warn を使い分け、store_failures で失敗行を収集すると改善サイクルが回しやすくなります。

• CI の既定は dbt build。個別 run/test は必要最小限に
• --full-refresh は計画的に。PR/CI では原則使わない
• tests の粒度と severity を整理。重要なキー制約は unique/not_null を最低限カバー
• 大きなスナップショットは時間帯を分離し、テストは分岐して並列実行
• タグとパスを整備し、セレクタで狙い撃ちできるようにする

スキーマテストの設定例（fail を収集）

version: 2
models:
  - name: orders
    columns:
      - name: id
        tests:
          - unique:
              severity: error
              store_failures: true
          - not_null:
              severity: error

問題で確認

よくある質問