# О флагах (глобальные конфигурации)
В dbt «флаги» (также называемые «глобальными настройками» и часто задаваемые с помощью [переменных окружения](https://docs.getdbt.tech/reference/global-configs/environment-variable-configs.md)) — это настройки для точного управления тем, *как* dbt выполняет ваш проект. Они отличаются от [настроек отдельных ресурсов](https://docs.getdbt.tech/reference/configs-and-properties.md), которые указывают dbt, *что* выполнять.
Флаги управляют такими вещами, как визуальный вывод логов, следует ли рассматривать определенные предупреждения как ошибки, или следует ли "быстро завершать" выполнение после первой ошибки. Флаги являются "глобальными" конфигурациями, потому что они доступны для всех команд dbt и могут быть установлены в нескольких местах.
Вы можете использовать флаги с движком dbt v2 или dbt v1 через CLI при локальной разработке или в dbt platform.
Флаги dbt и параметры командной строки dbt во многом пересекаются, но между ними есть различия:
* Некоторые флаги можно задать только в [`dbt_project.yml`](https://docs.getdbt.tech/reference/dbt_project.yml.md), и их нельзя переопределить для отдельных запусков с помощью параметров CLI.
* Если параметр CLI поддерживается только определёнными командами, а не всеми командами (то есть не является «глобальным»), он обычно не считается «флагом».
Вы можете настраивать флаги в `dbt_project.yml`, с помощью переменных окружения и параметров CLI. Подробности см. в разделе [Настройка с помощью переменных окружения](https://docs.getdbt.tech/reference/global-configs/environment-variable-configs.md).
### Настройка флагов
Существует несколько способов настройки флагов в зависимости от сценария использования:
* **[Параметры CLI](https://docs.getdbt.tech/reference/global-configs/command-line-options.md):** Определяют поведение для *конкретного вызова*. Поддерживаются для всех команд dbt.
* **[Переменные окружения](https://docs.getdbt.tech/reference/global-configs/environment-variable-configs.md):** Определяют различное поведение в разных средах выполнения (разработка, промышленная эксплуатация или [непрерывная интеграция](https://docs.getdbt.tech/docs/deploy/continuous-integration.md)) или для разных пользователей в среде разработки (на основе личных предпочтений).
* **[Флаги `flags` на уровне проекта в `dbt_project.yml`](https://docs.getdbt.tech/reference/global-configs/project-flags.md):** Определяют значения по умолчанию, хранящиеся в системе контроля версий, для всех, кто запускает этот проект. Также позволяют включать или отключать [изменения поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md), чтобы управлять переходом с устаревшей функциональности.
* **[Пользовательские настройки (`~/.dbt/user_settings.yml`)](https://docs.getdbt.tech/reference/global-configs/user-settings.md):** Определяют личные предпочтения, которые применяются ко всем проектам на вашем компьютере. Записываются автоматически командой `dbt login`.
Наиболее конкретная настройка имеет приоритет. Наивысший приоритет имеют параметры CLI, затем идут переменные окружения, далее — `dbt_project.yml` и, наконец, `user_settings.yml`. Если флаг не задан ни в одном из этих мест, используется значение по умолчанию, определённое в dbt.
```yaml
# dbt_project.yml
flags:
# значение по умолчанию для запуска этого проекта — везде, всегда, для всех
fail_fast: true
```
(Версии dbt: v1.11 и новее)
```bash
# установите для этой переменной окружения значение 'True' (синтаксис bash)
export DBT_ENGINE_FAIL_FAST=1
dbt run
```
```bash
dbt run --fail-fast # установить True для этого конкретного запуска
dbt run --no-fail-fast # установить False
```
Есть две категории исключений:
1. **Флаги, задающие пути к файлам:** Флаги для путей к файлам, используемых во время выполнения (например, `--log-path` или `--state`), нельзя задавать в `dbt_project.yml`. Чтобы переопределить значения по умолчанию, передайте параметры CLI или задайте переменные окружения ((Версии dbt: v1.11 и новее) `DBT_ENGINE_LOG_PATH` и `DBT_ENGINE_STATE`). Флаги, указывающие dbt, где искать ресурсы проекта (например, `model-paths`), задаются в `dbt_project.yml`, но в виде ключей верхнего уровня, вне словаря `flags`; эти настройки должны быть полностью статичными и никогда не меняться в зависимости от команды или среды выполнения.
2. **Флаги включения изменений поведения:** Флаги, включающие или отключающие [изменения поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md), можно задавать *только* в `dbt_project.yml`. Предполагается, что они задаются в системе контроля версий и изменяются через запросы на слияние (pull/merge request). Их значения не должны оставаться различными для разных запусков, сред или пользователей в течение неопределённо долгого времени.
### Доступ к флагам
Пользовательская логика, написанная на Jinja, может проверять значения флагов, используя [контекстную переменную `flags`](https://docs.getdbt.tech/reference/dbt-jinja-functions/flags.md).
```yaml
# dbt_project.yml
on-run-start:
- '{{ log("Я остановлюсь при первом признаке проблемы", info = true) if flags.FAIL_FAST }}'
```
## Доступные флаги
Поскольку значения `flags` могут различаться от запуска к запуску, мы настоятельно рекомендуем не использовать `flags` в качестве входных данных для конфигураций или зависимостей (`ref` + `source`), которые dbt разрешает [во время разбора](https://docs.getdbt.tech/reference/parsing.md#known-limitations).
Используйте эту таблицу для сравнения всех доступных флагов и способов их настройки через различные интерфейсы:
* **CLI dbt**: Указывает, поддерживается ли флаг в [CLI, поддерживаемом dbt platform](https://docs.getdbt.tech/docs/platform/dbt-cli-installation.md).
* **Тип / значение по умолчанию**: Показывает допустимый тип значения и значение по умолчанию.
* **В проекте**: Указывает, можно ли задать флаг в `dbt_project.yml`.
* **Переменная окружения**: Показывает имя соответствующей переменной окружения, если она доступна. Как правило, в версии v1.10 и более ранних используется префикс `DBT_`, а в v1.11 и более поздних — префикс `DBT_ENGINE_`.
* **Флаги CLI**: Перечисляет параметры командной строки для задания флага на конкретный запуск.
(Версии dbt: v1.11 и новее)
| Flag | dbt CLI? | Type / default | In project? | Env var | CLI flags |
| ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------- | ----------------------- | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| [ai\_provider](https://docs.getdbt.tech/docs/dbt-ai/package-skills.md#set-the-ai_provider-flag) (v2.0+) | ❌ | list
default: None | ✅ | `DBT_ENGINE_AI_PROVIDER` | `--ai-provider` |
| [batch\_tests](https://docs.getdbt.tech/reference/global-configs/batch-tests.md) (v2.0+) | ❌ | boolean
default: False | ✅ | `DBT_ENGINE_BATCH_TESTS` | `--batch-tests` |
| [cache\_selected\_only](https://docs.getdbt.tech/reference/global-configs/cache.md) | ✅ | boolean
default: False | ✅ | `DBT_ENGINE_CACHE_SELECTED_ONLY` | `--cache-selected-only`
`--no-cache-selected-only` |
| [clean\_project\_files\_only](https://docs.getdbt.tech/reference/commands/clean.md#clean-project-files-only) | ❌ | boolean
default: True | ❌ | `DBT_ENGINE_CLEAN_PROJECT_FILES_ONLY` | `--clean-project-files-only`
`--no-clean-project-files-only` |
| [debug](https://docs.getdbt.tech/reference/global-configs/logs.md#debug-level-logging) | ✅ | boolean
default: False | ✅ | `DBT_ENGINE_DEBUG` | `--debug`
`--no-debug` |
| [defer](https://docs.getdbt.tech/reference/node-selection/defer.md) | ✅ (default) | boolean
default: False | ❌ | `DBT_ENGINE_DEFER` | `--defer`
`--no-defer` |
| [defer\_state](https://docs.getdbt.tech/reference/node-selection/defer.md) | ❌ | path
default: None | ❌ | `DBT_ENGINE_DEFER_STATE` | `--defer-state` |
| [favor\_state](https://docs.getdbt.tech/reference/node-selection/defer.md#favor-state) | ✅ | boolean
default: False | ❌ | `DBT_ENGINE_FAVOR_STATE` | `--favor-state`
`--no-favor-state` |
| [empty](https://docs.getdbt.tech/docs/build/empty-flag.md) | ✅ | boolean
default: False | ❌ | `DBT_ENGINE_EMPTY` | `--empty`
`--no-empty` |
| [event\_time\_start](https://docs.getdbt.tech/reference/dbt-jinja-functions/model.md#batch-properties-for-microbatch-models) | ✅ | datetime
default: None | ❌ | `DBT_ENGINE_EVENT_TIME_START` | `--event-time-start` |
| [event\_time\_end](https://docs.getdbt.tech/reference/dbt-jinja-functions/model.md#batch-properties-for-microbatch-models) | ✅ | datetime
default: None | ❌ | `DBT_ENGINE_EVENT_TIME_END` | `--event-time-end` |
| [fail\_fast](https://docs.getdbt.tech/reference/global-configs/failing-fast.md) | ✅ | boolean
default: False | ✅ | `DBT_ENGINE_FAIL_FAST` | `--fail-fast`
`-x`
`--no-fail-fast` |
| [full\_refresh](https://docs.getdbt.tech/reference/resource-configs/full_refresh.md) | ✅ | boolean
default: False | ✅ (as resource config) | `DBT_ENGINE_FULL_REFRESH` | `--full-refresh`
`--no-full-refresh` |
| [generate\_info\_schema](https://docs.getdbt.tech/docs/build/dbt-information-schema.md) (v2.0+) | ✅ | boolean
default: False | ❌ | `DBT_ENGINE_GENERATE_INFO_SCHEMA` | `--generate-info-schema` |
| hints\_enabled (v1.12+) | ✅ | boolean
default: True | ✅ | `DBT_ENGINE_HINTS_ENABLED` | `--hints-enabled`
`--no-hints-enabled` |
| [indirect\_selection](https://docs.getdbt.tech/reference/node-selection/test-selection-examples.md#test-selection-syntax-examples) | ❌ | enum
default: eager | ✅ | `DBT_ENGINE_INDIRECT_SELECTION` | `--indirect-selection` |
| [info\_schema\_dir](https://docs.getdbt.tech/docs/build/dbt-information-schema.md) (v2.0+) | ✅ | path
default: None (uses `/info_schema/`) | ❌ | `DBT_ENGINE_INFO_SCHEMA_DIR` | `--info-schema-dir` |
| [introspect](https://docs.getdbt.tech/reference/commands/compile.md#introspective-queries) | ❌ | boolean
default: True | ❌ | `DBT_ENGINE_INTROSPECT` | `--introspect`
`--no-introspect` |
| [log\_cache\_events](https://docs.getdbt.tech/reference/global-configs/logs.md#logging-relational-cache-events) | ❌ | boolean
default: False | ❌ | `DBT_ENGINE_LOG_CACHE_EVENTS` | `--log-cache-events`
`--no-log-cache-events` |
| [log\_format\_file](https://docs.getdbt.tech/reference/global-configs/logs.md#log-formatting) | ❌ | enum
default: default (text) | ✅ | `DBT_ENGINE_LOG_FORMAT_FILE` | `--log-format-file` |
| [log\_format](https://docs.getdbt.tech/reference/global-configs/logs.md#log-formatting) | ❌ | enum
default: default (text) | ✅ | `DBT_ENGINE_LOG_FORMAT` | `--log-format` |
| [log\_level\_file](https://docs.getdbt.tech/reference/global-configs/logs.md#log-level) | ❌ | enum
default: debug | ✅ | `DBT_ENGINE_LOG_LEVEL_FILE` | `--log-level-file` |
| [log\_level](https://docs.getdbt.tech/reference/global-configs/logs.md#log-level) | ❌ | enum
default: info | ✅ | `DBT_ENGINE_LOG_LEVEL` | `--log-level` |
| [log\_path](https://docs.getdbt.tech/reference/global-configs/logs.md) | ❌ | path
default: None (uses `logs/`) | ❌ | `DBT_ENGINE_LOG_PATH` | `--log-path` |
| [manage\_state](https://docs.getdbt.tech/docs/deploy/dbt-state-setup.md) (v1.13+) | ✅ | boolean
default: False | ✅ | `DBT_ENGINE_MANAGE_STATE` | `--manage-state`
`--no-manage-state` |
| [partial\_parse](https://docs.getdbt.tech/reference/global-configs/parsing.md#partial-parsing) | ✅ | boolean
default: True | ✅ | `DBT_ENGINE_PARTIAL_PARSE` | `--partial-parse`
`--no-partial-parse` |
| [populate\_cache](https://docs.getdbt.tech/reference/global-configs/cache.md) | ✅ | boolean
default: True | ✅ | `DBT_ENGINE_POPULATE_CACHE` | `--populate-cache`
`--no-populate-cache` |
| [print](https://docs.getdbt.tech/reference/global-configs/print-output.md#suppress-print-messages-in-stdout) | ❌ | boolean
default: True | ❌ | `DBT_ENGINE_PRINT` | `--print`
`--no-print` |
| [printer\_width](https://docs.getdbt.tech/reference/global-configs/print-output.md#printer-width) | ❌ | int
default: 80 | ✅ | `DBT_ENGINE_PRINTER_WIDTH` | `--printer-width` |
| [profile](https://docs.getdbt.tech/docs/local/connection-profiles.md#about-profiles) | ❌ | string
default: None | ✅ (as top-level key) | `DBT_ENGINE_PROFILE` | [`--profile`](https://docs.getdbt.tech/docs/local/connection-profiles.md#overriding-profiles-and-targets) |
| [profiles\_dir](https://docs.getdbt.tech/docs/local/connection-profiles.md#about-profiles) | ❌ | path
default: None (current dir, then HOME dir) | ❌ | `DBT_ENGINE_PROFILES_DIR` | `--profiles-dir` |
| [project\_dir](https://docs.getdbt.tech/reference/dbt_project.yml.md) | ❌ | path
default: (empty) | ❌ | `DBT_ENGINE_PROJECT_DIR` | `--project-dir` |
| [quiet](https://docs.getdbt.tech/reference/global-configs/logs.md#dbt-list-logging) | ✅ | boolean
default: False | ❌ | `DBT_ENGINE_QUIET` | `--quiet` |
| [resource-type](https://docs.getdbt.tech/reference/global-configs/resource-type.md) (v1.8+) | ✅ | string
default: None | ❌ | `DBT_ENGINE_RESOURCE_TYPES`
`DBT_ENGINE_EXCLUDE_RESOURCE_TYPES` | `--resource-type`
`--exclude-resource-type` |
| [sample](https://docs.getdbt.tech/docs/build/sample-flag.md) | ✅ | string
default: None | ❌ | `DBT_ENGINE_SAMPLE` | `--sample` |
| [send\_anonymous\_usage\_stats](https://docs.getdbt.tech/reference/global-configs/usage-stats.md) | ❌ | boolean
default: True | ✅ | `DBT_ENGINE_SEND_ANONYMOUS_USAGE_STATS` | `--send-anonymous-usage-stats`
`--no-send-anonymous-usage-stats` |
| [source\_freshness\_run\_project\_hooks](https://docs.getdbt.tech/reference/global-configs/behavior-flags/source_freshness_run_project_hooks.md) | ❌ | boolean
default: True | ✅ | ❌ | ❌ |
| [sqlparse](https://docs.getdbt.tech/reference/global-configs/sqlparse.md) | ❌ | YAML map
default: MAX\_GROUPING\_DEPTH and MAX\_GROUPING\_TOKENS set to null | ❌ | `DBT_ENGINE_SQLPARSE` | `--sqlparse` |
| [state](https://docs.getdbt.tech/reference/node-selection/defer.md) | ❌ | path
default: none | ❌ | `DBT_ENGINE_STATE`, `DBT_ENGINE_DEFER_STATE` | `--state`
`--defer-state` |
| [static\_parser](https://docs.getdbt.tech/reference/global-configs/parsing.md#static-parser) | ❌ | boolean
default: True | ✅ | `DBT_ENGINE_STATIC_PARSER` | `--static-parser`
`--no-static-parser` |
| [store\_failures](https://docs.getdbt.tech/reference/resource-configs/store_failures.md) | ✅ | boolean
default: False | ✅ (as resource config) | `DBT_ENGINE_STORE_FAILURES` | `--store-failures`
`--no-store-failures` |
| [target\_path](https://docs.getdbt.tech/reference/global-configs/json-artifacts.md) | ❌ | path
default: None (uses `target/`) | ❌ | `DBT_ENGINE_TARGET_PATH` | `--target-path` |
| [target](https://docs.getdbt.tech/docs/local/connection-profiles.md#about-profiles) | ❌ | string
default: None | ❌ | `DBT_ENGINE_TARGET` | [`--target`](https://docs.getdbt.tech/docs/local/connection-profiles.md#overriding-profiles-and-targets) |
| [use\_colors\_file](https://docs.getdbt.tech/reference/global-configs/logs.md#color) | ❌ | boolean
default: True | ✅ | `DBT_ENGINE_USE_COLORS_FILE` | `--use-colors-file`
`--no-use-colors-file` |
| [use\_colors](https://docs.getdbt.tech/reference/global-configs/print-output.md#print-color) | ❌ | boolean
default: True | ✅ | `DBT_ENGINE_USE_COLORS` | `--use-colors`
`--no-use-colors` |
| [use\_experimental\_parser](https://docs.getdbt.tech/reference/global-configs/parsing.md#opt-in-v2-parser) | ❌ | boolean
default: False | ✅ | `DBT_ENGINE_USE_EXPERIMENTAL_PARSER` | `--use-experimental-parser`
`--no-use-experimental-parser` |
| [use\_fast\_test\_edges](https://docs.getdbt.tech/reference/global-configs/fast-test-edges.md) | ✅ | boolean
default: False | ❌ | `DBT_ENGINE_USE_FAST_TEST_EDGES` | `--use-fast-test-edges`
`--no-use-fast-test-edges` |
| [use\_v2\_parser](https://docs.getdbt.tech/reference/global-configs/parsing.md#opt-in-v2-parser) | ✅ | boolean
default: False | ✅ | `DBT_ENGINE_USE_V2_PARSER` | `--use-v2-parser` |
| [version\_check](https://docs.getdbt.tech/reference/global-configs/version-compatibility.md) | ❌ | boolean
default: varies | ✅ | `DBT_ENGINE_VERSION_CHECK` | `--version-check`
`--no-version-check` |
| [warn\_error\_options](https://docs.getdbt.tech/reference/global-configs/warnings.md) | ✅ | dict
default: | ✅ | `DBT_ENGINE_WARN_ERROR_OPTIONS` | `--warn-error-options` |
| [warn\_error](https://docs.getdbt.tech/reference/global-configs/warnings.md) | ✅ | boolean
default: False | ✅ | `DBT_ENGINE_WARN_ERROR` | `--warn-error` |
| [write\_json](https://docs.getdbt.tech/reference/global-configs/json-artifacts.md) | ✅ | boolean
default: True | ✅ | `DBT_ENGINE_WRITE_JSON` | `--write-json`
`--no-write-json` |
### Примеры распространённых флагов
Флаг `--target` задаёт целевую среду для команд dbt. Например:
```bash
dbt run --target dev
dbt run --target prod
dbt build --target staging
```
Флаг `--target` позволяет запускать один проект dbt в разных средах без изменения конфигурационных файлов. Определите целевую среду в `profiles.yml`. Подробнее см. [Профили подключения и целевые среды](https://docs.getdbt.tech/docs/local/profiles.yml.md#%D1%86%D0%B5%D0%BB%D0%B5%D0%B2%D1%8B%D0%B5-%D0%BE%D0%BA%D1%80%D1%83%D0%B6%D0%B5%D0%BD%D0%B8%D1%8F-%D0%B2-%D0%BF%D1%80%D0%BE%D1%84%D0%B8%D0%BB%D1%8F%D1%85).