Изменения в поведении

Большинство флагов существуют для настройки поведения во время выполнения с несколькими допустимыми вариантами. Правильный выбор может варьироваться в зависимости от среды, предпочтений пользователя или конкретного вызова.

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

Предоставления лучшего, более разумного и более последовательного поведения по умолчанию для новых пользователей/проектов.
Предоставления окна для миграции существующих пользователей/проектов — ничего не меняется в одночасье без предупреждения.
Обеспечения поддерживаемости программного обеспечения dbt. Каждое разветвление в поведении требует дополнительного тестирования и когнитивной нагрузки, что замедляет будущее развитие. Эти флаги существуют для облегчения миграции от "текущего" к "лучшему", а не для того, чтобы оставаться навсегда.

Эти флаги проходят три фазы разработки:

Введение (по умолчанию отключено): dbt добавляет логику для поддержки как "старого", так и "нового" поведения. "Новое" поведение ограничено флагом, который по умолчанию отключен, сохраняя старое поведение.
Зрелость (по умолчанию включено): Значение флага по умолчанию переключается с false на true, включая новое поведение по умолчанию. Пользователи могут сохранить "старое" поведение и отказаться от "нового" поведения, установив флаг в false в своих проектах. При этом они могут видеть предупреждения о прекращении поддержки.
Удаление (обычно включено): После пометки флага как устаревшего мы удаляем его вместе с поддерживаемым им "старым" поведением из кодовой базы dbt. Мы стремимся поддерживать большинство флагов на неопределенный срок, но не обязуемся поддерживать их вечно. Если мы решим удалить флаг, мы предоставим значительное предварительное уведомление.

Что такое изменение в поведении?

Один и тот же код проекта dbt и одни и те же команды dbt возвращают один результат до изменения в поведении и другой результат после изменения в поведении.

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

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

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

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

Подавляющее большинство изменений не являются изменениями в поведении. Поскольку введение этих изменений не требует никаких действий со стороны пользователей, они включены в непрерывные выпуски dbt Cloud и патч-выпуски dbt Core.

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

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

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

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

Решите проблему (переключив флаг на True)
Заглушите предупреждения, используя флаг warn_error_options.silence

Вот пример доступных флагов изменений в поведении с их значениями по умолчанию:

dbt_project.yml

flags:
  require_explicit_package_overrides_for_builtin_materializations: False
  require_model_names_without_spaces: False
  source_freshness_run_project_hooks: False
  restrict_direct_pg_catalog_access: False
  require_yaml_configuration_for_mf_time_spines: False
  require_batched_execution_for_custom_microbatch_strategy: False

Эта таблица описывает, какой месяц в треке "Latest" в dbt Cloud и какая версия dbt Core содержит введение изменения в поведении (по умолчанию отключено) или зрелость (по умолчанию включено).

Флаг	dbt Cloud "Latest": Введение	dbt Cloud "Latest": Зрелость	dbt Core: Введение	dbt Core: Зрелость
require_explicit_package_overrides_for_builtin_materializations	2024.04	2024.06	1.6.14, 1.7.14	1.8.0
require_resource_names_without_spaces	2024.05	TBD*	1.8.0	1.10.0
source_freshness_run_project_hooks	2024.03	TBD*	1.8.0	1.10.0
[Redshift] restrict_direct_pg_catalog_access	2024.09	TBD*	dbt-redshift v1.9.0	1.9.0
skip_nodes_if_on_run_start_fails	2024.10	TBD*	1.9.0	TBD*
state_modified_compare_more_unrendered_values	2024.10	TBD*	1.9.0	TBD*
require_yaml_configuration_for_mf_time_spines	2024.10	TBD*	1.9.0	TBD*
require_batched_execution_for_custom_microbatch_strategy	2024.11	TBD*	1.9.0	TBD*
cumulative_type_params	2024.11	TBD*	1.9.0	TBD*

Когда dbt Cloud Зрелость указана как "TBD", это означает, что мы еще не определили точную дату, когда значения по умолчанию для этих флагов изменятся. Затронутые пользователи увидят предупреждения о прекращении поддержки, и они получат электронные письма с предварительным уведомлением перед датой зрелости. В это время, если вы видите предупреждение о прекращении поддержки, вы можете либо:

Мигрировать ваш проект для поддержки нового поведения, а затем установить флаг в True, чтобы прекратить видеть предупреждения.
Установить флаг в False. Вы продолжите видеть предупреждения и сохраните устаревшее поведение даже после даты зрелости (когда значение по умолчанию изменится).

Ошибки в хуках on-run-start

Флаг по умолчанию установлен в False.

Установите флаг skip_nodes_if_on_run_start_fails в True, чтобы пропустить выполнение всех выбранных ресурсов, если произошла ошибка в хуке on-run-start.

Определения источников для state:modified

к сведению

Вам необходимо создать каталог состояния, используя dbt версии 1.9 или выше, или текущую версию dbt Cloud "Latest", и установить параметр state_modified_compare_more_unrendered_values в значение true в вашем файле dbt_project.yml.

Если каталог состояния был создан с использованием более старой версии dbt или если флаг изменения поведения state_modified_compare_more_unrendered_values не был установлен или был установлен в значение false, вам необходимо пересоздать каталог состояния, чтобы избежать ложных срабатываний при сравнении состояния с state:modified.

Флаг по умолчанию установлен в False.

Установите state_modified_compare_more_unrendered_values в True, чтобы уменьшить количество ложных срабатываний во время проверок state:modified (особенно когда конфигурации различаются в зависимости от целевой среды, например, prod против dev).

Установка флага в True изменяет сравнение state:modified с использованием неотрендеренных значений вместо отрендеренных. Это достигается за счет сохранения unrendered_config во время парсинга модели и конфигураций unrendered_database и unrendered_schema во время парсинга источника.

Переопределение пакета для встроенной материализации

Установка флага require_explicit_package_overrides_for_builtin_materializations в True предотвращает это автоматическое переопределение.

Мы прекратили поддержку поведения, при котором установленные пакеты могли переопределять встроенные материализации без вашего явного согласия. Когда этот флаг установлен в True, материализация, определенная в пакете, которая совпадает с именем встроенной материализации, больше не будет включена в порядок поиска и разрешения. В отличие от макросов, материализации не используют search_order, определенный в конфигурации проекта dispatch.

Встроенные материализации включают 'view', 'table', 'incremental', 'materialized_view' для моделей, а также 'test', 'unit', 'snapshot', 'seed' и 'clone'.

Вы все еще можете явно переопределить встроенные материализации в пользу материализации, определенной в пакете, переосуществив встроенную материализацию в вашем корневом проекте и обернув реализацию пакета.

macros/materialization_view.sql

{% materialization view, snowflake %}
  {{ return(my_installed_package_name.materialization_view_snowflake()) }}
{% endmaterialization %}

В будущем мы можем расширить конфигурацию dispatch на уровне проекта, чтобы поддерживать список авторизованных пакетов для переопределения встроенной материализации.

Отсутствие пробелов в именах ресурсов

Флаг require_resource_names_without_spaces требует использования имен ресурсов без пробелов.

Имена ресурсов dbt (модели, источники и т.д.) должны содержать буквы, цифры и подчеркивания. Мы настоятельно не рекомендуем использовать другие символы, особенно пробелы. В этой связи мы прекратили поддержку пробелов в именах ресурсов. Когда флаг require_resource_names_without_spaces установлен в True, dbt будет выдавать исключение (вместо предупреждения о прекращении поддержки), если обнаружит пробел в имени ресурса.

models/model name with spaces.sql

-- Этот файл модели следует переименовать в model_name_with_underscores.sql

Проектные хуки с актуальностью источников

Установите флаг source_freshness_run_project_hooks в True, чтобы включить "проектные хуки" (on-run-start / on-run-end) в выполнение команды dbt source freshness.

Если у вас есть определенные проектные хуки on-run-start / on-run-end, которые не должны выполняться до/после команды source freshness, вы можете добавить условную проверку в эти хуки:

dbt_project.yml

on-run-start:
  - '{{ ... if flags.WHICH != 'freshness' }}'

YAML для временной оси MetricFlow

Флаг require_yaml_configuration_for_mf_time_spines по умолчанию установлен в False.

В предыдущих версиях (dbt Core 1.8 и ранее) конфигурация временной оси MetricFlow хранилась в файле metricflow_time_spine.sql.

Когда флаг установлен в True, dbt продолжит поддерживать конфигурацию SQL файла. Когда флаг установлен в False, dbt будет выдавать предупреждение о прекращении поддержки, если обнаружит временную ось MetricFlow, настроенную в SQL файле.

Файл YAML для MetricFlow должен содержать поле time_spine:. Обратитесь к временной оси MetricFlow для получения более подробной информации.

Стратегия пользовательских микропакетов

Флаг require_batched_execution_for_custom_microbatch_strategy по умолчанию установлен в False и актуален только в том случае, если у вас уже есть пользовательский макрос микропакетов в вашем проекте. Если у вас нет пользовательского макроса микропакетов, вам не нужно устанавливать этот флаг, так как dbt будет автоматически обрабатывать микропакетирование для любой модели, использующей стратегию микропакетов.

Установите флаг в True, если у вас настроен пользовательский макрос микропакетов в вашем проекте. Когда флаг установлен в True, dbt будет выполнять пользовательскую стратегию микропакетов пакетами.

Если у вас есть пользовательский макрос микропакетов и флаг оставлен в False, dbt выдаст предупреждение о прекращении поддержки.

Ранее пользователям нужно было устанавливать переменную окружения DBT_EXPERIMENTAL_MICROBATCH в True, чтобы предотвратить непреднамеренные взаимодействия с существующими пользовательскими стратегиями инкрементального обновления. Но это больше не требуется, так как установка DBT_EXPERMINENTAL_MICROBATCH больше не будет влиять на функциональность во время выполнения.

Кумулятивные метрики

Кумулятивные метрики вложены в поле cumulative_type_params в треке "Latest" выпуска dbt Cloud, dbt Core v1.9 и новее. В настоящее время dbt будет предупреждать пользователей, если у них неправильно вложены кумулятивные метрики. Чтобы применить новый формат (что приведет к ошибке вместо предупреждения), установите require_nested_cumulative_type_params в True.

Используйте следующую метрику, настроенную с синтаксисом до v1.9, в качестве примера:

    type: cumulative
    type_params:
      measure: order_count
      window: 7 days

Если вы выполните dbt parse с этим синтаксисом на Core v1.9 или треке "Latest" выпуска dbt Cloud, вы получите предупреждение, подобное следующему:

15:36:22  [WARNING]: Кумулятивные поля `type_params.window` и
`type_params.grain_to_date` были перемещены и вскоре будут устаревшими. Пожалуйста,
вложите эти значения под `type_params.cumulative_type_params.window` и
`type_params.cumulative_type_params.grain_to_date`. См. документацию по
изменениям в поведении:
https://docs.getdbt.com/reference/global-configs/behavior-changes.

Если вы установите require_nested_cumulative_type_params в True и повторно выполните dbt parse, вы получите ошибку, подобную следующей:

21:39:18  Кумулятивные поля `type_params.window` и `type_params.grain_to_date` должны быть вложены под `type_params.cumulative_type_params.window` и `type_params.cumulative_type_params.grain_to_date`. Неверные метрики: orders_last_7_days. См. документацию по изменениям в поведении: https://docs.getdbt.com/reference/global-configs/behavior-changes.

После обновления метрики она будет работать как ожидалось:

    type: cumulative
    type_params:
      measure:
        name: order_count
      cumulative_type_params:
        window: 7 days

Что такое изменение в поведении?​

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

Ошибки в хуках on-run-start​

Определения источников для state:modified​

Переопределение пакета для встроенной материализации​

Отсутствие пробелов в именах ресурсов​

Проектные хуки с актуальностью источников​

YAML для временной оси MetricFlow​

Стратегия пользовательских микропакетов​

Кумулятивные метрики​