dbt run と dbt build の違いと使い分け（Analytics Engineer 試験と実務に効く要点）

コマンドは知っていても、レビューや本番前の検証で迷いがちなのが run と build の使い分けです。実務では最短の反復、CI では信頼できる一貫性、試験では定義の正確さが問われます。

本稿は dbt の公式ドキュメントの挙動に沿って、違い・選び方・周辺機能（選択子、インクリメンタル、スナップショット、テスト）の連動をまとめます。

基本の違い：何が動くか、いつ止まるか

dbt run はモデルのみを対象に、選択子で指定したノードをコンパイルして実行します。テストは動きません。依存関係は実行順序に反映されますが、未選択の親モデルは自動では再実行されません（存在しない場合は参照エラー）。

dbt build は選択したスコープに含まれるシード、スナップショット、モデルを依存関係順に実行し、その後関連するテスト（スキーマ・データ）を実行します。つまり、1コマンドで「作る＋確かめる」を完了させる統合フローです。

• dbt run: モデルだけ。検証は別途 dbt test。
• dbt build: シード/スナップショット/モデルの構築後、該当テストを自動実行。
• どちらも選択子（-s/--select, -m エイリアス）でスコープを絞れる。

run と build の実行フロー（概念）

最小例：個別モデルと統合ビルド

# 個別モデルだけ（親は+で明示選択）
dbt run -s +stg_orders

# 選択範囲の構築とテストを一括
# 変更分とその下流、関連テストを対象
dbt build -s state:modified+

実行順序とテストの扱い（失敗時の挙動を含む）

dbt はDAGに基づき並列・順序制御します。build は対象ノードのビルド完了後に、そのノードに紐づくテストを実行します。未選択ノードのテストは走りません。

テスト失敗時は、そのテストが失敗として記録され、既定では他の独立ノードの実行は継続します（--fail-fast を付けると早期停止）。run はテストを実行しないため、失敗の検出は test 実行に依存します。

• テストは node 完了後に実施。対象はスコープに含まれる資産に紐づいたもののみ。
• --fail-fast で最初の失敗で停止。付けなければ可能な限り継続。
• データテスト（singular）とスキーマテスト（generic）の両方が build で実行対象。

ノードとテストの実行シーケンス

スキーマテストとデータテストの例

# models/schema.yml（generic test 例）
models:
  - name: dim_customers
    columns:
      - name: customer_id
        tests:
          - not_null
          - unique

# tests/assert_positive_revenue.sql（singular test 例）
-- 失敗すると build は失敗として集計
select 1 where exists (
  select 1 from {{ ref('fct_revenue') }} where total_revenue < 0
);

# 実行
# スキーマ・データ両テストを fct_revenue, dim_customers に対して実行
dbt build -s dim_customers fct_revenue

選択子の使い分け：最小スコープで速く・安全に

run と build のどちらでも、何を対象にするかは選択子で決まります。+で親子を含める、tag: で属性選択、state: で変更影響範囲をとるのが基本です。

build の場合は選んだスコープに対しテストも自動で付随する点が差分です。未選択のノードに紐づくテストは実行されません。

• +my_model は上流も含める、my_model+ は下流も含める、+my_model+ は両側を含める
• state:modified+ は変更ノードとその下流（影響範囲）を対象にでき、CI で有用
• resource_type:, tag:, path:, config.materialized: などで粒度を調整

選択子によるスコープの違い

A -> B -> C

-s B      : [B]
-s +B     : [A, B]
-s B+     : [B, C]
-s +B+    : [A, B, C]

run と build で同じ選択子を使う

# 開発ループ（モデルだけ速く）
dbt run -s +stg_orders

# CI（影響範囲を構築＆検証）
dbt build -s state:modified+ --defer --state target/manifest

インクリメンタル・スナップショットとの相性

インクリメンタルモデルは選択されたときに既定モードで差分反映され、--full-refresh で全再計算します。run でも build でも動作は同じです。

スナップショットは独立したノードで、ref されるとDAGに組み込まれます。build はスナップショットも対象に含められるため、スナップショットに依存するモデルを含む一括検証に向きます。

• incremental: 変更量が多いときは --full-refresh を計画的に（ロックやコストに注意）
• snapshot: 選択子で含めると build が実行。未選択なら既存テーブルを参照
• テストは生成物に対して実行されるため、更新直後の健全性確認が容易

スナップショットとモデルの依存

設定例：インクリメンタルとスナップショット

# models/fct_orders.sql
{{ config(materialized='incremental', unique_key='order_id') }}
select * from {{ ref('stg_orders') }}
{% if is_incremental() %}
  where updated_at > (select max(updated_at) from {{ this }})
{% endif %}

# snapshots/customers.sql
{% snapshot customers_scd %}
{{ config(strategy='timestamp', unique_key='customer_id', updated_at='updated_at') }}
select * from {{ source('app', 'customers') }}
{% endsnapshot %}

# 実行
# 影響範囲を含め一括構築・検証
dbt build -s +dim_customers
# 全再計算（注意して計画的に）
dbt run -s fct_orders --full-refresh

CI/CD と本番運用での判断基準

PR 検証や本番前の整合性チェックは dbt build が第一選択です。構築とテストを一発でカバーし、失敗があれば早期に検出できます。

ローカル開発やデバッグは dbt run で対象を最小化して素早く反復し、論点が固まったら build でテストまで通すのが効率的です。

• 開発: run で速く確認 → 節目で build
• CI: build -s state:modified+ --defer --state を基本形に
• 本番バッチ: build で包括的に。テストの一部を除外したい場合は --exclude

CI パイプラインの典型

GitHub Actions の最小ジョブ例

jobs:
  dbt-ci:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install dbt-core dbt-bigquery  # 適宜アダプタ
      - run: dbt deps
      - run: dbt build -s state:modified+ --defer --state target

落とし穴と試験対策の着眼点

試験では定義の厳密さが問われます。特に「dbt build は何を対象にするか」「テストがいつ動くか」「未選択ノードの扱い」を正確に押さえましょう。

実務では、選択子の過不足や full-refresh の濫用がコスト・ロック・誤検知の原因になります。ルール化と自動化で回避します。

• 未選択の親は自動で再実行されない。必要なら + を付けるか明示選択
• build は tests を実行するが、未選択ノードに紐づくテストは走らない
• full-refresh は計画的に。並列度とロックの相互作用に注意

意思決定の分岐

試験向けミニチェック（自問）

- dbt run: 何が動く？ models のみ
- dbt build: 何が動く？ seeds/snapshots/models + tests
- テストはいつ？ 対象ノードの構築後
- 親子を含める？ +で選択範囲を拡張

問題で確認

よくある質問