dbt CLI主要コマンドを整理: run / test / build / compile の違いと使い分け

dbt 1.x 系の安定挙動に基づき、run・test・build・compile の違いを、試験の出題傾向と実務の観点で最短で理解できるよう整理します。

特に、build が umbrella コマンドとして seed・model・snapshot と test を DAG 順にまとめて実行する点、compile は SQL を生成するだけで DB を変更しない点が鍵です。

全体像: 4コマンドの責務と実行順序

dbt run はモデルをビルドし、dbt test はテストを実行します。dbt build は seed・model・snapshot をビルドし、対応するテストをノードごとに後続で走らせる包括コマンドです。dbt compile は Jinja/refs を解決した SQL を生成するだけで、データベースには触れません。

試験・実務ともに重要なのは「何が実行され」「どの順序で」「副作用が何か」を明確にすることです。以下の比較表と図で、役割と実行パターンを一度に掴みます。

• run = モデル等のビルドのみ（テストは走らない）
• test = テストノードのみ（基本は0行＝成功。行が返ると失敗）
• build = seed → model/snapshot → test をDAG順で包括実行
• compile = クエリ実行なし。target/compiled にSQLを出力

主要コマンドとDAG実行の関係

sources --> seeds --> models --> tests
                 |          ^
                 v          |
              snapshots ----+

Legend:
- run:    seeds/models/snapshots のみ実行（testsは含まない）
- test:   tests のみ実行
- build:  seeds -> (models/snapshots) -> tests の順で包括実行
- compile: 実行なし、SQL生成のみ

最短の使い分け例

## 開発でモデルだけ動かす
$ dbt run --select my_model+

## テストだけ流す
$ dbt test --select tag:quality

## CIで一括（変更影響範囲のみ）
$ dbt build --select state:modified+ --defer --state target

dbt run: ビルド専任。選択子で正しく範囲を絞る

dbt run はモデル（および選択に応じた seed/snapshot）をDAG順に実行します。テストは走らないため、品質検証が必要なら別途 test または build を組み合わせます。

増分モデルは materialized='incremental' のロジックに従い差分更新します。全件やり直したい場合は --full-refresh を使います。

• テストは含まれない点に注意（試験の頻出混乱ポイント）
• 選択子 --select と --exclude を組み合わせる
• 増分更新と --full-refresh の切替
• ephemeral は物理化されず、下流SQLにインライン展開

run の実行イメージ

seed_a   model_b(ephemeral)
   \        |
    --> model_c (incremental)

run: seed_a -> model_c（model_bはインライン展開、testsは実行しない）

選択子の具体例

# 依存先も含めビルド
$ dbt run --select my_model+

# 上流（親）も含める
$ dbt run --select +my_model

# フォルダ単位
$ dbt run --select models/marts/

# タグで除外
$ dbt run --select tag:daily --exclude tag:expensive

dbt test: 成功条件は“行が返らない”。store_failuresとseverityの扱い

dbt test は generic（not_null、unique 等）と singular（任意のSQLで記述）を実行します。基本ルールは「テストクエリが0行なら成功、1行以上返せば失敗」です。

失敗行を後で調査したい場合は store_failures を有効化します。警告として扱いたいチェックには severity: warn を付与できます。

• generic = YAMLで宣言、singular = tests/配下にSQLで記述
• 成功=0行、失敗=1+行（singular も同様）
• store_failures: true で失敗行テーブルを残す
• severity: warn で失敗でもパイプライン継続可能

test の依存関係

model_x  -->  test_not_null_model_x.col1
model_x  -->  test_unique_model_x.col2

テストは対象ノードに依存し、dbt test はテストノードのみ実行する

schema.yml の例（generic）

version: 2
models:
  - name: fct_orders
    columns:
      - name: order_id
        tests:
          - not_null
          - unique
      - name: customer_id
        tests:
          - relationships:
              to: ref('dim_customers')
              field: customer_id
              severity: warn
    config:
      materialized: incremental

# singular（tests/late_orders.sql）
-- 0行で成功
select *
from {{ ref('fct_orders') }}
where order_date > current_date + interval '1 day'

dbt build: CIの既定値。ノード直後にテストして壊れた変更を即検知

dbt build は seed・model・snapshot をDAG順にビルドし、各ノードに紐づくテストを続けて実行します。これにより、壊れた変更を依存先に波及させる前に検出できます。

変更影響のみを素早く検証するには state:modified 選択子と --defer を組み合わせ、未変更の依存を本番オブジェクトに委譲します。source freshness は別コマンド（dbt source freshness）である点に注意します。

• seed → model/snapshot → test をノード単位で実行
• state:modified+ で変更とその下流のみを対象化
• --defer で未変更依存を上位環境に解決（高速化）
• source freshness は build に含まれない（別実行）

build の流れ（ノード単位）

[seed_s] -> (test_seed_s)
   |             \
   v              X（seedにはgeneric testがなければスキップ）
[model_m] -> test_model_m_*
   |
   v
[snapshot_n] -> test_snapshot_n_*

CI向けスリムビルド例

# 直近のmanifest.jsonを用いた state 選択（例）
$ dbt build \
    --select state:modified+ \
    --defer \
    --state target \
    --profiles-dir . \
    --target ci

dbt compile: 実行なしでSQLを確定。レビューと安全確認に最適

dbt compile は Jinja、ref、source、変数、マクロを解決し、各ノードの SQL を target/compiled 配下に生成します。データベースに対する実行や変更は行いません。

実行前に生成SQLを確認できるため、レビューや静的解析に向いています。解析のみが目的なら parse もありますが、compile は最終SQLを出力する点が実務で便利です。

• 実行しない＝副作用なし（本番環境を汚さない）
• target/compiled/<project>/<resource_type>/... に出力
• マクロ展開後の最終SQLを事前に確認可能
• パーサエラーや参照解決エラーの早期検出

compile の生成物

project/
  models/
  macros/
  ...
      |
      v
 target/compiled/project/
   models/...
   snapshots/...
   tests/...

（DBへの実行は発生しない）

生成SQLのパスと確認

# コンパイルのみ
$ dbt compile

# 例: compiled SQL を開く（モデル fct_orders）
$ sed -n '1,80p' target/compiled/<project>/models/marts/fct_orders.sql

選択子と依存の書き方: 試験・実務の頻出整理

選択子は “どのノードを対象にするか” を厳密に制御します。+ は親/子の依存を含める演算子で、左側の + は上流（親）、右側の + は下流（子）を表します。

build は選択したノードに紐づくテストを自動で含めますが、run は含めない点が出題の常連です。resource type や tag、path を組み合わせて現実的な粒度に調整します。

• +my_model は親を含める、my_model+ は子を含める、+my_model+ は両側
• resource type: model:, test:, seed:, snapshot:, source:
• tag:xxx, path:models/marts/, state:modified などの併用
• build は tests を内包、run/test は明示的に分ける

依存選択の直感図

src --> stg_orders --> int_orders --> marts_orders
          ^              ^              ^
         +stg_orders   +int_orders    +marts_orders

my_model+ は右方向（子）に広がる

組み合わせ例

# 親と自ノードのみ
$ dbt build --select +stg_orders --defer --state target

# 変更分の下流のみ
$ dbt build --select state:modified+ --defer --state target

# PIIを除外
$ dbt run --select tag:daily --exclude tag:pii

問題で確認

よくある質問