О флагах (глобальные конфигурации)
В dbt «флаги» (также называемые «глобальными настройками» и часто задаваемые с помощью переменных окружения) — это настройки для точного управления тем, как dbt выполняет ваш проект. Они отличаются от настроек отдельных ресурсов, которые указывают dbt, что выполнять.
Флаги управляют такими вещами, как визуальный вывод логов, следует ли рассматривать определенные предупреждения как ошибки, или следует ли "быстро завершать" выполнение после первой ошибки. Флаги являются "глобальными" конфигурациями, потому что они доступны для всех команд dbt и могут быть установлены в нескольких местах.
Вы можете использовать флаги с движком dbt v2 или dbt v1 через CLI при локальной разработке или в dbt platform.
Флаги dbt и параметры командной строки dbt во многом пересекаются, но между ними есть различия:
- Некоторые флаги можно задать только в
dbt_project.yml, и их нельзя переопределить для отдельных запусков с помощью параметров CLI. - Если параметр CLI поддерживается только определёнными командами, а не всеми командами (то есть не является «глобальным»), он обычно не считается «флагом».
Вы можете настраивать флаги в dbt_project.yml, с помощью переменных окружения и параметров CLI. Подробности см. в разделе Настройка с помощью переменных окружения.
Настройка флагов
Существует несколько способов настройки флагов в зависимости от сценария использования:
- Параметры CLI: Определяют поведение для конкретного вызова. Поддерживаются для всех команд dbt.
- Переменные окружения: Определяют различное поведение в разных средах выполнения (разработка, промышленная эксплуатация или непрерывная интеграция) или для разных пользователей в среде разработки (на основе личных предпочтений).
- Флаги
flagsна уровне проекта вdbt_project.yml: Определяют значения по умолчанию, хранящиеся в системе контроля версий, для всех, кто запускает этот проект. Также позволяют включать или отключать изменения поведения, чтобы управлять переходом с устаревшей функциональности. - Пользовательские настройки (
~/.dbt/user_settings.yml): Определяют личные предпочтения, которые применяются ко всем проектам на вашем компьютере. Записываются автоматически командойdbt login.
Наиболее конкретная настройка имеет приоритет. Наивысший приоритет имеют параметры CLI, затем идут переменные окружения, далее — dbt_project.yml и, наконец, user_settings.yml. Если флаг не задан ни в одном из этих мест, используется значение по умолчанию, определённое в dbt.
# dbt_project.yml
flags:
# значение по умолчанию для запуска этого проекта — везде, всегда, для всех
fail_fast: true
# установите для этой переменной окружения значение 'True' (синтаксис bash)
export DBT_ENGINE_FAIL_FAST=1
dbt run
dbt run --fail-fast # установить True для этого конкретного запуска
dbt run --no-fail-fast # установить False
Есть две категории исключений:
- Флаги, задающие пути к файлам: Флаги для путей к файлам, используемых во время выполнения (например,
--log-pathили--state), нельзя задавать вdbt_project.yml. Чтобы переопределить значения по умолчанию, передайте параметры CLI или задайте переменные окружения ((Версии dbt: v1.11 и новее)DBT_ENGINE_LOG_PATHиDBT_ENGINE_STATE). Флаги, указывающие dbt, где искать ресурсы проекта (например,model-paths), задаются вdbt_project.yml, но в виде ключей верхнего уровня, вне словаряflags; эти настройки должны быть полностью статичными и никогда не меняться в зависимости от команды или среды выполнения. - Флаги включения изменений поведения: Флаги, включающие или отключающие изменения поведения, можно задавать только в
dbt_project.yml. Предполагается, что они задаются в системе контроля версий и изменяются через запросы на слияние (pull/merge request). Их значения не должны оставаться различными для разных запусков, сред или пользователей в течение неопределённо долгого времени.
Доступ к флагам
Пользовательская логика, написанная на Jinja, может проверять значения флагов, используя контекстную переменную flags.
# dbt_project.yml
on-run-start:
- '{{ log("Я остановлюсь при первом признаке проблемы", info = true) if flags.FAIL_FAST }}'
Доступные флаги
Поскольку значения flags могут различаться от запуска к запуску, мы настоятельно рекомендуем не использовать flags в качестве входных данных для конфигураций или зависимостей (ref + source), которые dbt разрешает во время разбора.
Используйте эту таблицу для сравнения всех доступных флагов и способов их настройки через различные интерфейсы:
- CLI dbt: Указывает, поддерживается ли флаг в CLI, поддерживаемом dbt platform.
- Тип / значение по умолчанию: Показывает допустимый тип значения и значение по умолчанию.
- В проекте: Указывает, можно ли задать флаг в
dbt_project.yml. - Переменная окружения: Показывает имя соответствующей переменной окружения, если она доступна. Как правило, в версии v1.10 и более ранних используется префикс
DBT_, а в v1.11 и более поздних — префиксDBT_ENGINE_. - Флаги CLI: Перечисляет параметры командной строки для задания флага на конкретный запуск.
| Flag | dbt CLI? | Type / default | In project? | Env var | CLI flags |
|---|---|---|---|---|---|
| ai_provider (v2.0+) | ❌ | list default: None | ✅ | DBT_ENGINE_AI_PROVIDER | --ai-provider |
| batch_tests (v2.0+) | ❌ | boolean default: False | ✅ | DBT_ENGINE_BATCH_TESTS | --batch-tests |
| cache_selected_only | ✅ | boolean default: False | ✅ | DBT_ENGINE_CACHE_SELECTED_ONLY | --cache-selected-only --no-cache-selected-only |
| clean_project_files_only | ❌ | boolean default: True | ❌ | DBT_ENGINE_CLEAN_PROJECT_FILES_ONLY | --clean-project-files-only --no-clean-project-files-only |
| debug | ✅ | boolean default: False | ✅ | DBT_ENGINE_DEBUG | --debug --no-debug |
| defer | ✅ (default) | boolean default: False | ❌ | DBT_ENGINE_DEFER | --defer --no-defer |
| defer_state | ❌ | path default: None | ❌ | DBT_ENGINE_DEFER_STATE | --defer-state |
| favor_state | ✅ | boolean default: False | ❌ | DBT_ENGINE_FAVOR_STATE | --favor-state --no-favor-state |
| empty | ✅ | boolean default: False | ❌ | DBT_ENGINE_EMPTY | --empty --no-empty |
| event_time_start | ✅ | datetime default: None | ❌ | DBT_ENGINE_EVENT_TIME_START | --event-time-start |
| event_time_end | ✅ | datetime default: None | ❌ | DBT_ENGINE_EVENT_TIME_END | --event-time-end |
| fail_fast | ✅ | boolean default: False | ✅ | DBT_ENGINE_FAIL_FAST | --fail-fast -x --no-fail-fast |
| full_refresh | ✅ | boolean default: False | ✅ (as resource config) | DBT_ENGINE_FULL_REFRESH | --full-refresh --no-full-refresh |
| generate_info_schema (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 | ❌ | enum default: eager | ✅ | DBT_ENGINE_INDIRECT_SELECTION | --indirect-selection |
| info_schema_dir (v2.0+) | ✅ | path default: None (uses <target>/info_schema/) | ❌ | DBT_ENGINE_INFO_SCHEMA_DIR | --info-schema-dir |
| introspect | ❌ | boolean default: True | ❌ | DBT_ENGINE_INTROSPECT | --introspect --no-introspect |
| log_cache_events | ❌ | boolean default: False | ❌ | DBT_ENGINE_LOG_CACHE_EVENTS | --log-cache-events --no-log-cache-events |
| log_format_file | ❌ | enum default: default (text) | ✅ | DBT_ENGINE_LOG_FORMAT_FILE | --log-format-file |
| log_format | ❌ | enum default: default (text) | ✅ | DBT_ENGINE_LOG_FORMAT | --log-format |
| log_level_file | ❌ | enum default: debug | ✅ | DBT_ENGINE_LOG_LEVEL_FILE | --log-level-file |
| log_level | ❌ | enum default: info | ✅ | DBT_ENGINE_LOG_LEVEL | --log-level |
| log_path | ❌ | path default: None (uses logs/) | ❌ | DBT_ENGINE_LOG_PATH | --log-path |
| manage_state (v1.13+) | ✅ | boolean default: False | ✅ | DBT_ENGINE_MANAGE_STATE | --manage-state --no-manage-state |
| partial_parse | ✅ | boolean default: True | ✅ | DBT_ENGINE_PARTIAL_PARSE | --partial-parse --no-partial-parse |
| populate_cache | ✅ | boolean default: True | ✅ | DBT_ENGINE_POPULATE_CACHE | --populate-cache --no-populate-cache |
| ❌ | boolean default: True | ❌ | DBT_ENGINE_PRINT | --print --no-print | |
| printer_width | ❌ | int default: 80 | ✅ | DBT_ENGINE_PRINTER_WIDTH | --printer-width |
| profile | ❌ | string default: None | ✅ (as top-level key) | DBT_ENGINE_PROFILE | --profile |
| profiles_dir | ❌ | path default: None (current dir, then HOME dir) | ❌ | DBT_ENGINE_PROFILES_DIR | --profiles-dir |
| project_dir | ❌ | path default: (empty) | ❌ | DBT_ENGINE_PROJECT_DIR | --project-dir |
| quiet | ✅ | boolean default: False | ❌ | DBT_ENGINE_QUIET | --quiet |
| resource-type (v1.8+) | ✅ | string default: None | ❌ | DBT_ENGINE_RESOURCE_TYPES DBT_ENGINE_EXCLUDE_RESOURCE_TYPES | --resource-type --exclude-resource-type |
| sample | ✅ | string default: None | ❌ | DBT_ENGINE_SAMPLE | --sample |
| send_anonymous_usage_stats | ❌ | boolean default: True | ✅ | DBT_ENGINE_SEND_ANONYMOUS_USAGE_STATS | --send-anonymous-usage-stats --no-send-anonymous-usage-stats |
| source_freshness_run_project_hooks | ❌ | boolean default: True | ✅ | ❌ | ❌ |
| sqlparse | ❌ | YAML map default: MAX_GROUPING_DEPTH and MAX_GROUPING_TOKENS set to null | ❌ | DBT_ENGINE_SQLPARSE | --sqlparse |
| state | ❌ | path default: none | ❌ | DBT_ENGINE_STATE, DBT_ENGINE_DEFER_STATE | --state --defer-state |
| static_parser | ❌ | boolean default: True | ✅ | DBT_ENGINE_STATIC_PARSER | --static-parser --no-static-parser |
| store_failures | ✅ | boolean default: False | ✅ (as resource config) | DBT_ENGINE_STORE_FAILURES | --store-failures --no-store-failures |
| target_path | ❌ | path default: None (uses target/) | ❌ | DBT_ENGINE_TARGET_PATH | --target-path |
| target | ❌ | string default: None | ❌ | DBT_ENGINE_TARGET | --target |
| use_colors_file | ❌ | boolean default: True | ✅ | DBT_ENGINE_USE_COLORS_FILE | --use-colors-file --no-use-colors-file |
| use_colors | ❌ | boolean default: True | ✅ | DBT_ENGINE_USE_COLORS | --use-colors --no-use-colors |
| use_experimental_parser | ❌ | boolean default: False | ✅ | DBT_ENGINE_USE_EXPERIMENTAL_PARSER | --use-experimental-parser --no-use-experimental-parser |
| use_fast_test_edges | ✅ | boolean default: False | ❌ | DBT_ENGINE_USE_FAST_TEST_EDGES | --use-fast-test-edges --no-use-fast-test-edges |
| use_v2_parser | ✅ | boolean default: False | ✅ | DBT_ENGINE_USE_V2_PARSER | --use-v2-parser |
| version_check | ❌ | boolean default: varies | ✅ | DBT_ENGINE_VERSION_CHECK | --version-check --no-version-check |
| warn_error_options | ✅ | dict default: | ✅ | DBT_ENGINE_WARN_ERROR_OPTIONS | --warn-error-options |
| warn_error | ✅ | boolean default: False | ✅ | DBT_ENGINE_WARN_ERROR | --warn-error |
| write_json | ✅ | boolean default: True | ✅ | DBT_ENGINE_WRITE_JSON | --write-json --no-write-json |
Примеры распространённых флагов
Флаг --target задаёт целевую среду для команд dbt. Например:
dbt run --target dev
dbt run --target prod
dbt build --target staging
Флаг --target позволяет запускать один проект dbt в разных средах без изменения конфигурационных файлов. Определите целевую среду в profiles.yml. Подробнее см. Профили подключения и целевые среды.
