調査日: 2026-02-28 対象バージョン: dbt Core 1.6 〜 1.12(dbt Cloud 2024.03 〜 2026.01)


概要

flags(グローバルコンフィグ)は、dbt がプロジェクトをどのように実行するかを制御する設定です。「何を実行するか」(モデルの定義)ではなく「どう実行するか」(ログ出力方法、エラー処理など)を指定します。

dbt_project.ymlflags: セクションに記述することで、設定をバージョン管理下に置けます。


目次

  1. 設定優先順位
  2. 一般フラグ(Project Flags)
  3. 動作変更フラグ(Behavior Change Flags)
  4. バージョン別導入履歴
  5. 実際の使用例
  6. GitHubでよく使われているフラグ設定パターン

1. 設定優先順位

同じフラグを複数の場所で設定した場合、以下の優先順位で解決されます(高い順):

CLI オプション
  > 環境変数
    > dbt_project.yml の flags
      > dbt ハードコードデフォルト

設定できないフラグ

ファイルパス系フラグ(--log-path--state など)は dbt_project.yml に設定できません。

また、動作変更フラグ(Behavior Change Flags)はバージョン管理の観点から dbt_project.yml のみに設定することが推奨されています。


2. 一般フラグ(Project Flags)

基本構文

# dbt_project.yml
flags:
  partial_parse: true
  send_anonymous_usage_stats: false

フラグ一覧

フラグ名デフォルト環境変数説明
cache_selected_onlybooleanfalseDBT_CACHE_SELECTED_ONLY選択されたモデルのみキャッシュ対象にする
debugbooleanfalseDBT_DEBUGデバッグレベルのログ出力を有効化する
fail_fastbooleanfalseDBT_FAIL_FAST最初のエラーで即座に停止する(-x と同等)
full_refreshbooleanfalseIncremental モデルをフルリビルドする
indirect_selectionenumeagerDBT_INDIRECT_SELECTIONテスト選択の間接選択動作を制御(eager / cautious / buildable / empty
log_formatenumdefaultDBT_LOG_FORMATコンソールログのフォーマット(default / json / text
log_format_fileenumdefaultDBT_LOG_FORMAT_FILEファイルログのフォーマット
log_levelenuminfoDBT_LOG_LEVELコンソールログの詳細度(debug / info / warn / error / none
log_level_fileenumdebugDBT_LOG_LEVEL_FILEファイルログの詳細度
partial_parsebooleantrueDBT_PARTIAL_PARSE増分プロジェクトパーシングを有効化(起動高速化)
populate_cachebooleantrueDBT_POPULATE_CACHE実行開始時にリレーショナルキャッシュを構築する
printer_widthint80コンソール出力の幅(文字数)
send_anonymous_usage_statsbooleantrueDBT_SEND_ANONYMOUS_USAGE_STATSdbt Labs への匿名使用統計送信(DO_NOT_TRACK=1 でも無効化可能)
static_parserbooleantrue静的パーシングアプローチを使用する
use_colorsbooleantrueDBT_USE_COLORSコンソール出力のカラー表示を有効化する
use_colors_filebooleantrueログファイルのカラー表示を有効化する
use_experimental_parserbooleanfalse実験的パーシング機能を有効化する
version_checkbooleanvariesDBT_VERSION_CHECKdbt バージョン互換性チェックを行う
warn_errorbooleanfalseDBT_WARN_ERROR警告をエラーとして扱う
warn_error_optionsobjectDBT_WARN_ERROR_OPTIONS警告/エラー変換を細かく制御する
write_jsonbooleantrueJSON アーティファクト(manifest.json 等)を生成する

各フラグの詳細

partial_parse(デフォルト: true

前回の実行結果をキャッシュして増分パーシングを行います。変更されていないファイルは再パースしないため起動が高速になります。

flags:
  partial_parse: true

CIなどでキャッシュが問題を引き起こす場合は false に設定します。


warn_error / warn_error_options(デフォルト: false

warn_error: true は警告をすべてエラーとして扱います。warn_error_options を使うと特定の警告のみをエラーや無視に設定できます。

flags:
  warn_error: false
  warn_error_options:
    error:
      - NoNodesForSelectionCriteria
    silence:
      - DeprecatedModel

fail_fast(デフォルト: false

最初のエラーが発生した時点でジョブ全体を停止します。CI/CD でフィードバックを速くしたい場合に有効です。

flags:
  fail_fast: true

send_anonymous_usage_stats(デフォルト: true

dbt Labs に匿名の使用統計を送信するかどうかを制御します。ネットワーク制限がある環境や社内ポリシーで外部送信が禁止されている場合は false にします。

flags:
  send_anonymous_usage_stats: false

indirect_selection(デフォルト: eager

--select でモデルを選択した際に、そのモデルに紐づくテストをどこまで選択するかを制御します。

動作
eager選択モデルに関連するすべてのテストを実行(デフォルト)
cautious選択モデルのみをテスト対象にする(未選択モデルを含むテストはスキップ)
buildable選択モデルとその上流が実行済みのテストのみ対象
emptyテストを一切選択しない
flags:
  indirect_selection: cautious

3. 動作変更フラグ(Behavior Change Flags)

新機能への段階的な移行を管理するためのフラグです。古い挙動から新しい挙動へ安全に移行できます。

ライフサイクル

Phase 1(導入):   フラグ追加 → デフォルト false(旧挙動を維持)
                   早期採用者はオプトインして新挙動を使用可能

Phase 2(成熟):   デフォルト true に変更(新挙動がデフォルト)
                   false に設定することで一時的に旧挙動に戻せる

Phase 3(削除):   フラグとコードを削除、常に新挙動が適用される

dbt Fusion では、すべての Behavior Change Flags が削除済みで、常に新しい動作が適用されます。

Behavior Change Flags 一覧

フラグ名デフォルト導入バージョンデフォルト true 化Fusion
require_explicit_package_overrides_for_builtin_materializationstrueCore 1.6.14Core 1.8.0削除済
require_resource_names_without_spacestrueCore 1.8.0Core 1.10.0削除済
source_freshness_run_project_hookstrueCore 1.8.0Core 1.10.0削除済
skip_nodes_if_on_run_start_failsfalseCore 1.9.0TBD削除済
state_modified_compare_more_unrendered_valuesfalseCore 1.9.0TBD削除済
require_yaml_configuration_for_mf_time_spinesfalseCore 1.9.0TBD削除済
require_batched_execution_for_custom_microbatch_strategyfalseCore 1.9.0TBD削除済
require_nested_cumulative_type_paramsfalseCore 1.9.0TBD未対応
validate_macro_argsfalseCore 1.10.0TBD未対応
require_all_warnings_handled_by_warn_errorfalseCore 1.10.0TBD未対応
require_generic_test_arguments_propertytrueCore 1.10.5Core 1.10.8未対応
require_unique_project_resource_namesfalseCore 1.11.0TBD未対応
require_ref_searches_node_package_before_rootfalseCore 1.11.0TBD未対応
require_valid_schema_from_generate_schema_namefalseCore 1.12.0a1TBD未対応

各フラグの詳細

require_explicit_package_overrides_for_builtin_materializations

  • 導入: Core 1.6.14(dbt Cloud 2024.04)
  • デフォルト true 化: Core 1.8.0(dbt Cloud 2024.06)
  • Fusion: 削除済み

内容: インストール済みパッケージが暗黙的にビルトインマテリアライゼーション(tableviewincremental など)を上書きするのを防ぎます。

  • false(旧挙動): パッケージが自動的にビルトインマテリアライゼーションを上書き可能
  • true(新挙動): 明示的な設定なしにパッケージが上書きするとエラー
flags:
  require_explicit_package_overrides_for_builtin_materializations: true

require_resource_names_without_spaces

  • 導入: Core 1.8.0(dbt Cloud 2024.05)
  • デフォルト true 化: Core 1.10.0(dbt Cloud 2025.05)
  • Fusion: 削除済み

内容: リソース名(モデル名、テスト名など)に英数字とアンダースコアのみを使用することを強制します。

  • false(旧挙動): スペースを含むリソース名を許容
  • true(新挙動): スペースを含む名前はパースエラー
flags:
  require_resource_names_without_spaces: true

source_freshness_run_project_hooks

  • 導入: Core 1.8.0(dbt Cloud 2024.03)
  • デフォルト true 化: Core 1.10.0(dbt Cloud 2025.05)
  • Fusion: 削除済み

内容: dbt source freshness 実行時に on-run-start / on-run-end プロジェクトフックを含めるかを制御します。

  • false(旧挙動): freshness チェック時にフックをスキップ
  • true(新挙動): freshness チェック時もフックを実行
flags:
  source_freshness_run_project_hooks: true

skip_nodes_if_on_run_start_fails

  • 導入: Core 1.9.0(dbt Cloud 2024.10)
  • Fusion: 削除済み

内容: on-run-start フックが失敗した場合、選択されたすべてのリソースの実行をスキップします。

  • false(旧挙動): フック失敗後もモデル実行を継続
  • true(新挙動): フック失敗時に選択済みリソースをスキップ

CI/CD環境でフックの失敗を早期に検知したい場合に有効です。

flags:
  skip_nodes_if_on_run_start_fails: true

state_modified_compare_more_unrendered_values

  • 導入: Core 1.9.0(dbt Cloud 2024.10)
  • Fusion: 削除済み

内容: state:modified チェック時に、レンダリング済みの値ではなく未レンダリング値(Jinja テンプレートのソースコード)を比較します。環境変数などによる false positive(誤検知)を削減できます。

  • false(旧挙動): レンダリング済み値で比較 → 環境差異による誤検知が発生しやすい
  • true(新挙動): 未レンダリング値で比較 → より正確な差分検出

CI/CD で state:modified を使っている場合、このフラグを true にすることで不要な再実行を削減できます。

flags:
  state_modified_compare_more_unrendered_values: true

require_yaml_configuration_for_mf_time_spines

  • 導入: Core 1.9.0(dbt Cloud 2024.10)

内容: MetricFlow のタイムスパイン設定を YAML 形式で記述することを強制します。従来の Python ベース設定からの移行を促します。

flags:
  require_yaml_configuration_for_mf_time_spines: true

require_batched_execution_for_custom_microbatch_strategy

  • 導入: Core 1.9.0(dbt Cloud 2024.11)
  • Fusion: 削除済み

内容: カスタムマイクロバッチ戦略(get_batch_size マクロなど)を持つプロジェクトで、バッチ実行を強制します。カスタムマイクロバッチマクロを定義している場合は true に設定することが推奨されます。

flags:
  require_batched_execution_for_custom_microbatch_strategy: true

require_nested_cumulative_type_params

  • 導入: Core 1.9.0(dbt Cloud 2024.11)

内容: 累積メトリクスのパラメータを cumulative_type_params 配下にネスト形式で記述することを強制します。

  • false(旧挙動): フラットな形式で記述可能
  • true(新挙動): cumulative_type_params 配下にネスト必須
# true にした場合の記述形式
metrics:
  - name: cumulative_revenue
    type: cumulative
    type_params:
      cumulative_type_params:
        period: all_time
flags:
  require_nested_cumulative_type_params: true

validate_macro_args

  • 導入: Core 1.10.0(dbt Cloud 2025.03)

内容: パース時にマクロの引数名と型を検証します。引数の定義と呼び出しが一致しない場合にエラーを発生させます。

flags:
  validate_macro_args: true

require_all_warnings_handled_by_warn_error

  • 導入: Core 1.10.0(dbt Cloud 2025.06)

内容: すべての警告を warn_error_options ハンドラー経由でルーティングすることを要求します。未処理の警告がある場合にエラーを発生させます。

flags:
  require_all_warnings_handled_by_warn_error: true

require_generic_test_arguments_property

  • 導入: Core 1.10.5(dbt Cloud 2025.07)
  • デフォルト true 化: Core 1.10.8(dbt Cloud 2025.08)

内容: ジェネリックテストのキーバリュー引数を arguments プロパティ配下でパースすることを要求します。

flags:
  require_generic_test_arguments_property: true

require_unique_project_resource_names

  • 導入: Core 1.11.0(dbt Cloud 2025.12)

内容: 同一パッケージ内でリソース名のユニーク性を強制します。重複がある場合は DuplicateResourceNameError が発生します。

flags:
  require_unique_project_resource_names: true

require_ref_searches_node_package_before_root

  • 導入: Core 1.11.0(dbt Cloud 2025.12)

内容: ref() の名前解決時に、ルートプロジェクトより先にモデルが定義されているパッケージを検索します。パッケージ間の名前解決の一貫性が向上します。

flags:
  require_ref_searches_node_package_before_root: true

require_valid_schema_from_generate_schema_name

  • 導入: Core 1.12.0a1(dbt Cloud 2026.01)

内容: カスタム generate_schema_name マクロが有効なスキーマ名(null 以外)を返すことを強制します。

flags:
  require_valid_schema_from_generate_schema_name: true

4. バージョン別導入履歴

dbt Coredbt Cloud導入されたフラグ
1.6.142024.04require_explicit_package_overrides_for_builtin_materializations
1.8.02024.05〜06require_resource_names_without_spacessource_freshness_run_project_hooks
1.9.02024.10〜11skip_nodes_if_on_run_start_failsstate_modified_compare_more_unrendered_valuesrequire_yaml_configuration_for_mf_time_spinesrequire_batched_execution_for_custom_microbatch_strategyrequire_nested_cumulative_type_params
1.10.02025.03〜06validate_macro_argsrequire_all_warnings_handled_by_warn_error
1.10.52025.07require_generic_test_arguments_property
1.11.02025.12require_unique_project_resource_namesrequire_ref_searches_node_package_before_root
1.12.0a12026.01require_valid_schema_from_generate_schema_name

5. 実際の使用例

Core 1.9.x 本番環境

name: my_project
version: "1.0.0"
config-version: 2
 
profile: default
 
flags:
  # テレメトリ
  send_anonymous_usage_stats: false
 
  # パーシング最適化
  partial_parse: true
 
  # 出力設定
  use_colors: true
  printer_width: 120
 
  # アーティファクト生成
  write_json: true
 
  # 1.9.0 で導入(推奨設定)
  skip_nodes_if_on_run_start_fails: true
  state_modified_compare_more_unrendered_values: true

Core 1.10.x へのアップグレード時

1.10.0 でデフォルトが true に変わったフラグを確認し、既存プロジェクトへの影響を評価します。

flags:
  # 1.10.0 でデフォルト true 化(影響があれば false に戻して移行猶予を確保)
  require_resource_names_without_spaces: false # スペース含む名前を一時的に許容
  source_freshness_run_project_hooks: false # freshness 時にフックをスキップ
 
  # 1.10.0 で新規導入(準備ができたら true に)
  validate_macro_args: false

dbt-project-evaluator の実例

dbt-labs/dbt-project-evaluator の設定例:

flags:
  require_nested_cumulative_type_params: true
  require_yaml_configuration_for_mf_time_spines: true
  require_generic_test_arguments_property: true

CI/CD で state:modified を活用する場合

誤検知削減のために state_modified_compare_more_unrendered_values を有効化します。

flags:
  state_modified_compare_more_unrendered_values: true
  skip_nodes_if_on_run_start_fails: true
  partial_parse: true
  write_json: true

6. GitHubでよく使われているフラグ設定パターン

GitHub上のパブリックリポジトリを調査した結果をもとに、実際によく使われるフラグのパターンをまとめます。

6.1 使用頻度ランキング

使用頻度フラグよくある設定値用途
ほぼ全プロジェクトsend_anonymous_usage_statsfalseプライバシー・社内ポリシー対応
CI/CDプロジェクトの多数fail_fasttrue最初のエラーで即停止してフィードバックを速くする
CI/CDプロジェクトの多数use_colorsfalseCIログを読みやすくする・ログパーサーとの互換性
CI/CDプロジェクトの多数log_formatjsonDatadog等のログ収集ツールとの連携
増加中(1.9.0以降)skip_nodes_if_on_run_start_failstrueフック失敗時の安全停止
増加中(1.9.0以降)state_modified_compare_more_unrendered_valuestrueSlim CI の誤検知削減
専門用途warn_error_options個別設定品質管理の強化

6.2 OSSリポジトリの実例

dbt Labsの公式リポジトリからの設定例です。

dbt-utils(integration_tests)

最小構成。プライバシー設定のみ設定する典型例。

flags:
  send_anonymous_usage_stats: false
  use_colors: true

dbt-project-evaluator

Behavior Change Flags を積極的に採用する例。

flags:
  require_nested_cumulative_type_params: true
  require_yaml_configuration_for_mf_time_spines: true
  require_generic_test_arguments_property: true

6.3 ユースケース別推奨パターン

パターン A:最小構成(全プロジェクト共通推奨)

send_anonymous_usage_stats はネットワーク制限や社内ポリシーに関わらず、設定しておくことが推奨されます。

flags:
  send_anonymous_usage_stats: false

パターン B:CI/CD 厳格モード

CIログをパース可能にして、ログ収集ツール(Datadog・CloudWatch など)との連携を容易にするパターンです。

flags:
  send_anonymous_usage_stats: false
  fail_fast: true
  use_colors: false
  log_format: json

パターン C:Slim CI(state:modified 活用)

state:modified で変更モデルのみ実行する Slim CI パターン。state_modified_compare_more_unrendered_values: true で環境変数による誤検知を削減します。

flags:
  send_anonymous_usage_stats: false
  state_modified_compare_more_unrendered_values: true
  skip_nodes_if_on_run_start_fails: true
  partial_parse: true
  write_json: true

パターン D:品質管理強化モード

プロジェクトのポリシーに合わせて警告を細かく制御するパターンです。

flags:
  send_anonymous_usage_stats: false
  warn_error_options:
    error:
      - NoNodesForSelectionCriteria
    warn:
      - DeprecatedModel
    silence:
      - SpacesInResourceNameDeprecation

6.4 warn_error_options 詳細パターン

warn_error_options で使えるキーとよく使われるイベント名:

flags:
  warn_error_options:
    error: # 警告をエラーとして扱う(ビルドを失敗させる)
      - NoNodesForSelectionCriteria # セレクターで対象ノードなし
    warn: # エラーを警告として扱う(ビルドは継続)
      - DeprecatedModel # 非推奨モデル参照
    silence: # 完全に無視する
      - SpacesInResourceNameDeprecation # リソース名のスペース(移行期)
      - PackageRedirectDeprecation # パッケージのリダイレクト通知

6.5 よくある設定ミス・アンチパターン

warn_error_options: error: all は避ける

dbt のバージョンアップで新しい警告が追加されると自動的にビルドが失敗するリスクがあります。特定のイベント名を明示的に指定する方が安全です。

# 避けるべき例
flags:
  warn_error_options:
    error: all  # バージョンアップ時に予期せぬ失敗が発生する可能性
 
# 推奨例
flags:
  warn_error_options:
    error:
      - NoNodesForSelectionCriteria  # 具体的なイベント名を指定

partial_parse: false を本番環境に常時設定しない

CIでキャッシュ問題が発生した場合の一時的な対処としては有効ですが、常時 false にすると起動が遅くなります。

CI専用の厳格オプションはフラグ化しない

dbt_project.yml の flags: はローカル開発を含む全環境に適用されます。CI専用の厳格チェックはCLIオプションとして明示的に記述することで、スコープと意図を明確に保てます。

フラグ vs CLIオプションの比較

観点dbt_project.yml flagsCLIオプション
適用範囲全環境(ローカル・CI・本番)一律コマンド単位で制御可能
ローカル開発への影響全実行に適用されるCI環境のみに影響を限定できる
意図の明示なぜその設定をしているか伝わりにくいCIワークフローのコメントで意図を説明できる
段階的な厳格化全て同じ厳しさになるフェーズごとに異なる厳しさを設定できる

たとえば warn_error: true をフラグ化すると、移行作業中にローカルで DeprecatedModel 警告が出るたびに実行がエラーで止まります。CIでのみ厳格にしたい意図がフラグからは読み取れません。

warn_error_options だけはプロジェクト全体の品質ポリシーとして dbt_project.yml に設定する意義があります。

チェック1:非推奨機能の警告チェック(dbt --warn-error ls

ls はモデル一覧を取得する軽量コマンドで、SQL を実行せずにグラフ全体をパースします。--warn-error を付けることで、DeprecatedModel などの非推奨APIの使用をCIで検出できます。

  • ls を使う理由: run/build より高速。SQL実行なしで ref・source の解決とグラフ整合性を検証できる
  • フラグ化しない理由: ローカルで非推奨機能の移行作業中に毎回エラーになり開発体験が悪化する
- name: Check for deprecation warnings
  run: dbt --warn-error ls
チェック2:コンパイル検証(dbt compile --show-all-deprecations --no-partial-parse

Jinja 展開・SQL 生成まで検証し、実際のDBに接続せずにコンパイルエラーを検出します。

  • --show-all-deprecations: デフォルトは最初の1件のみ表示。全件表示させることで見落としを防ぐ(フラグ対応なし)
  • --no-partial-parse: キャッシュを使わず全ファイルを再パース。削除済みファイルへの参照など、キャッシュが隠す問題を検出できる
  • フラグ化しない理由: partial_parse: false を常時設定すると全ての実行が遅くなる
- name: Compile all models
  run: dbt compile --show-all-deprecations --no-partial-parse

6.6 CIで推奨するその他のチェック

チェックコマンド目的
構文チェック(高速)dbt parseJinja展開なし。ref/source解決もしないため最速
グラフ整合性dbt lsref/sourceが解決でき、グラフに矛盾がないことを確認
ソーステストdbt test -s source:*upstream のスキーマ変更をモデル実行前に検出
Slim CIdbt build -s state:modified+変更モデルと下流のみ実行。全体実行より高速
ソース鮮度dbt source freshnessデータ遅延をCIで検知
失敗ノード再実行dbt retryflaky な外部依存によるエラーを再試行で回避

dbt parse vs dbt ls vs dbt compile の使い分け

dbt parse
  └── Jinja展開なし・依存解決なし → 最速、構文エラーのみ検出
dbt ls
  └── Jinja展開あり・依存解決あり → ref/source の解決を確認
dbt compile
  └── SQL生成まで実行 → コンパイルエラーを検出(最も重い)

参照