dbt コマンドの実行

推奨事項

1. 利用可能な場合は MCP ツールを使用 (dbt_build, dbt_run, dbt_show など) - パス、タイムアウト、フォーマットを自動で処理します
2. ユーザーが「run」と言った場合でも常に build を使用 - ユーザーがモデルを「実行」するよう求めている場合、代わりに dbt build を推奨してください。build = run + test を1ステップで実行するため、データ品質の問題をすぐに検出できます。dbt run だけでは開発中はほぼ正解ではありません。
3. 常に --quiet を使用 して --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}' と共に使う - 出力を削減しながらセレクタのタイプミスを検出します
4. 常に --select を使用 - ユーザーの明示的な承認なしにプロジェクト全体を実行しません

クイックリファレンス

# 標準的なコマンドパターン
dbt build --select my_model --quiet --warn-error-options '{"error": ["NoNodesForSelectionCriteria"]}'

# モデルの出力をプレビュー
dbt show --select my_model --limit 10

# インライン SQL クエリを実行
dbt show --inline "select * from {{ ref('orders') }}" --limit 5

# 変数付き (複数の場合は JSON フォーマット)
dbt build --select my_model --vars '{"key": "value"}'

# インクリメンタルモデルの完全更新
dbt build --select my_model --full-refresh

# 実行前にリソースをリスト表示
dbt list --select my_model+ --resource-type model

dbt CLI フレーバー

3 つの CLI が存在します。不明な場合はユーザーに確認してください。

フレーバー	場所	備考
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              # 単一モデル
--select staging.*             # パスパターン
--select fqn:*stg_*            # FQN パターン
--select model_a model_b       # 和集合 (スペース)
--select tag:x,config.mat:y    # 交集合 (カンマ)
--exclude my_model             # セレクションから除外

リソースタイプフィルター:

--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+              # セレクションをプレビュー
dbt list --select my_model+ --resource-type model  # モデルのみ
dbt list --output json                   # JSON 出力
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 フラグを使用してください。

変数

STRING として渡してください。dict ではなく、特殊文字 (\, \n) なし。

--vars 'my_var: value'                              # 単一
--vars '{"k1": "v1", "k2": 42, "k3": true}'         # 複数 (JSON)

実行結果の分析

dbt コマンド実行後、詳細な実行情報については target/run_results.json を確認してください:

# クイックステータスチェック
cat target/run_results.json | jq '.results[] | {node: .unique_id, status: .status, time: .execution_time}'

# 失敗を検出
cat target/run_results.json | jq '.results[] | select(.status != "success")'

主要フィールド:

• status: success, error, fail, skipped, warn
• execution_time: 実行に費やした秒数
• compiled_code: レンダリングされた SQL
• adapter_response: データベースメタデータ (影響を受けた行数、処理されたバイト数)

遅延実行 (上流ビルドをスキップ)

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

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

フラグ:

• --defer - 状態マニフェストへの遅延を有効化
• --state <path> - 前回の実行 (例: 本番アーティファクト) からのマニフェストへのパス
• --favor-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"]}' を追加してください
Fusion を期待しているのに venv 内で dbt を実行	dbtf または ~/.local/bin/dbt を使用してください
Fusion でファイル変更後のスキーマエラー	dbt clean を実行してスタイルなスキーマキャッシュをクリアしてから再実行してください
dbt_show の SQL に LIMIT を追加	代わりに limit パラメータを使用してください
特殊文字を含む変数	シンプルな文字列として渡す (\ や \n なし)