# Обновление до v1.10 Доступно в v1 ## Ресурсы * dbt [журнал изменений v1.10](https://github.com/dbt-labs/dbt/blob/1.10.latest/CHANGELOG.md) * [Установка CLI dbt v1](https://docs.getdbt.tech/docs/local/install-dbt.md) * [Обновление версии dbt на платформе](https://docs.getdbt.tech/docs/dbt-versions/upgrade-dbt-platform-version.md) ## Что нужно знать перед обновлением dbt Labs стремится обеспечивать обратную совместимость для всех версий 1.x. Любые изменения поведения будут сопровождаться [флагом изменения поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md#behavior-change-flags), чтобы предоставить время для миграции существующих проектов. Если после обновления вы столкнётесь с ошибкой, сообщите нам об этом, [создав issue](https://github.com/dbt-labs/dbt/issues/new). dbt предоставляет функциональность новых версий dbt v1 через [каналы выпусков](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md) с автоматическими обновлениями. Если вы выбрали канал выпусков **v1 Latest** в dbt, у вас уже есть доступ ко всем возможностям, исправлениям и другим функциям, включённым в dbt v1.10! Если вы выбрали канал выпусков **v1 Compatible**, вы получите доступ к ним в следующем ежемесячном выпуске **v1 Compatible** после выхода финальной версии dbt v1.10. ## Новые и измененные возможности и функциональность Новые возможности и функции, доступные в dbt v1.10 ### Флаг `--sample` Большие наборы данных могут существенно замедлять время выполнения сборок dbt, усложняя эффективное тестирование нового кода. Флаг [`--sample`](https://docs.getdbt.tech/docs/build/sample-flag.md), доступный для команд `run` и `build`, помогает сократить время сборки и затраты на хранилище данных, запуская dbt в режиме выборки. Он генерирует отфильтрованные refs и sources с использованием временной выборки, позволяя разработчикам проверять результаты без построения моделей целиком. ### Перемещение независимых якорей под ключ `anchors:` В рамках непрерывной работы над повышением строгости языка описания dbt dbt v1.10 выводит предупреждение при обнаружении непредусмотренного ключа верхнего уровня в YAML-файле свойств. Часто такие ключи используются для отдельных определений якорей на верхнем уровне YAML-файла свойств. Теперь для размещения этих повторно используемых блоков конфигурации можно использовать новый ключ верхнего уровня `anchors:`. Например, вместо следующей конфигурации: models/\_models.yml ```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 ```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](https://docs.getdbt.tech/reference/resource-properties/anchors.md). ### Парсинг `catalogs.yml` dbt v1 теперь поддерживает разбор файла `catalogs.yml`. Это важный этап на пути к поддержке внешних каталогов для таблиц Iceberg, поскольку он открывает возможность интеграции для записи данных. Вы сможете указать в конфигурации интеграцию с каталогом для модели, создающей данные: Например: ```yml 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 ```yaml models: - name: my_second_public_model config: catalog_name: catalog_dave ``` Уже сейчас ознакомьтесь с нашей [документацией по поддержке внешних каталогов](https://docs.getdbt.tech/docs/build/iceberg/about-catalogs.md)! В ближайшие недели мы расскажем об этом подробнее, но уже сейчас это важный шаг на пути к кроссплатформенной поддержке. ### Интеграция артефактов dbt v1 с проектами dbt Благодаря [гибридным проектам](https://docs.getdbt.tech/docs/deploy/hybrid-projects.md) пользователи dbt v1, работающие в интерфейсе командной строки (CLI), могут выполнять запуски с автоматической загрузкой [артефактов](https://docs.getdbt.tech/reference/artifacts/dbt-artifacts.md) в dbt. Это расширяет возможности гибридных развертываний dbt v1/dbt следующим образом: * Улучшает совместную работу пользователей dbt и dbt v1, позволяя им визуализировать модели, определенные в проектах dbt v1, и создавать [межпроектные ссылки](https://docs.getdbt.tech/docs/mesh/govern/project-dependencies.md#how-to-write-cross-project-ref) на них. Эта функция объединяет рабочие процессы dbt и dbt v1, обеспечивая более тесную интеграцию при работе с dbt. * Предоставляет пользователям dbt и dbt v1 информацию об их моделях и ресурсах в [Catalog](https://docs.getdbt.tech/docs/explore/explore-projects.md). Для просмотра Catalog необходима [лицензия разработчика или лицензия с доступом только для чтения](https://docs.getdbt.tech/docs/platform/manage-access/seats-and-users.md). Гибридные проекты доступны в рамках закрытого бета-тестирования для [аккаунтов dbt Enterprise](https://www.getdbt.com/pricing). Свяжитесь с представителем, который ведет ваш аккаунт, чтобы сообщить о своем интересе к участию в бета-тестировании. ### Управление изменениями в устаревших поведениях В dbt v1.10 появились новые флаги для [управления изменениями прежнего поведения](https://docs.getdbt.tech/reference/global-configs/behavior-changes.md). Вы можете включить недавно добавленные изменения (по умолчанию отключены) или отключить устоявшиеся изменения (по умолчанию включены), задав соответствующим флагам в разделе `flags` файла `dbt_project.yml` значения `true` или `false` соответственно. Подробнее о каждом изменении поведения можно прочитать по следующим ссылкам: * (Добавлен, отключён по умолчанию) [`validate_macro_args`](https://docs.getdbt.tech/reference/global-configs/behavior-flags/validate_macro_args.md). Если установлено значение `true`, dbt выдаёт предупреждение, если имена или типы аргументов в YAML-описании макроса не соответствуют определению макроса на Jinja или используются неподдерживаемые значения типов. Обратите внимание: в проектах, использующих `--warn-error`, сборка может завершиться ошибкой на этапе разбора, если объявления аргументов макроса в YAML не согласованы с сигнатурой макроса на Jinja. * (Добавлен, отключён по умолчанию) [`require_all_warnings_handled_by_warn_error`](https://docs.getdbt.tech/reference/global-configs/behavior-flags/require_all_warnings_handled_by_warn_error.md). Если для этого флага установлено значение `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`](https://github.com/dbt-labs/dbt-autofix), чтобы автоматически исправить многие из этих проблем! 2. В будущем [конфигурация `meta`](https://docs.getdbt.tech/reference/resource-configs/meta.md) станет единственным местом для пользовательских атрибутов. Все остальные атрибуты будут строго типизированы и будут проходить строгую проверку. Если вы хотите добавить в проект дополнительный атрибут или параметр конфигурации модели, к которому нужно обращаться в пользовательской материализации, впредь его необходимо размещать внутри `meta`. 3. Если вы используете [флаг `--warn-error`](https://docs.getdbt.tech/reference/global-configs/warnings.md) (или `--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: ```yml models: - name: my_model description: A model in my project. dbt_is_awesome: true # пользовательское свойство ``` dbt обнаруживает неизвестное пользовательское свойство (`dbt_is_awesome`) и продолжает работу без предупреждений. Без строго определённого набора входных параметров проверять конфигурацию проекта становится сложно. Это приводит к непредвиденным проблемам, таким как: * Игнорирование свойств и параметров конфигурации с опечатками без предупреждений (например, `description:` вместо `description:`). * Непреднамеренные конфликты с пользовательским кодом, когда dbt вводит новое «зарезервированное» свойство или параметр конфигурации. Если у вас есть нераспознанное пользовательское свойство, вы получите предупреждение, а в будущей версии dbt поддержка таких свойств будет прекращена. В дальнейшем их следует размещать внутри конфигурации [`meta`](https://docs.getdbt.tech/reference/resource-configs/meta.md), которая станет единственным местом для пользовательских атрибутов: ```yml models: - name: my_model description: A model in my project. config: meta: dbt_is_awesome: true ``` #### Пользовательские ключи не вложенные под meta Ранее возможность определять любые дополнительные поля напрямую под `config` могла приводить к конфликтам между пользовательскими конфигурациями и официальными конфигурациями фреймворка dbt. В будущем конфигурация `meta` станет единственным допустимым местом для пользовательских атрибутов. Всё остальное будет строго типизировано и валидировано. Если у вас есть дополнительный атрибут, который вы хотите включить в проект, или конфигурация модели, к которой требуется доступ в кастомной материализации, её необходимо размещать под `meta`: ```yaml 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 ```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 ```sql {% endmacro %} # orphaned endmacro jinja block {% macro hello() %} hello! {% endmacro %} ``` В дальнейшем следует удалить такие осиротевшие Jinja-блоки. #### Свойства, перемещённые в конфигурацию Некоторые исторические properties полностью перемещаются в configs. К ним относятся: `freshness`, `meta`, `tags`, `docs`, `group` и `access`. Если ранее вы задавали одно из затронутых свойств, например `freshness`: ```yaml sources: - name: ecom schema: raw description: E-commerce data for the Jaffle Shop freshness: warn_after: count: 24 period: hour ``` Теперь его следует задавать внутри `config`: ```yaml 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` соответственно. ```yaml ... flags: warn_error_options: error: # Previously called "include" warn: # Previously called "exclude" silence: # To silence or ignore warnings - NoNodesForSelectionCriteria ``` ## Адаптер-специфичные возможности и функциональность Изменение размера столбцов в Snowflake [Snowflake планирует увеличить](https://docs.snowflake.com/en/release-notes/bcr-bundles/un-bundled/bcr-2118) размер столбцов по умолчанию для строковых и двоичных типов данных в сентябре 2026 года. После внедрения этого изменения в версиях `dbt-snowflake` ниже v1.10.6 могут возникать ошибки при построении некоторых инкрементальных моделей.  Оценка влияния и необходимые действия Если вы используете версию `dbt-snowflake` ниже v1.10.6 или ещё не перешли на [канал выпуска](https://docs.getdbt.tech/docs/dbt-versions/dbt-release-tracks.md) в dbt platform, ваша версия адаптера несовместима с этим изменением. Это может приводить к ошибкам при построении инкрементальных моделей, которые соответствуют *обоим* следующим условиям: * Содержат строковые столбцы с заданными правилами сортировки (collation) * Используют настройку `on_schema_change='sync_all_columns'` Чтобы проверить, затрагивает ли это изменение ваш проект, выполните следующую команду [list](https://docs.getdbt.tech/reference/commands/list.md): ```bash 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 или более поздняя версия. Указания по обновлению приведены в разделе [Обновление адаптеров](https://docs.getdbt.tech/docs/local/install-dbt.md) инструкции по установке dbt v1. * **dbt platform**: любой канал выпуска (**v1 Latest**, **v1 Compatible**, **v1 Extended** или **v1 Fallback**). * **dbt v2**: v2.0.0. Это позволит вашим инкрементальным моделям корректно обрабатывать изменения схемы, сохраняя необходимые настройки правил сортировки. ### Snowflake * С помощью параметра `platform_detection_timeout_seconds` можно задать время ожидания коннектора Snowflake при определении облачной платформы, из которой устанавливается подключение. Подробнее см. в разделе [Настройка Snowflake](https://docs.getdbt.tech/docs/local/connect-data-platform/snowflake-setup.md?version=1.12#platformdetectiontimeout_seconds). ### BigQuery * `dbt-bigquery` отправляет запрос на отмену заданий BigQuery, время выполнения которых превышает настроенный тайм-аут. Если запрос выполнен успешно, dbt останавливает задание. Если запрос не выполнен, задание BigQuery может продолжать выполняться в фоновом режиме, пока не завершится или вы не отмените его вручную. Подробнее см. в разделе [Тайм-ауты и повторные попытки](https://docs.getdbt.tech/docs/local/connect-data-platform/bigquery-setup.md?version=1.12#timeouts-and-retries). ## Коротко о главном * Используйте флаг [`--use-fast-test-edges`](https://docs.getdbt.tech/reference/global-configs/fast-test-edges.md) с командой `dbt build`, чтобы уменьшить количество рёбер тестов, которые dbt добавляет в граф выполнения. В крупных проектах это может значительно сократить время выполнения и потребление памяти. * Укажите свойство [`loaded_at_query`](https://docs.getdbt.tech/reference/resource-configs/freshness.md) для проверки актуальности источника, чтобы задать пользовательский SQL-запрос для получения временной метки `maxLoadedAt` в источнике (вместо [встроенного запроса](https://github.com/dbt-labs/dbt-adapters/blob/6c41bedf27063eda64375845db6ce5f7535ef6aa/dbt/include/global_project/macros/adapters/freshness.sql#L4-L16), который использует `loaded_at_field`). Нельзя задавать `loaded_at_query`, если также указан параметр конфигурации `loaded_at_field`. * Включите проверку аргументов макросов с помощью флага [`validate_macro_args`](https://docs.getdbt.tech/reference/global-configs/behavior-flags/validate_macro_args.md), который по умолчанию отключён. Когда этот флаг включён, он проверяет, совпадают ли имена аргументов макроса в документации с именами в определении макроса, а также соответствуют ли их типы поддерживаемому формату. Ранее dbt не требовал соблюдения стандартных типов аргументов и рассматривал поле типа исключительно как документацию. Если ни один аргумент не описан в документации, dbt определяет аргументы по определению макроса и включает их в файл manifest.json. Подробнее см. в разделе [Поддерживаемые типы](https://docs.getdbt.tech/reference/resource-properties/arguments.md#supported-types). * Вы можете использовать функции [`config.meta_get()`](https://docs.getdbt.tech/reference/dbt-jinja-functions/config.md#configmeta_get) и [`config.meta_require()`](https://docs.getdbt.tech/reference/dbt-jinja-functions/config.md#configmeta_require) для доступа к пользовательским настройкам, хранящимся в `meta`.