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

Обновление до движка dbt Fusion (v2.0)

important

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

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

Читайте Fusion Diaries, чтобы быть в курсе последних обновлений.

Дополнительная информация о Fusion​

Fusion — это значительное обновление dbt. Хотя многие рабочие процессы, к которым вы привыкли, остаются без изменений, появляется множество новых идей, а также происходит отказ от ряда старых подходов. Ниже приведён список, охватывающий полный объём текущего релиза движка Fusion, включая вопросы реализации, установки, устаревших возможностей и ограничений:

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

dbt Core и dbt Fusion используют единый языковой спецификатор — код вашего проекта. dbt Labs стремится обеспечить функциональное соответствие (feature parity) с dbt Core везде, где это возможно.

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

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

Подробнее о том, какие изменения вносит движок dbt Fusion, можно узнать в changelog.

Соображения при обновлении​

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

  • Несовместимость манифестов — Fusion обратно совместим и может читать манифесты dbt Core. Однако dbt Core не обладает прямой совместимостью и не может читать манифесты Fusion. Fusion создаёт манифест версии v20, в то время как последняя версия dbt Core по‑прежнему создаёт манифест v12.

    В результате смешивание манифестов dbt Core и Fusion между разными окружениями нарушает работу кросс‑окруженческих возможностей. Чтобы этого избежать, используйте state:modified, --defer и кросс‑окруженческий dbt docs generate только после того, как все окружения будут работать на последней версии Fusion. Использование этих возможностей до перевода всех окружений на Fusion может приводить к ошибкам и сбоям.

  • Оркестрация с учётом состояния (state-aware orchestration) — При использовании state-aware orchestration dbt не обнаруживает изменения, если таблица или представление были удалены вне dbt, поскольку кэш является уникальным для каждого окружения dbt platform. Это означает, что state-aware orchestration не будет пересобирать соответствующую модель до тех пор, пока не появятся новые данные или не произойдёт изменение кода, который использует эта модель.

    • Обходные решения:
      • Использовать кнопку Clear cache на странице целевого окружения Environment, чтобы принудительно выполнить полную пересборку (аналогично сбросу), или
      • Временно отключить state-aware orchestration для задания и запустить его повторно.

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

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

 BigQuery
 Databricks
  • Служебная учетная запись / токен пользователя
  • Нативный OAuth
 Redshift
  • Имя пользователя / пароль
  • Профиль IAM
 Snowflake
  • Имя пользователя / пароль
  • Нативный OAuth
  • Внешний OAuth
  • Пара ключей с использованием современного метода PKCS#8
  • MFA

Чистый лист​

dbt Labs делает ставку на дальнейшее развитие Fusion, и поэтому он не поддерживает никакую устаревшую функциональность:

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

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

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

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

При обновлении до Fusion следует ожидать следующих изменений.

Вывод relations на этапе parse теперь печатает полное квалифицированное имя, а не пустую строку​

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

В Fusion, чтобы обеспечить интеллектуальное батчирование вызовов get_relation() (и существенно ускорить dbt compile), dbt необходимо создавать объект relation с полностью разрешённым квалифицированным именем уже на этапе parse для вызова адаптера get_relation().

Создание relation с полностью квалифицированным именем в Fusion приводит к отличающемуся поведению по сравнению с dbt Core v1 при использовании print(), log() или любых Jinja‑макросов, выводящих данные в stdout или stderr на этапе parse.

Пример:

{% 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 Core v1:

relation: None
relation_via_api: my_db.my_schema.my_table

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

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

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

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

Есть одно исключение: флаг --models / --model / -m был переименован в --select / --s ещё в dbt Core v0.21 (октябрь 2021). Тихое игнорирование этого флага означало бы игнорирование критериев выбора в команде, что могло бы привести к сборке всего DAG вместо небольшой подмножины. Поэтому флаг --models / --model / -m будет приводить к ошибке в Fusion. Пожалуйста, обновите определения ваших задач соответствующим образом.

имя флагадействия
dbt seed --showN/A
--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заменить на --resource-types / --exclude-resource-types
--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Действия не требуются
--introspect / --no-introspectДействия не требуются
--inject-ephemeral-ctes / --no-inject-ephemeral-ctes
--partial-parse / --no-partial-parseДействия не требуются
Loading table...

Конфликтующие версии пакетов теперь приводят к ошибке​

Если локальный пакет зависит от пакета из хаба, который также требуется корневому пакету, dbt deps в dbt Core v1 не разрешает конфликт версий и устанавливает версию, указанную корневым проектом.

В Fusion будет выведена ошибка:

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

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

Если вы вызываете несуществующий макрос:

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() }}

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

В Fusion ошибка будет выброшена уже на этапе parse.

Parse завершается ошибкой при отсутствии generic test​

Если в проекте определён несуществующий generic test:

models:
  - name: dim_wizards
    data_tests:
      - does_not_exist

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

В Fusion ошибка возникает уже во время parse.

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

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

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

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

В Fusion ошибка возникает уже во время parse.

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

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

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

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 blocks.

Прекращение поддержки устаревших версий manifest​

Fusion больше не может работать с версиями dbt-core ниже 1.8, если вы:

  • гибридный клиент, использующий Fusion и старую (до v1.8) версию dbt Core;
  • клиент, обновляющийся со старой (до v1.8) версии dbt Core на Fusion.

Fusion не может работать со старым manifest, который используется, например, для deferral при сравнении state:modified.

dbt clean больше не удаляет файлы в resource paths и за пределами директории проекта​

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

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

В Fusion dbt clean не будет удалять файлы ни в настроенных resource paths, ни за пределами директории проекта.

Все unit tests выполняются первыми в dbt build​

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

В Fusion dbt build сначала выполняет все unit tests, а затем строит остальной DAG, благодаря встроенному знанию имён и типов колонок.

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

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

В Fusion, если --threads не задан или задан как --threads 0, dbt использует значение по умолчанию для максимального числа потоков, определённое для конкретного адаптера. Некоторые платформы данных способны обрабатывать больше параллельных соединений, чем другие. Если пользователь явно задал --threads (через CLI или profiles.yml), Fusion будет использовать это значение.

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

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

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

Seeds с лишними запятыми больше не создают дополнительные колонки​

В dbt Core v1, если в seed-файле присутствует лишняя запятая, dbt создаёт дополнительную пустую колонку.

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

animal,  
dog,  
cat,  
bear,

Приведёт к созданию таблицы:

animalb
dog
cat
bear
Loading table...

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

animal
dog
cat
bear
Loading table...

Перенос standalone anchors под ключ anchors:​

В рамках процесса уточнения языка описания dbt любые неожиданные ключи верхнего уровня в YAML-файлах теперь приводят к ошибкам. Частый источник таких ключей — standalone anchors, определённые на верхнем уровне 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

Переместите 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.

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

В dbt Core можно использовать алгебраические операции в возвращаемом значении Jinja-макроса:

{% macro my_macro() %}

return('xyz') + 'abc'

{% endmacro %}

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

error: dbt1501: Failed to add template invalid operation: return() is called in a non-block context

Это редкий сценарий использования, и для такого поведения в dbt Core не было предупреждения об устаревании. Поддерживаемый вариант выглядит так:

{% 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')Генерирует ошибку и выдаёт предупреждение
Loading table...

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

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

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

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

Чтобы определить, совместим ли пакет с dbt Fusion Engine, посетите dbt package hub и найдите бейдж совместимости с Fusion, либо изучите конфигурацию пакета require-dbt-version.

  • Пакеты с require-dbt-version, который равен 2.0.0 или включает его, совместимы с Fusion. Например: require-dbt-version: ">=1.10.0,<3.0.0".

    Даже если пакет не отражает совместимость в package hub, он всё равно может работать с Fusion. Рекомендуется взаимодействовать с мейнтейнерами пакета, чтобы отслеживать обновления, и тщательно тестировать пакеты, совместимость которых не очевидна, перед развертыванием.

  • Мейнтейнеры пакетов, которые хотят сделать свой пакет совместимым с Fusion, могут обратиться к руководству по обновлению пакетов для Fusion с подробными инструкциями.

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

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

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

Несоответствие предупреждений Fusion и логов dbt-autofix

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

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

Вот почему это происходит:

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

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

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

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

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

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

0
Loading