Переход на v2

dbt v2 — последняя основная версия фреймворка dbt. При установке dbt вы по умолчанию получаете dbt v2. В этом руководстве описан переход проекта с v1 на v2.

v2 работает быстрее и предъявляет более строгие требования, но язык вашего существующего проекта и семантика DAG сохраняются, поэтому после обновления проект работает как прежде — только быстрее.

Важно

dbt v2 доступен для установки в следующих средах:

• Локальные инструменты командной строки (CLI)
• VS Code и Cursor с расширением dbt
• Среды dbt platform

Присоединяйтесь к обсуждению в канале #dbt-v2 в Slack сообщества dbt.

Дополнительная информация о dbt v2

• Журнал изменений dbt v2
• О расширении dbt
• Установка dbt v2
• Краткое руководство по началу работы с dbt v2
• Лицензионное соглашение dbt v2

Установка dbt

У dbt v2 новое имя в PyPI: dbt. При установке с помощью менеджера пакетов, такого как pip, используйте пространство имён dbt, чтобы получить бесплатный полнофункциональный дистрибутив:

python -m pip install dbt

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

Полные инструкции, включая установку через Homebrew, winget и дополнительные варианты, приведены в разделе Установка dbt.

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

Если ваш старый проект ещё не готов к переходу на v2 или вам нужна совместимость с существующими инструментами, пакетами или рабочими процессами, которые ещё не перешли на v2, вы можете остаться на dbt v1.x — эта версия по-прежнему полностью поддерживается. Со временем новые возможности будут появляться только в v2, поэтому большинство пользователей в конечном счёте захотят обновиться. Чтобы установить или продолжить использовать v1.x, обратитесь к разделу Установка dbt v1.x.

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

Эти действия описаны ниже — они должны быть простыми, понятными и во многих случаях могут выполняться автоматически с помощью вспомогательного инструмента dbt-autofix или навыка агента.

Проверка совместимости с парсером v2 в dbt v1.12

Если вы используете dbt v1.12, вы можете проверить совместимость с парсером на Rust до полного перехода, включив флаг --use-v2-parser. Он передаёт разбор парсеру v2, не меняя остального поведения, что позволяет заранее выявить проблемы совместимости с минимальным риском.

Что следует учитывать при обновлении

В процессе обновления учитывайте следующее:

• Совместимость манифеста — dbt v2 создает манифест версии v12, совместимый с dbt v1. Единственное отличие — необязательные поля, специфичные для dbt v2: их записывает только dbt v2, а dbt v1 корректно их игнорирует.

  Поэтому вы можете использовать dbt v2 и dbt v1 параллельно. Функции, зависящие от состояния, такие как state:modified, --defer и выполнение dbt docs generate с использованием состояния из другого окружения, работают в смешанных окружениях dbt v2 и dbt v1. Это позволяет переходить на dbt v2 постепенно, не нарушая работу существующих заданий dbt v1.

Оркестрация с учетом состояния теперь называется dbt State

dbt State работает со всеми движками и окружениями: dbt v1, dbt platform и dbt v2.

Если вы использовали оркестрацию с учетом состояния до 1 июня 2026 года, вы можете продолжать ею пользоваться. Когда вы начнете бесплатный пробный период dbt State, он будет продлен сверх стандартных 30 дней. Если для вашей учетной записи продление не применено, обратитесь к команде по работе с вашим клиентским аккаунтом. Чтобы начать, ознакомьтесь с разделом Переход с оркестрации с учетом состояния.

Поддерживаемые адаптеры

В v2 поддерживаются следующие адаптеры:

 BigQuery

• Сервисный аккаунт / Токен пользователя
• Встроенный OAuth
• Внешний OAuth
  • Федерация удостоверений рабочих нагрузок (Microsoft Entra)
• Необходимые разрешения

 Databricks

• Сервисный аккаунт / Токен пользователя
• Встроенный OAuth

 Redshift

• Имя пользователя / Пароль
• Профиль IAM

 Snowflake

• Имя пользователя / Пароль
• Встроенный OAuth
• Внешний OAuth
• Пара ключей с использованием современного формата PKCS#8
• MFA

 ClickHouseЗакрытая бета-версия

• Имя пользователя / Пароль

 Apache Spark (только CLI)Бета-версия

• Thrift
  • Простой уровень аутентификации и безопасности (SASL), механизм PLAIN
  • Без SASL (NOSASL)
• Livy
  • Базовая аутентификация (имя пользователя и пароль)
  • При развертывании в Amazon Web Services (AWS): AWS Signature Version 4
    • Поддерживается аутентификация с использованием единого входа, сервисных учетных записей или пользовательских токенов

 DuckDB (только CLI)

DuckDB не требует аутентификации — он работает локально на вашем компьютере.

Обратите внимание, что жизненный цикл адаптера может различаться для dbt platform и локальной разработки. Адаптер может стать общедоступным (GA) в платформе dbt раньше, чем для локального использования.

С чистого листа

v2 не будет поддерживать никакую устаревшую функциональность (подробнее см. Обзор изменений):

• Перед переходом на новый движок необходимо устранить все предупреждения об устаревании. Это касается как ранее устаревших возможностей, так и новых предупреждений, появившихся в dbt v1.10.
• Некоторые флаги изменения поведения будут удалены (как правило, соответствующее поведение будет включено). Флаги, отмеченные значением 2.0 в столбце Removed этой таблицы, удалены: новое поведение всегда включено, и отключить его через flags: в dbt_project.yml больше нельзя. Все остальные флаги без указанной версии удаления (отмеченные -) остаются настраиваемыми, включая флаги, специфичные для v2 и перечисленные далее на этой странице.

Пакеты экосистемы

Самые популярные пакеты dbt-labs (dbt_utils, audit_helper, dbt_external_tables, dbt_project_evaluator) уже совместимы с v2. Сторонние пакеты, опубликованные организациями за пределами dbt, могут использовать устаревший код или несовместимые возможности, которые не удаётся разобрать в v2. Мы работаем с сопровождающими этих пакетов, чтобы сделать их доступными для v2. Пакеты, для совместимости которых с v2 требуется обновление до нового выпуска, будут указаны в этом руководстве по переходу.

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

Строгая валидация

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

Более быстрый парсер на Rust

Движок v2 полностью переписан на Rust, что ускоряет разбор и компиляцию, особенно в крупных проектах. Настройка не требуется; повышение производительности происходит автоматически.

dbt Information Schema

Подобно INFORMATION_SCHEMA в базе данных, dbt Information Schema представляет собой интерфейс с гарантированным контрактом для доступа к метаданным всех ресурсов вашего проекта dbt.

При использовании флага --generate-info-schema или установке DBT_ENGINE_GENERATE_INFO_SCHEMA=true dbt записывает Information Schema в target/info_schema/, в подкаталог с номером версии (например, target/info_schema/v1/), в виде стандартных файлов Parquet. Доступные в схеме метаданные дополняются на каждом этапе: разбор создаёт базовые метаданные, компиляция добавляет типы столбцов моделей и происхождение данных на уровне столбцов (при использовании --static-analysis strict), а выполнение или сборка добавляют результаты выполнения.

Подробнее см. dbt Information Schema.

Проверки

В dbt v2 можно создавать проверки, чтобы обеспечивать соблюдение стандартов проекта (например, у всех моделей должно быть описание, у публичной модели должен быть владелец и т. д.) на этапе разбора, до выполнения каких-либо операций в хранилище. Напишите SQL-правило в каталоге checks/, а затем запускайте проверки по мере необходимости с помощью dbt check. Проверки также автоматически выполняются при каждом запуске dbt build. Используйте --skip-checks, чтобы пропустить проверки при сборке.

Подробнее см. Проверки.

dbt Docs v2

В v2 появилась dbt Docs v2 — быстрый современный каталог для самостоятельного размещения, который помогает разобраться в производственных данных и доверять им. Вы получаете происхождение данных на уровне столбцов, метаданные Semantic Layer и полностью обновлённый интерфейс, который плавно работает даже с самыми крупными проектами. На внутреннем уровне метаданные хранятся в эффективных артефактах Parquet, что ускоряет загрузку и позволяет каталогу масштабироваться по мере роста проекта.

dbt docs generate компилирует проект, создаёт артефакты Parquet v2 и экспортирует статический сайт одной командой. dbt docs serve позволяет просмотреть этот сайт локально. Поскольку браузер запрашивает эти артефакты напрямую через DuckDB-WASM, сгенерированные файлы также можно разместить на любом хостинге статических файлов. Происхождение данных на уровне столбцов отображается при сборке с --static-analysis strict.

dbt Docs v2 работает только локально. Если вы используете dbt platform, ваши задания автоматически обновляют метаданные Catalog, поэтому изучайте проект в Catalog.

Чтобы заполнить метаданные каталога (catalog.json) для Catalog без сборки сайта, используйте флаг --write-catalog.

Полные сведения об использовании приведены в разделе О командах dbt docs.

Пакетное выполнение тестов

Теперь тесты данных можно выполнять пакетами! При использовании --batch-tests совместимые тесты данных, применяемые к одной модели, объединяются в один запрос для каждого типа теста. Внутреннее тестирование показывает, что пакетное выполнение сокращает время работы команды тестирования на 40%, количество отправляемых запросов — на 65%, а стоимость выполнения тестов в хранилище — на 15%!

Включите эту возможность с помощью --batch-tests в dbt test или dbt build либо с помощью переменной окружения DBT_ENGINE_BATCH_TESTS=true.

Подробнее о пакетном выполнении см. Пакетное выполнение тестов.

Актуальность моделей и команда dbt freshness

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

Используйте новую команду dbt freshness, чтобы за один вызов проверить все источники и модели с настроенной актуальностью и записать результаты в файл target/freshness.json.

Команда dbt source freshness по-прежнему поддерживается для обратной совместимости, проверяет только источники и продолжает создавать файл sources.json. В дальнейшем мы рекомендуем использовать dbt freshness.

Адаптеры на основе драйверов ADBC

Все адаптеры v2 подключаются к хранилищам данных через стандарт Arrow Database Connectivity (ADBC), а не через библиотеки адаптеров на Python. В результате dbt поставляется в виде единого автономного бинарного файла, которому не требуется среда выполнения Python.

При первом запуске dbt загружает драйверы адаптеров из CDN dbt Labs и кеширует их локально. Последующие запуски работают без доступа к сети. Сведения о поддерживаемых адаптерах приведены в разделе Поддерживаемые платформы данных.

dbt lint

В v2 появилась команда dbt lint — высокопроизводительный SQL-линтер, встроенный в dbt. Он совместим с SQLFluff: вы сохраняете существующую конфигурацию .sqlfluff и коды правил (например, CP01, RF03). Запустите dbt lint, чтобы проверить все модели, или dbt lint [FILE], чтобы проверить конкретный файл. Используйте --fix для автоматического исправления нарушений, которые можно исправить.

Статический анализ

В отличие от dbt v1.x, который только преобразовывал SQL-строки с шаблонами Jinja в запросы, v2 добавляет второй этап: статический анализ. После рендеринга движок создаёт и проверяет логический план для каждого запроса в проекте — ничего не выполняя в хранилище. Это обеспечивает валидацию с учётом диалекта, отслеживание происхождения данных на уровне столбцов и точную проверку типов. Настройка static_analysis определяет строгость этого анализа.

Базовый статический анализ

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

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

# dbt_project.yml
models:
  your_project:
    +static_analysis: baseline

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

Или передайте --static-analysis baseline через CLI. Подробнее см. О статическом анализе.

Строгий статический анализ

Строгий режим полностью определяет типы столбцов и проверяет ссылки во всём проекте до начала выполнения; ничего не запускается, пока корректность проекта не подтверждена. Он необходим для формирования происхождения данных на уровне столбцов и открывает дополнительные возможности LSP, такие как переход к определению столбца и проверка типов.

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

# dbt_project.yml
models:
  your_project:
    +static_analysis: strict

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

Или передайте --static-analysis strict через CLI (либо установите DBT_STATIC_ANALYSIS=strict). Подробнее см. static_analysis.

Устаревшие значения

static_analysis: on и static_analysis: unsafe — устаревшие синонимы strict. Замените их на strict; они будут удалены в одном из будущих выпусков.

Происхождение данных на уровне столбцов

v2 отслеживает, какие исходные столбцы формируют какие выходные столбцы во всём DAG. Чтобы сгенерировать происхождение данных на уровне столбцов, выполните сборку или компиляцию с --static-analysis strict:

dbt build --static-analysis strict

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

После этого происхождение данных отображается в dbt-docs. Дополнительная настройка не требуется; сайт автоматически обнаруживает артефакт с данными о происхождении. Подробнее см. Происхождение данных на уровне столбцов.

Протокол языкового сервера (LSP)

v2 включает встроенный языковой сервер, который предоставляет возможности IDE для SQL- и YAML-файлов dbt: информацию при наведении, диагностику, переход к определению и автодополнение на уровне столбцов. Отдельный пакет dbt-lsp больше не публикуется; теперь LSP входит в бинарный файл dbt и автоматически используется расширением dbt для VS Code и Studio IDE.

Доступные возможности зависят от настройки static_analysis: baseline добавляет обнаружение синтаксических ошибок и предварительный просмотр CTE; strict добавляет переход к определению столбца, происхождение данных на уровне столбцов и проверку типов. Подробнее см. О dbt LSP.

Навыки агентов

В v2 появились навыки агентов — многократно используемые инструкции, которые ваш агент программирования читает из файла SKILL.md. Вы и ваша команда можете распространять навыки из собственного проекта или из пакета, чтобы все работали по единому набору соглашений, а не копировали файлы между репозиториями.

Чтобы использовать навыки агентов, необходимо:

• Добавить навыки в каталог skills/ проекта, использовать пакет, содержащий навыки, или совместить оба способа
• Установить флаг ai_provider в корневом проекте, чтобы указать dbt, какой агент программирования вы используете. Поддерживаемые значения: wizard, claude, openai, codex, cursor или gemini (без учёта регистра).

Когда выполнены оба условия, dbt deps устанавливает эти навыки в каталог, из которого их читает агент (например, .claude/skills или .agents/skills), а dbt clean удаляет их. Если хотя бы одно условие не выполнено, dbt deps устанавливает пакеты как обычно и пропускает навыки.

Полные сведения об использовании, включая отключение ненужного навыка, приведены в разделе Установка навыков агентов из пакетов dbt.

Экспериментальные возможности

Локальное выполнение модульных тестов

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

Эта настройка экспериментальная и требует явного включения: перед использованием compute: local установите DBT_ENGINE_EXPERIMENTAL_LOCAL_UNIT_TESTS=true в окружении, где запускается dbt. Подробнее см. Локальное выполнение модульных тестов.

Запуски с несколькими адаптерами

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

export DBT_ENGINE_EXPERIMENTAL_MULTI_ADAPTER=true

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

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

Изменённая функциональность

При разработке v2 появилась возможность улучшить фреймворк dbt: раньше выявлять ошибки (где это возможно), исправить ошибки реализации, оптимизировать порядок выполнения и объявить устаревшими флаги, которые больше не актуальны. В результате внесён ряд точечных изменений с определёнными нюансами в существующее поведение.

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

Вызов макросов проекта в YAML-файлах

Вы можете вызывать макросы проекта непосредственно в YAML-файлах, таких как sources.yml и schema.yml:

sources:
  - name: raw_orders
    database: "{{ get_environment() }}"

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

В dbt v1 это не поддерживается, поскольку два движка используют разные контексты Jinja при рендеринге YAML:

• dbt v2 регистрирует макросы проекта до рендеринга, поэтому они доступны Jinja в YAML.
• В dbt v1 YAML-файлы обрабатываются с использованием отдельного ограниченного контекста, который не включает макросы проекта — только встроенные функции Jinja, такие как env_var() и doc().

Подробнее см. Поддержка Jinja по типам файлов.

При выводе отношений на этапе разбора отображается полное имя вместо пустой строки

В dbt v1 при выводе результата get_relation() соответствующий код Jinja на этапе разбора выводил None (неопределённый объект преобразуется в строку "None").

В v2 для интеллектуального объединения вызовов get_relation() в пакеты (и значительного ускорения dbt compile) dbt необходимо создавать объект отношения с полным именем, определённым на этапе разбора, для вызова метода адаптера get_relation().

Создание объекта отношения с полным именем в v2 приводит к поведению, отличному от v1, в print(), log() или любом макросе Jinja, который выводит данные в stdout или stderr на этапе разбора.

Пример:

{% set relation = adapter.get_relation(
database=db_name,
schema=db_schema,
identifier='a')
%}
{{ print('relation: ' ~ relation) }}

{% set relation_via_api = api.Relation.create(
database=db_name,
schema=db_schema,
identifier='a'
) %}
{{ print('relation_via_api: ' ~ relation_via_api) }}

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

Вывод после dbt parse в dbt v1:

relation: None
relation_via_api: my_db.my_schema.my_table

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

Вывод после dbt parse в v2:

relation: my_db.my_schema.my_table
relation_via_api: my_db.my_schema.my_table

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

Устаревшие флаги

Устаревшие флаги — это флаги командной строки (например, --models, --print), которые вы передаёте командам dbt. В v2 они удаляются. Их следует отличать от:

• Предупреждений об устаревании — возможностей в коде проекта (моделях, YAML, макросах), которые необходимо обновить
• Флагов изменения поведения — флагов в dbt_project.yml, позволяющих включать или отключать новое поведение

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

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

имя флага	необходимые действия
--models / --model / -m	См. Флаги CLI, требующие изменений.
dbt seed --show	Неприменимо
--print / --no-print	Никаких действий не требуется
--printer-width	Никаких действий не требуется
--source	Никаких действий не требуется
--record-timing-info / -r	Никаких действий не требуется
--cache-selected-only / --no-cache-selected-only	Никаких действий не требуется
--clean-project-files-only / --no-clean-project-files-only	Никаких действий не требуется
--single-threaded / --no-single-threaded	Никаких действий не требуется
dbt source freshness --output / -o
--config-dir	Никаких действий не требуется
--resource-type / --exclude-resource-type	См. Флаги CLI, требующие изменений.
--show-resource-report / --no-show-resource-report	Никаких действий не требуется
--log-cache-events / --no-log-cache-events	Никаких действий не требуется
--use-experimental-parser / --no-use-experimental-parser	Никаких действий не требуется
--empty-catalog
--compile / --no-compile
--inline-direct	Никаких действий не требуется
--partial-parse-file-diff / --no-partial-parse-file-diff	Никаких действий не требуется
--partial-parse-file-path	Никаких действий не требуется
--populate-cache / --no-populate-cache	Никаких действий не требуется
--static-parser / --no-static-parser	Никаких действий не требуется
--use-fast-test-edges / --no-use-fast-test-edges	Никаких действий не требуется
--inject-ephemeral-ctes / --no-inject-ephemeral-ctes
--partial-parse / --no-partial-parse	См. Флаги CLI, требующие изменений.

Флаги CLI, требующие изменений

Следующий устаревший флаг требует обновления определений заданий или скриптов:

• --models / --model / -m: Используйте вместо него --select / -s (переименован в dbt v0.21). В v2 dbt выдаёт ошибку при использовании старых флагов. Не передавайте --models в качестве значения -s (например, dbt run -s --models); v1 воспринимал это как имя модели, но v2 требует допустимый селектор.

Запуски заданий dbt v2 больше не поддерживают флаги CLI --partial-parse и --no-partial-parse. Если вы передадите их (например, в команде или скрипте dbt v1), dbt запишет в журнал предупреждение об устаревании dbt1700. Удалите эти флаги из команд запуска заданий dbt v2. Подробнее см. в разделе Устаревшие флаги руководства по переходу на dbt v2.

Конфликт версий, когда локальный пакет зависит от пакета из Hub, который также нужен корневому пакету, приводит к ошибке

Если локальный пакет зависит от пакета из Hub, который также нужен корневому пакету, dbt deps в dbt v1 не разрешает конфликты версий; команда устанавливает то, что запрашивает корневой проект.

v2 выдаст ошибку:

error: dbt8999: Cannot combine non-exact versions: =0.8.3 and =1.1.1

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

Разбор завершается ошибкой при вызове несуществующих макросов и методов адаптера

При вызове несуществующего макроса в dbt:

select
  id as payment_id,
  # my_nonexistent_macro is a macro that DOES NOT EXIST
  {{ my_nonexistent_macro('amount') }} as amount_usd,
from app_data.payments

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

Или несуществующего метода адаптера:

{{ adapter.does_not_exist() }}

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

В v1 dbt parse выполняется успешно, но dbt compile завершается ошибкой.

В v2 dbt выдаёт ошибку уже на этапе parse.

Разбор завершается ошибкой при отсутствии универсального теста

Если в проекте указан неопределённый универсальный тест:

models:
  - name: dim_wizards
    data_tests:
      - does_not_exist

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

В v1 dbt parse выполняется успешно, но dbt compile завершается ошибкой.

В v2 dbt выдаёт ошибку уже на этапе parse.

Разбор завершается ошибкой при отсутствии переменной

Если в проекте используется неопределённая переменная:

select {{ var('does_not_exist') }} as my_column

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

В v1 dbt parse выполняется успешно, но dbt compile завершается ошибкой.

В v2 dbt выдаёт ошибку уже на этапе parse.

Более строгая проверка дублирующихся блоков docs

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

v2 добавляет более строгую проверку имён блоков docs, чтобы исключить такую неоднозначность. При обнаружении повторяющихся имён будет выдана ошибка:

dbt found two docs with the same name: 'docs_block_title' in files: 'models/crm/_crm.md' and 'docs/crm/business_class_marketing.md'

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

Чтобы устранить эту ошибку, переименуйте все дублирующиеся блоки docs.

dbt clean не удаляет файлы в настроенных путях ресурсов или за пределами каталога проекта

В dbt v1 команда dbt clean удаляет:

• Любые файлы за пределами каталога проекта, если в clean-targets задан абсолютный путь или относительный путь, содержащий ../, хотя существует настройка для явного отключения этого поведения (--clean-project-files-only / --no-clean-project-files-only).
• Любые файлы в asset-paths или doc-paths (хотя для других путей ресурсов, таких как model-paths и seed-paths, действуют ограничения).

В v2 dbt clean не удаляет файлы в настроенных путях ресурсов или за пределами каталога проекта.

В dbt build все модульные тесты выполняются первыми

В dbt v1 непосредственные родительские модели тестируемой модели должны были существовать в хранилище, чтобы получить необходимые сведения об именах и типах столбцов. dbt build выполняет модульные тесты (и модели, от которых они зависят) в порядке зависимостей.

В v2 dbt build сначала выполняет все модульные тесты, а затем собирает остальную часть DAG благодаря встроенной информации об именах и типах столбцов.

Настройка --threads

dbt v1 по умолчанию запускается с --threads 1. Вы можете увеличить это число, чтобы выполнять больше узлов параллельно на удалённой платформе данных, вплоть до максимального параллелизма, допускаемого DAG.

v2 управляет потоками по-разному в зависимости от вашей платформы данных:

Адаптер	Поведение
Snowflake	dbt v2 автоматически управляет количеством параллельных подключений с учётом ограничений платформы и обратного давления. Если задан параметр threads, он устанавливает максимальное количество подключений, но dbt v2 рассчитан на оптимальную работу и без его настройки. Если возникают проблемы с тайм-аутами или ограничениями частоты запросов, может помочь уменьшение значения threads.
Databricks	dbt v2 автоматически управляет количеством параллельных подключений с учётом ограничений платформы и обратного давления. Если задан параметр threads, он устанавливает максимальное количество подключений, но dbt v2 рассчитан на оптимальную работу и без его настройки. Если возникают проблемы с тайм-аутами или ограничениями частоты запросов, может помочь уменьшение значения threads.
BigQuery	dbt v2 учитывает заданное пользователем количество потоков для соблюдения ограничений частоты запросов к API. Значение --threads 0 (или отсутствие этой настройки) позволяет dbt v2 динамически оптимизировать степень параллелизма.
Redshift	dbt v2 учитывает заданное пользователем количество потоков для соблюдения ограничений на число одновременно выполняемых операций. Значение --threads 0 (или отсутствие этой настройки) позволяет dbt v2 динамически оптимизировать степень параллелизма.

Подробнее см. Использование потоков.

Продолжение компиляции независимых узлов после ошибки компиляции

Как только compile в v1 сталкивается с ошибкой при компиляции одной из моделей, dbt останавливается и больше ничего не компилирует.

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

Лишние запятые в seed-файлах не приводят к появлению дополнительных столбцов

В dbt v1, если в seed-файле есть дополнительная запятая, dbt создаёт seed с дополнительным пустым столбцом.

Например, следующий seed-файл (с лишней запятой):

animal,  
dog,  
cat,  
bear,  

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

При выполнении dbt seed создаст такую таблицу:

animal	b
dog
cat
bear

В v2 этот дополнительный столбец в таблице, полученной в результате dbt seed, не создаётся:

animal
dog
cat
bear

Перенос отдельных якорей под ключ anchors:

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

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

models/_models.yml

# id_column is not a valid name for a top-level key in the dbt authoring spec, and will raise an error
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

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

Перенесите якорь под ключ 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.

Самоссылочные (рекурсивные) якоря YAML не поддерживаются

В v1 dbt мог разобрать якорь YAML, который объединяется с элементом той же последовательности, для которой он определён, создавая самоссылочный (циклический) якорь. Например, якорь задаётся для всей последовательности tables:, а затем объединяется с одним из элементов этой же последовательности:

sources:
  - name: catalogue
    tables: &tables
      - name: anchor_item
        description: The first table in the sequence.
      - <<: *tables
        name: merged_item

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

В v1 такой код успешно разбирался только потому, что PyYAML (библиотека YAML, от которой зависит dbt v1) попутно допускает самоссылочные якоря. Это побочный эффект поддержки циклических структур данных в самом Python, а не намеренно предусмотренная возможность YAML. Никакая другая крупная реализация YAML не допускает такой шаблон.

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

Чтобы исправить это, удалите самоссылку. Задавайте якоря только для тех частей документа, которые не объединяются сами с собой: например, задайте якорь для отображения одной таблицы, а не для всей последовательности:

sources:
  - name: catalogue
    tables:
      - &anchor_item_alias
        name: anchor_item
        description: The first table in the sequence.
      - <<: *anchor_item_alias
        name: merged_item

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

Алгебраические операции в макросах Jinja

В v1 можно использовать алгебраические операции с функцией return в макросе Jinja:

{% macro my_macro() %}

return('xyz') + 'abc'

{% endmacro %}

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

В v2 это больше не поддерживается и приводит к предупреждению:

[warning] [JinjaTopLevelReturn (dbt1508)]: return is not at the top level of the block.
Its value is final and cannot be modified by surrounding expressions.
Example: return(0) + 1. The + 1 is ignored and the macro returns 0.

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

Такое использование встречается редко, и в v1 для этого поведения нет предупреждения об устаревании. Поддерживаемый формат:

{% macro my_macro() %}

return('xyzabc')

{% endmacro %}

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

Доступ к пользовательским настройкам в meta

config.get() и config.require() не возвращают значения из словаря meta. Если вы попытаетесь обратиться к ключу, который существует только в meta, dbt выдаст предупреждение:

warning: The key 'my_key' was not found using config.get('my_key'), but was 
detected as a custom config under 'meta'. Please use config.meta_get('my_key') 
or config.meta_require('my_key') instead.

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

Поведение, когда ключ существует только в meta:

Метод	Поведение
config.get('my_key')	Возвращает значение по умолчанию и выдаёт предупреждение.
config.require('my_key')	Вызывает ошибку и выдаёт предупреждение.

Кроме того, доступ к самому словарю meta (а не к конкретному ключу) работает по-разному в разных движках:

Движок	config.get('meta', default={})
dbt v1	Не работает.
dbt v2	Возвращает весь словарь meta.

Для доступа к пользовательским настройкам, хранящимся в meta, используйте специальные методы:

{% set owner = config.meta_get('owner') %}
{% set has_pii = config.meta_require('pii') %}

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

Подробнее см. config.meta_get() и config.meta_require().

Коротко о других изменениях

• v2 поддерживает экспорт трассировок и журналов в форматах JSONL, Parquet и OTLP. Подробнее см. Телеметрия и наблюдаемость dbt v2.
• Компилятор v2 разбирает и проверяет типы вызовов функций моделей Snowflake (model!method(...)), принимая любые аргументы и рассматривая результаты как VARIANT. Приведите результат к нужному типу (например, model!predict(col)::float).
• В dbt v2 команда dbt login открывает браузер для входа в dbt platform или создания бесплатной учётной записи. Выполните dbt login status, чтобы просмотреть текущий статус аутентификации.

Поддержка пакетов

Чтобы определить, совместим ли пакет с dbt v2, посетите каталог пакетов dbt и найдите значок совместимости с dbt v2 или проверьте настройку require-dbt-version пакета.

• Пакеты, у которых значение require-dbt-version равно 2.0.0 или задаёт диапазон, включающий эту версию, совместимы с dbt v2. Например, require-dbt-version: ">=1.10.0,<3.0.0".

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

• Сопровождающие пакетов, которые хотят обеспечить совместимость своих пакетов с v2, могут найти инструкции в руководстве по обновлению пакетов для dbt v2.

Особенности пакетов Fivetran:

• Пакеты Fivetran source и transformation объединены в один пакет.
• Если вы вручную установили пакеты источников, такие как fivetran/github_source, необходимо убедиться, что установлен пакет fivetran/github, и деактивировать модели преобразования.

Сообщения о совместимости пакетов

Расхождения между предупреждениями v2 и журналами dbt-autofix

Предупреждения dbt v2 и журналы dbt-autofix могут содержать разные сообщения о совместимости пакетов.

Если вы используете dbt-autofix при переходе на v2 в Studio IDE или расширении dbt для VS Code, вы можете заметить расхождения между сообщениями о совместимости пакетов в dbt-autofix и предупреждениями v2.

Вот почему:

• Предупреждения dbt v2 выдаются на основе значения require-dbt-version пакета и того, включает ли require-dbt-version версию 2.0.0.
• Некоторые пакеты уже совместимы с v2, хотя их сопровождающие еще не обновили require-dbt-version.
• dbt-autofix знает об этих совместимых пакетах и не будет пытаться обновить пакет, о совместимости которого ему уже известно.

Это означает, что даже если вы видите предупреждение v2 для пакета, который dbt-autofix определяет как совместимый, вам не нужно менять этот пакет.

Это временное расхождение в сообщениях: мы работаем над внедрением улучшенного механизма определения совместимости из dbt-autofix в предупреждения v2.

Вот пример предупреждения v2 в Studio IDE, которое сообщает, что пакет несовместим с v2, хотя dbt-autofix указывает, что он совместим:

dbt1065: Package 'dbt_utils' requires dbt version [>=1.30,<2.0.0], but current version is 2.0.0. This package may not be compatible with your dbt version. dbt(1065) [Ln 1, Col 1]

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

Дистрибутивы

v2 доступна в двух дистрибутивах. Подробнее см. Лицензирование dbt.

Дистрибутив	Пакет	Когда использовать
dbt v2	dbt	Рекомендуемый вариант использования v2.
dbt OSS	dbt-oss	В вашей организации действует строгое требование использовать среду выполнения с открытым исходным кодом под лицензией Apache 2.0.

Если ваш старый проект ещё не готов к переходу на v2, продолжайте использовать v1.x для совместимости. Для новых или обновлённых проектов мы рекомендуем v2.

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

Создать GitHub Issue