Перейти к основному содержимому

Об изменениях поведения

Изменение поведения — это намеренное обновление dbt, после которого тот же код проекта и те же команды дают другой результат. Например, появляется новая ошибка валидации, меняется сигнатура макроса или нарушается совместимость артефактов или структурированных журналов. Исправления ошибок, новые предупреждения и обратно совместимые дополнения к таким изменениям не относятся.

dbt вводит эти изменения с помощью флагов изменения поведения, чтобы вы могли сами решать, когда переходить на новое поведение.

Примеры изменений поведения:

  • dbt начинает выдавать ошибку валидации, которую раньше не выдавал.
  • dbt изменяет сигнатуру встроенного макроса. В вашем проекте есть собственная реализация этого макроса. Это может привести к ошибкам, поскольку в вашу реализацию будут передаваться аргументы, которые она не может принять.
  • Адаптер dbt переименовывает или удаляет метод, который ранее был доступен у объекта {{ adapter }} в контексте dbt-Jinja.

Следующие изменения не считаются изменениями поведения:

  • Исправление ошибки, из-за которой прежнее поведение было некорректным, нежелательным или недокументированным.
  • dbt начинает выдавать предупреждение, которое раньше не выдавал.
  • dbt обновляет формулировки сообщений для пользователей в событиях журнала.

Флаги изменений в поведении​

Эти флаги должны быть установлены в словаре flags в dbt_project.yml. Они настраивают поведение, тесно связанное с кодом проекта, что означает, что они должны быть определены в системе контроля версий и изменены через pull или merge запросы с тем же тестированием и рецензированием.

Жизненный цикл флагов​

Флаги изменения поведения проходят три этапа развития:

  1. Введение (отключён по умолчанию): dbt добавляет логику для поддержки как «старого», так и «нового» поведения. «Новое» поведение управляется флагом, который по умолчанию отключён, что сохраняет старое поведение.
  2. Зрелость (включён по умолчанию): Значение флага по умолчанию меняется, и новое поведение становится поведением по умолчанию. Вы по-прежнему можете сохранить старое поведение, но при этом могут появляться предупреждения о прекращении его поддержки.
  3. Удаление (новое поведение включено всегда): Старое поведение удаляется из кодовой базы dbt. Большинство флагов поддерживаются бессрочно, но обязательств поддерживать их вечно нет. Об удалении флага будет объявлено заблаговременно.

Введены в dbt v1​

В этой таблице указано, в каком месяце в канале выпусков v1 Latest в dbt и в какой версии dbt v1 изменение поведения было введено (отключено по умолчанию) или достигло зрелости (включено по умолчанию). Флаги, отмеченные значением 2.0 в столбце Удаление, удалены в dbt v2, и новое поведение включено всегда.

Флагv1 Latest: Введениеv1 Latest: Зрелостьdbt v1: Введениеdbt v1: ЗрелостьУдаление
require_explicit_package_overrides_for_builtin_materializations2024.042024.061.6.14, 1.7.141.8.02.0
require_resource_names_without_spaces2024.052025.051.8.01.10.02.0
source_freshness_run_project_hooks2024.032025.051.8.01.10.02.0
skip_nodes_if_on_run_start_fails2024.102026.091.9.01.12.02.0
state_modified_compare_more_unrendered_values2024.102026.091.9.01.12.02.0
require_yaml_configuration_for_mf_time_spines2024.102026.091.9.01.12.02.0
require_batched_execution_for_custom_microbatch_strategy2024.112026.091.9.01.12.02.0
require_nested_cumulative_type_params2024.112026.091.9.01.12.02.0
enable_truthy_nulls_equals_macro2025.02-1.9.0--
validate_macro_args2025.032026.091.10.01.12.0-
require_all_warnings_handled_by_warn_error2025.062026.091.10.01.12.0-
require_generic_test_arguments_property2025.072025.081.10.51.10.8-
require_unique_project_resource_names2025.12-1.11.0--
require_ref_searches_node_package_before_root2025.12-1.11.0--
require_valid_schema_from_generate_schema_name2026.1-1.12.0a1--
require_sql_header_in_test_configs2026.3-1.12.0--
require_corrected_analysis_fqns2026.3-1.12.0--
require_source_and_semantic_model_names_without_spaces2026.4-1.12.0--
allow_jinja_file_extensions2026.5-1.12.0--
latest_version_pointer_enabled_by_default2026.5-1.12.0--

Введены в dbt v2​

Следующие флаги предназначены только для dbt v2 и не имеют аналогов в dbt v1. Они настраиваются так же — в блоке flags: файла dbt_project.yml.

ФлагАдаптерЗначение по умолчаниюВведениеСтановится значением по умолчанию
require_resource_names_without_plus_prefixВсеfalse2.0.0-preview.208Пока не определено
use_catalogs_v2Всеtrue2.0.0-preview.1742.0.0
bigquery_noop_alter_relation_commentBigQueryfalse2.0.0-preview.124Пока не определено

Флаги изменения поведения для отдельных адаптеров​

В этой таблице указано, в какой версии адаптера dbt изменение поведения было введено (отключено по умолчанию) или достигло зрелости (включено по умолчанию). Флаги, отмеченные значением 2.0 в столбце Удаление, удалены в dbt v2, и новое поведение включено всегда.

Флагdbt-ADAPTER: Введениеdbt-ADAPTER: ЗрелостьУдаление
use_info_schema_for_columnsDatabricks 1.9.0-2.0
use_user_folder_for_pythonDatabricks 1.9.0-2.0
use_managed_icebergDatabricks 1.11.01.12.0-
use_materialization_v2Databricks 1.10.0--
use_replace_on_for_insert_overwriteDatabricks 1.11.01.11.0-
use_describe_as_json_for_relation_metadataDatabricks 1.12.0--
redshift_skip_autocommit_transaction_statementsRedshift 1.12.0--
bigquery_use_batch_source_freshnessBigQuery 1.11.0rc2--
bigquery_reject_wildcard_metadata_source_freshnessBigQuery 1.12.0--
bigquery_use_standard_sql_for_partitionsBigQuery 1.12.01.12.0-
snowflake_default_transient_dynamic_tablesSnowflake 1.12.0--

Часто задаваемые вопросы​

 Как настроить флаги изменения поведения в моём проекте?

В следующем примере показаны текущие флаги и их текущие значения по умолчанию в последних версиях dbt и dbt v1. Чтобы отказаться от определённого изменения поведения, задайте для соответствующего флага значение false в dbt_project.yml. Предупреждения об использовании устаревшего поведения, сохранённого при отказе от изменений, будут появляться до тех пор, пока вы не выполните одно из следующих действий:

  • Устраните проблему (переключив флаг на true)
  • Отключите предупреждения с помощью флага warn_error_options.silence
dbt_project.yml
flags:
require_explicit_package_overrides_for_builtin_materializations: true
require_resource_names_without_spaces: true
source_freshness_run_project_hooks: true
skip_nodes_if_on_run_start_fails: true
state_modified_compare_more_unrendered_values: true
require_yaml_configuration_for_mf_time_spines: true
require_batched_execution_for_custom_microbatch_strategy: true
require_nested_cumulative_type_params: true
validate_macro_args: true
require_all_warnings_handled_by_warn_error: true
require_generic_test_arguments_property: true
require_unique_project_resource_names: false
require_ref_searches_node_package_before_root: false
require_valid_schema_from_generate_schema_name: false
enable_truthy_nulls_equals_macro: false
require_sql_header_in_test_configs: false
require_corrected_analysis_fqns: false
require_source_and_semantic_model_names_without_spaces: false
allow_jinja_file_extensions: false
latest_version_pointer_enabled_by_default: false
 Что означает отсутствие даты погашения?

Если дата вступления в силу ещё не назначена (в таблице стоит прочерк), точная дата смены значения флага по умолчанию пока неизвестна. До этого пользователи будут видеть предупреждения об устаревании и заранее получат уведомление по электронной почте. Если вы видите такое предупреждение, можно:

  • Обновить проект для работы с новым поведением и установить флаг в true, чтобы отключить предупреждения.
  • Явно установить флаг в false. Предупреждения останутся, но прежнее поведение сохранится даже после смены значения флага по умолчанию.
 Чем флаги изменения поведения отличаются от других изменений?

Флаги изменения поведения следует отличать от других изменений dbt:

  • Предупреждения об устаревании сообщают о конструкциях в коде проекта, которые перестанут работать. Флаги поведения часто определяют, когда такие предупреждения станут ошибками.
  • Устаревшие флаги CLI — параметры командной строки, которые удаляются в v2.

Краткое сравнение приведено в разделе Обзор изменений.

Если вы переходите на v2, некоторые флаги изменения поведения удалены, а соответствующее им новое поведение всегда включено.

Нашли ошибку?

0
Loading