Обновление до v1.10

Ресурсы

• dbt журнал изменений v1.10
• Установка CLI dbt v1
• Обновление версии dbt на платформе

Что нужно знать перед обновлением

dbt Labs стремится обеспечивать обратную совместимость для всех версий 1.x. Любые изменения поведения будут сопровождаться флагом изменения поведения, чтобы предоставить время для миграции существующих проектов. Если после обновления вы столкнётесь с ошибкой, сообщите нам об этом, создав issue.

dbt предоставляет функциональность новых версий dbt v1 через каналы выпусков с автоматическими обновлениями. Если вы выбрали канал выпусков v1 Latest в dbt, у вас уже есть доступ ко всем возможностям, исправлениям и другим функциям, включённым в dbt v1.10! Если вы выбрали канал выпусков v1 Compatible, вы получите доступ к ним в следующем ежемесячном выпуске v1 Compatible после выхода финальной версии dbt v1.10.

Новые и измененные возможности и функциональность

Новые возможности и функции, доступные в dbt v1.10

Флаг --sample

Большие наборы данных могут существенно замедлять время выполнения сборок dbt, усложняя эффективное тестирование нового кода. Флаг --sample, доступный для команд run и build, помогает сократить время сборки и затраты на хранилище данных, запуская dbt в режиме выборки. Он генерирует отфильтрованные refs и sources с использованием временной выборки, позволяя разработчикам проверять результаты без построения моделей целиком.

Перемещение независимых якорей под ключ anchors:

В рамках непрерывной работы над повышением строгости языка описания dbt dbt v1.10 выводит предупреждение при обнаружении непредусмотренного ключа верхнего уровня в YAML-файле свойств. Часто такие ключи используются для отдельных определений якорей на верхнем уровне YAML-файла свойств. Теперь для размещения этих повторно используемых блоков конфигурации можно использовать новый ключ верхнего уровня anchors:.

Например, вместо следующей конфигурации:

models/_models.yml

id_column: &id_column_alias
  name: id
  description: This is a unique identifier.
  data_type: int
  data_tests:
    - not_null
    - unique

models:
  - name: my_first_model
    columns: 
      - *id_column_alias
      - name: unrelated_column_a
        description: This column is not repeated in other models.
  - name: my_second_model
    columns: 
      - *id_column_alias

Сообщить об ошибке в коде

Следует переместить anchor под ключ anchors::

models/_models.yml

anchors: 
  - &id_column_alias
      name: id
      description: This is a unique identifier.
      data_type: int
      data_tests:
        - not_null
        - unique

models:
  - name: my_first_model
    columns: 
      - *id_column_alias
      - name: unrelated_column_a
        description: This column is not repeated in other models
  - name: my_second_model
    columns: 
      - *id_column_alias

Сообщить об ошибке в коде

Это перемещение необходимо только для фрагментов, определённых вне основной структуры YAML. Подробнее о новом ключе см. в разделе anchors.

Парсинг catalogs.yml

dbt v1 теперь поддерживает разбор файла catalogs.yml. Это важный этап на пути к поддержке внешних каталогов для таблиц Iceberg, поскольку он открывает возможность интеграции для записи данных. Вы сможете указать в конфигурации интеграцию с каталогом для модели, создающей данные:

Например:

catalogs:
  - name: catalog_dave
    # materializing the data to an external location, and metadata to that data catalog
    write_integrations: 
      - name: databricks_glue_write_integration
          external_volume: databricks_external_volume_prod
          table_format: iceberg
          catalog_type: unity 

Сообщить об ошибке в коде

Реализация на стороне модели будет выглядеть так:

models/schemas.yml

models:
  - name: my_second_public_model
    config:
      catalog_name: catalog_dave

Сообщить об ошибке в коде

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

Интеграция артефактов dbt v1 с проектами dbt

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

• Улучшает совместную работу пользователей dbt и dbt v1, позволяя им визуализировать модели, определенные в проектах dbt v1, и создавать межпроектные ссылки на них. Эта функция объединяет рабочие процессы dbt и dbt v1, обеспечивая более тесную интеграцию при работе с dbt.
• Предоставляет пользователям dbt и dbt v1 информацию об их моделях и ресурсах в Catalog. Для просмотра Catalog необходима лицензия разработчика или лицензия с доступом только для чтения.

Гибридные проекты доступны в рамках закрытого бета-тестирования для аккаунтов dbt Enterprise. Свяжитесь с представителем, который ведет ваш аккаунт, чтобы сообщить о своем интересе к участию в бета-тестировании.

Управление изменениями в устаревших поведениях

В dbt v1.10 появились новые флаги для управления изменениями прежнего поведения. Вы можете включить недавно добавленные изменения (по умолчанию отключены) или отключить устоявшиеся изменения (по умолчанию включены), задав соответствующим флагам в разделе flags файла dbt_project.yml значения true или false соответственно.

Подробнее о каждом изменении поведения можно прочитать по следующим ссылкам:

• (Добавлен, отключён по умолчанию) validate_macro_args. Если установлено значение true, dbt выдаёт предупреждение, если имена или типы аргументов в YAML-описании макроса не соответствуют определению макроса на Jinja или используются неподдерживаемые значения типов. Обратите внимание: в проектах, использующих --warn-error, сборка может завершиться ошибкой на этапе разбора, если объявления аргументов макроса в YAML не согласованы с сигнатурой макроса на Jinja.
• (Добавлен, отключён по умолчанию) require_all_warnings_handled_by_warn_error. Если для этого флага установлено значение true, все предупреждения, возникающие во время выполнения, будут направляться в обработчик --warn-error / --warn-error-options. Это обеспечивает единообразное поведение при преобразовании предупреждений в ошибки или их подавлении. Когда флаг имеет значение false (текущее значение по умолчанию), обработчик обрабатывает только часть предупреждений — остальные могут его обходить. Включение этого флага в проектах, использующих --warn-error (или --warn-error-options='{"error":"all"}'), может привести к сбоям сборки из-за предупреждений, которые ранее игнорировались, поэтому мы рекомендуем включать его постепенно, по одному проекту за раз.

Предупреждения об устаревании

Начиная с версии v1.10, вы будете получать предупреждения об устаревании (deprecation warnings) для dbt-кода, который станет недопустимым в будущем, включая:

• Пользовательские входные данные (например, нераспознанные свойства ресурсов, конфигурации и ключи верхнего уровня)
• Дублирующиеся ключи YAML в одном файле
• Неожиданные Jinja-блоки (например, теги {% endmacro %} без соответствующего тега {% macro %})
• Перемещение некоторых properties в configs
• И другое

dbt начнёт выдавать эти предупреждения в версии 1.10, однако внесение изменений не является обязательным условием для её использования. В dbt Labs мы понимаем, что существующим пользователям потребуется время на миграцию проектов, и наша цель — не нарушить вашу работу этим обновлением. Основная цель — дать вам больше безопасности, обратной связи и уверенности в дальнейшей работе.

Что это значит для вас?

1. Если в вашем проекте (или пакете dbt) появляется новое предупреждение об устаревании в v1.10, запланируйте в ближайшее время исправление кода, не соответствующего требованиям. Хотя пока это лишь предупреждение, в будущей версии dbt будет строже проверять входные данные вашего проекта. Воспользуйтесь инструментом dbt-autofix, чтобы автоматически исправить многие из этих проблем!
2. В будущем конфигурация meta станет единственным местом для пользовательских атрибутов. Все остальные атрибуты будут строго типизированы и будут проходить строгую проверку. Если вы хотите добавить в проект дополнительный атрибут или параметр конфигурации модели, к которому нужно обращаться в пользовательской материализации, впредь его необходимо размещать внутри meta.
3. Если вы используете флаг --warn-error (или --warn-error-options '{"error": "all"}'), чтобы считать все предупреждения ошибками, это коснётся и новых предупреждений об устаревании, которые появятся в dbt v1. Если вы не хотите считать их ошибками, флаг --warn-error-options позволяет точнее настроить, какие именно типы предупреждений будут обрабатываться как ошибки. Можно задать "warn": ["Deprecations"] (новая возможность в v1.10), чтобы предупреждения об устаревании по-прежнему обрабатывались как предупреждения.
4. Флаг --models / --model / -m был переименован в --select / --s ещё в dbt v0.21 (октябрь 2021 года). Если молча пропускать этот флаг, критерии выбора в вашей команде будут игнорироваться: в результате может быть построен весь DAG, хотя вы хотели выбрать лишь небольшое подмножество. По этой причине флаг --models / --model / -m будет вызывать предупреждение в dbt v1.10 и ошибку в dbt v2. Обновите определения заданий соответствующим образом.

Пользовательские входные данные

Исторически dbt позволял настраивать входные данные практически без ограничений. Типичный пример — задание пользовательских свойств в YAML:

models:
  - name: my_model
    description: A model in my project.
    dbt_is_awesome: true # пользовательское свойство

Сообщить об ошибке в коде

dbt обнаруживает неизвестное пользовательское свойство (dbt_is_awesome) и продолжает работу без предупреждений. Без строго определённого набора входных параметров проверять конфигурацию проекта становится сложно. Это приводит к непредвиденным проблемам, таким как:

• Игнорирование свойств и параметров конфигурации с опечатками без предупреждений (например, description: вместо description:).
• Непреднамеренные конфликты с пользовательским кодом, когда dbt вводит новое «зарезервированное» свойство или параметр конфигурации.

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

models:
  - name: my_model
    description: A model in my project.
    config:
      meta:
        dbt_is_awesome: true 

Сообщить об ошибке в коде

Пользовательские ключи не вложенные под meta

Ранее возможность определять любые дополнительные поля напрямую под config могла приводить к конфликтам между пользовательскими конфигурациями и официальными конфигурациями фреймворка dbt.

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

models:
  - name: my_model
    config:
      meta:
        custom_config_key: value
    columns:
      - name: my_column
        config:
          meta:
            some_key: some_value

Сообщить об ошибке в коде

Дублирующиеся ключи в одном YAML‑файле

Если в одном properties YAML-файле присутствуют два одинаковых ключа, вы получите предупреждение, а в будущей версии dbt поддержка дублирующихся ключей будет прекращена. Ранее при наличии одинаковых ключей dbt молча перезаписывал значение, используя последнюю конфигурацию в файле.

profiles.yml

my_profile:
  target: my_target
  outputs:
...

my_profile: # dbt would use only this profile key
  target: my_other_target
  outputs:
...

Сообщить об ошибке в коде

В дальнейшем следует удалить неиспользуемые ключи или перенести их в отдельный properties YAML-файл.

Неожиданные Jinja-блоки

Если у вас есть «осиротевший» Jinja-блок, вы получите предупреждение, а в будущей версии dbt поддержка неожиданных Jinja-блоков будет прекращена. Ранее такие блоки молча игнорировались.

macros/my_macro.sql

{% endmacro %} # orphaned endmacro jinja block

{% macro hello() %}
hello!
{% endmacro %}

Сообщить об ошибке в коде

В дальнейшем следует удалить такие осиротевшие Jinja-блоки.

Свойства, перемещённые в конфигурацию

Некоторые исторические properties полностью перемещаются в configs.

К ним относятся: freshness, meta, tags, docs, group и access.

Если ранее вы задавали одно из затронутых свойств, например freshness:

sources: 
  - name: ecom
    schema: raw
    description: E-commerce data for the Jaffle Shop
    freshness:
      warn_after:
        count: 24
        period: hour

Сообщить об ошибке в коде

Теперь его следует задавать внутри config:

sources: 
  - name: ecom
    schema: raw
    description: E-commerce data for the Jaffle Shop
    config:
      freshness:
        warn_after:
          count: 24
          period: hour

Сообщить об ошибке в коде

Пользовательский путь вывода для свежести источника

Возможность переопределять путь по умолчанию для sources.json с помощью флагов --output или -o была признана устаревшей. Вы по-прежнему можете задавать путь для всех artifacts с помощью --target-path, но при попытке указать путь только для source freshness будет выдаваться предупреждение.

Опции warn/error

Опции warn_error_option для include и exclude были признаны устаревшими и заменены на error и warn соответственно.

...
flags:
  warn_error_options:
    error: # Previously called "include"
    warn: # Previously called "exclude"
    silence: # To silence or ignore warnings
      - NoNodesForSelectionCriteria

Сообщить об ошибке в коде

Адаптер-специфичные возможности и функциональность

Изменение размера столбцов в Snowflake

Snowflake планирует увеличить размер столбцов по умолчанию для строковых и двоичных типов данных в сентябре 2026 года. После внедрения этого изменения в версиях dbt-snowflake ниже v1.10.6 могут возникать ошибки при построении некоторых инкрементальных моделей.

 Оценка влияния и необходимые действия

Если вы используете версию dbt-snowflake ниже v1.10.6 или ещё не перешли на канал выпуска в dbt platform, ваша версия адаптера несовместима с этим изменением. Это может приводить к ошибкам при построении инкрементальных моделей, которые соответствуют обоим следующим условиям:

• Содержат строковые столбцы с заданными правилами сортировки (collation)
• Используют настройку on_schema_change='sync_all_columns'

Чтобы проверить, затрагивает ли это изменение ваш проект, выполните следующую команду list:

dbt ls -s config.materialized:incremental,config.on_schema_change:sync_all_columns --resource-type model

Сообщить об ошибке в коде

• Если команда возвращает No nodes selected!, никаких действий не требуется.

• Если команда возвращает одну или несколько моделей (например, Found 1000 models, 644 macros), изменение может затронуть вас, если в этих моделях есть строковые столбцы без явно указанной длины. В этом случае обновитесь до версии, содержащей исправление:

  • dbt v1: dbt-snowflake v1.10.6 или более поздняя версия. Указания по обновлению приведены в разделе Обновление адаптеров инструкции по установке dbt v1.
  • dbt platform: любой канал выпуска (v1 Latest, v1 Compatible, v1 Extended или v1 Fallback).
  • dbt v2: v2.0.0.

  Это позволит вашим инкрементальным моделям корректно обрабатывать изменения схемы, сохраняя необходимые настройки правил сортировки.

Snowflake

• С помощью параметра platform_detection_timeout_seconds можно задать время ожидания коннектора Snowflake при определении облачной платформы, из которой устанавливается подключение. Подробнее см. в разделе Настройка Snowflake.

BigQuery

• dbt-bigquery отправляет запрос на отмену заданий BigQuery, время выполнения которых превышает настроенный тайм-аут. Если запрос выполнен успешно, dbt останавливает задание. Если запрос не выполнен, задание BigQuery может продолжать выполняться в фоновом режиме, пока не завершится или вы не отмените его вручную. Подробнее см. в разделе Тайм-ауты и повторные попытки.

Коротко о главном

• Используйте флаг --use-fast-test-edges с командой dbt build, чтобы уменьшить количество рёбер тестов, которые dbt добавляет в граф выполнения. В крупных проектах это может значительно сократить время выполнения и потребление памяти.

• Укажите свойство loaded_at_query для проверки актуальности источника, чтобы задать пользовательский SQL-запрос для получения временной метки maxLoadedAt в источнике (вместо встроенного запроса, который использует loaded_at_field). Нельзя задавать loaded_at_query, если также указан параметр конфигурации loaded_at_field.

• Включите проверку аргументов макросов с помощью флага validate_macro_args, который по умолчанию отключён. Когда этот флаг включён, он проверяет, совпадают ли имена аргументов макроса в документации с именами в определении макроса, а также соответствуют ли их типы поддерживаемому формату. Ранее dbt не требовал соблюдения стандартных типов аргументов и рассматривал поле типа исключительно как документацию. Если ни один аргумент не описан в документации, dbt определяет аргументы по определению макроса и включает их в файл manifest.json. Подробнее см. в разделе Поддерживаемые типы.

• Вы можете использовать функции config.meta_get() и config.meta_require() для доступа к пользовательским настройкам, хранящимся в meta.

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

Создать GitHub Issue