running-dbt-commands

dbt コマンドの実行

設定

1. 利用可能な場合は MCP ツール（dbt_build、dbt_run、dbt_show など）を使用します。パス、タイムアウト、書式設定が自動的に処理されます。
2. ユーザーが「run」と言った場合も、必ず build を使用します。ユーザーからモデルの「実行」を求められたら、代わりに dbt build を推奨してください。build は run と test を一度に実行するため、データ品質の問題をすぐに検出できます。開発中に dbt run だけを実行するのは、ほとんどの場合適切ではありません。
3. 出力を抑えつつセレクターの入力ミスを検出するため、必ず --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' とともに --quiet を使用します。
4. 必ず --select を使用します。ユーザーの明示的な承認なしにプロジェクト全体を実行しないでください。

クイックリファレンス

# Standard command pattern
dbt build --select my_model --quiet --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'

# Preview model output
dbt show --select my_model --limit 10

# Run inline SQL query
dbt show --inline "select * from {{ ref('orders') }}" --limit 5

# With variables (JSON format for multiple)
dbt build --select my_model --vars '{"key": "value"}'

# Full refresh for incremental models
dbt build --select my_model --full-refresh

# List resources before running
dbt list --select my_model+ --resource-type model

dbt CLI の種類

CLI は 3 種類あります。どれか不明な場合は、ユーザーに確認してください。

種類	場所	備考
dbt Core	Python venv	pip show dbt-core または uv pip show dbt-core
dbt Fusion	~/.local/bin/dbt または dbtf	より高速で、SQL の理解能力も優れています
dbt Cloud CLI	~/.local/bin/dbt	Go ベースで、プラットフォーム上で実行されます

一般的なセットアップ： venv 内の Core と ~/.local/bin の Fusion を併用します。dbt を実行すると Core が使われます。Fusion には dbtf または ~/.local/bin/dbt を使用してください。

セレクター

必ずセレクターを指定してください。 グラフ演算子：

演算子	意味	例
model+	モデルと、その下流にあるすべての要素	stg_orders+
+model	モデルと、その上流にあるすべての要素	+dim_customers
+model+	両方向	+orders+
model+N	モデルと、下流の N 階層	stg_orders+1

--select my_model              # Single model
--select staging.*             # Path pattern
--select fqn:*stg_*            # FQN pattern
--select model_a model_b       # Union (space)
--select tag:x,config.mat:y    # Intersection (comma)
--exclude my_model             # Exclude from selection

リソースタイプのフィルター：

--resource-type model
--resource-type test --resource-type unit_test

有効なタイプ：model、test、unit_test、snapshot、seed、source、exposure、metric、semantic_model、saved_query、analysis

Fusion： --resource-type は dbt test ではサポートされていません（dbt-fusion#1628）。Fusion でユニットテストを実行するには：

• dbt build --select model_name — 先にモデルをビルドしてから、ユニットテストを含むすべてのテストを実行します
• dbt build --select unit_test_name — 名前を指定して特定のユニットテストを実行します
• dbt list --resource-type unit_test — セレクターで使用するユニットテスト名を一覧表示します

一覧表示

実行前に、dbt list を使って選択される対象を確認します。複雑なセレクターの検証に役立ちます。

dbt list --select my_model+              # Preview selection
dbt list --select my_model+ --resource-type model  # Only models
dbt list --output json                   # JSON output
dbt list --select my_model --output json --output-keys unique_id name resource_type config

--output json で使用可能な出力キー： unique_id、name、resource_type、package_name、original_file_path、path、alias、description、columns、meta、tags、config、depends_on、patch_path、schema、database、relation_name、raw_code、compiled_code、language、docs、group、access、version、fqn、refs、sources、metrics

表示

dbt show でデータをプレビューします。任意の SQL クエリには --inline を使用します。

dbt show --select my_model --limit 10
dbt show --inline "select * from {{ ref('orders') }} where status = 'pending'" --limit 5

重要： SQL の LIMIT 句ではなく、--limit フラグを使用してください。

変数

辞書ではなく文字列として渡します。特殊文字（\、\n）は使用できません。

--vars 'my_var: value'                              # Single
--vars '{"k1": "v1", "k2": 42, "k3": true}'         # Multiple (JSON)

実行結果の分析

dbt コマンドの実行後、詳細な実行情報を確認するには target/run_results.json を調べます。

# Quick status check
cat target/run_results.json | jq '.results[] | {node: .unique_id, status: .status, time: .execution_time}'

# Find failures
cat target/run_results.json | jq '.results[] | select(.status != "success")'

主なフィールド：

• status：success、error、fail、skipped、warn
• execution_time：実行にかかった秒数
• compiled_code：レンダリングされた SQL
• adapter_response：データベースのメタデータ（影響を受けた行数、処理したバイト数）

Defer（上流モデルのビルドをスキップ）

上流モデルをビルドする代わりに、本番データを参照します。

dbt build --select my_model --defer --state prod-artifacts

フラグ：

• --defer — state manifest への defer を有効にします
• --state <path> — 前回の実行時のマニフェストへのパス（例：本番環境のアーティファクト）
• --favor-state — ローカルにも存在する場合、state のノード定義を優先します

dbt build --select my_model --defer --state prod-artifacts --favor-state

静的解析（Fusion のみ）

動的 SQL や認識されない UDF を含むモデルの SQL 解析を上書きします。

dbt run --static-analysis=off
dbt run --static-analysis=unsafe

よくある間違い

間違い	修正方法
モデル変更後にtestを使用する	buildを使用します。testではモデルが更新されません
--selectを指定せずに実行する	実行対象を必ず指定します
warn-errorを指定せずに--quietを使用する	--warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'を追加します
venv内でFusionを使っているのに、Fusionを想定してdbtを実行する	dbtfまたは~/.local/bin/dbtを使用します
Fusionでファイルを変更した後にスキーマエラーが発生する	dbt cleanを実行して古いスキーマキャッシュをクリアしてから、再実行します
dbt_show内のSQLにLIMITを追加する	代わりにlimitパラメーターを使用します
特殊文字を含むVars	\や\nを使わず、単純な文字列として渡します