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

Изменения в поведении адаптера Databricks

Ниже приведены текущие флаги изменения поведения, которые специфичны для dbt-databricks:

Флагdbt-databricks: Introdbt-databricks: MaturityСтатус
use_info_schema_for_columns1.9.0НеприменимоУдалён в 1.11.0
use_user_folder_for_python1.9.01.11.0Значение по умолчанию изменено на true
use_materialization_v21.10.0Пока не определеноАктивен
use_managed_iceberg1.11.01.12.0Активен
use_replace_on_for_insert_overwrite1.11.01.12.0Активен, значение по умолчанию — true
use_describe_as_json_for_relation_metadata1.12.0Пока не определеноАктивен, значение по умолчанию — false

Используйте information schema для столбцов​

Удалён в v1.11.0

Флаг use_info_schema_for_columns был удалён, начиная с dbt-databricks v1.11.0. Адаптер теперь использует DESCRIBE EXTENDED ... AS JSON (доступно в DBR 16.2+) для эффективного получения информации о сложных типах данных, что устраняет необходимость в этом флаге.

Если вы всё ещё используете этот флаг в конфигурации проекта, его можно безопасно удалить. Новый подход обеспечивает лучшую производительность и не требует выполнения операций REPAIR TABLE, которые были необходимы при использовании information_schema.

Документация для предыдущих версий​

Применяется к dbt-databricks версии v1.11 и более ранних версий В версиях 1.9 и 1.10 флаг use_info_schema_for_columns по умолчанию имел значение false.

При установке этого флага в true для получения метаданных столбцов таблиц Unity Catalog использовалась information_schema вместо describe extended. Эта настройка помогала избежать проблем, связанных с тем, что describe extended обрезает информацию, когда тип данных — сложная структура (struct).

При установке этого флага в True для получения метаданных колонок таблиц Unity Catalog использовался information_schema, а не describe extended. Это помогало обходить проблемы, при которых describe extended усекал информацию, если тип данных представлял собой сложную структуру (struct).

Для сложных типов

Если сложный тип получен в результате обработки JSON с помощью from_json, есть альтернативный вариант: использовать parse_json для создания колонки типа variant. Тип variant может быть разумной альтернативой с точки зрения производительности и при этом позволяет избежать проблем с усечением типов.

Используйте папку пользователя для блокнотов моделей Python​

Значение по умолчанию изменено в v1.11.0

Начиная с dbt-databricks v1.11.0, флаг use_user_folder_for_python по умолчанию имеет значение true.

Флаг use_user_folder_for_python определяет, где в Databricks хранятся загруженные ноутбуки Python-моделей:

  • true (по умолчанию в v1.11+): Ноутбуки записываются в /Users/{{current user}}/{{catalog}}/{{schema}}/.
  • false (по умолчанию в v1.9-v1.10): Ноутбуки записываются в /Shared/dbt_python_models/{{schema}}/.

Databricks признал запись в папку Shared устаревшей, так как она не соответствует лучшим практикам управления и безопасности. Использование пользовательских папок обеспечивает лучшую изоляцию, контроль доступа и соответствует модели безопасности Unity Catalog.

Чтобы сохранить прежнее поведение для обратной совместимости, можно явно установить для этого флага значение false в файле dbt_project.yml:

flags:
use_user_folder_for_python: false

Используйте реструктурированные материализации​

Флаг use_materialization_v2 по умолчанию имеет значение false и управляет включением существенно переработанных основных материализаций в dbt-databricks, пока они находятся на экспериментальной стадии.

При значении true адаптер dbt-databricks использует обновлённую логику для всех типов моделей (представлений, таблиц, инкрементальных моделей и seed-данных). Также становятся доступны дополнительные необязательные параметры конфигурации для более тонкой настройки:

  • view_update_via_alter — Если этот параметр включён, адаптер пытается обновить представление на месте с помощью alter view, а не заменить его с помощью create or replace.
  • use_safer_relation_operation — Если этот параметр включён (а view_update_via_alter не задан), обновление моделей dbt становится безопаснее: объекты базы данных предварительно подготавливаются, а затем переименовываются, чтобы сбои не нарушали работу текущей версии таблицы или представления.

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

В версии v1.11.0 этот флаг по умолчанию останется установленным в false. Учитывая отзывы об отсутствии атомарности (обновлений по принципу «всё или ничего») в новой материализации, мы не будем включать его автоматически. Мы изучим другие способы получить те же преимущества без потери атомарности. Учитывая отзывы об отсутствии атомарности в новом подходе к материализации, мы не будем переключать этот флаг на true. Вместо этого мы будем исследовать новые способы получить те же преимущества, сохранив атомарность.

Изменения в materialization Seed​

Materialization для seeds должна иметь минимальные отличия между старой и новой реализациями, так как основное изменение заключается в удалении вызовов методов, которые не поддерживаются Databricks, например операций с транзакциями.

Изменения в materialization View​

Если флаг use_materialization_v2 установлен в true, доступны два параметра конфигурации модели, которые позволяют настроить обработку материализации в виде представления при обнаружении существующего отношения в целевом расположении.

  • view_update_via_alter — обновляет view «на месте» с помощью alter view, вместо использования create or replace. Это позволяет сохранить историю view, метаданные и улучшает совместимость с Unity Catalog. Пример конфигурации:
schema.yml
models:
- name: market_summary
config:
materialized: view
view_update_via_alter: true

columns:
- name: country
data_tests:
- unique
- not_null
...
В настоящее время Databricks SQL не поддерживает изменение комментария view с помощью alter.

Поэтому при изменении описания view его необходимо пересоздавать.

  • use_safer_relation_operations — при включении (и если не задан view_update_via_alter) этот параметр делает обновления моделей более безопасными за счёт создания новой relation во временном месте, её замены на существующую и последующего удаления старой relation. Пример конфигурации:
schema.yml
models:
- name: market_summary
config:
materialized: view
use_safer_relation_operations: true

columns:
- name: country
data_tests:
- unique
- not_null
...
Этот параметр конфигурации может увеличить затраты и повлиять на историю Unity Catalog.

Хотя этот подход эквивалентен стандартной materialization view в dbt, он создаёт больше объектов UC по сравнению с альтернативами. Так как в этой конфигурации не используется атомарный create or replace..., история объекта в Unity Catalog может вести себя не так, как вы ожидаете. Тщательно взвесьте необходимость использования этой настройки в широком масштабе.

Изменения в materialization Table​

Этот флаг может увеличить затраты на хранение таблиц.

Как и в случае с view, эти изменения materialization могут привести к росту затрат. Используется больше временных объектов, что соответствует materialization в других адаптерах dbt. Мы считаем эти изменения экспериментальными, в том числе потому, что у нас недостаточно данных для точной оценки влияния на стоимость. При этом преимущества заключаются в улучшении производительности, безопасности и возможности реализовать функции, которые невозможно добавить в текущей materialization.

Когда use_materialization_v2 установлен в true, обновляются все пути выполнения материализаций. Ключевое изменение заключается в том, что создание таблицы отделено от вставки строк в неё. Такое разделение значительно повышает производительность при добавлении комментариев к таблицам, поскольку добавлять комментарии при создании таблицы быстрее, чем с помощью отдельных операторов alter table. Оно также устраняет проблемы совместимости в Databricks, где создание таблицы и вставка данных за один шаг не позволяют задавать комментарии.

Кроме того, это изменение позволяет поддерживать другие возможности на уровне колонок — например, column-level masks — которые несовместимы со вставкой данных во время создания таблицы. Хотя эти функции не включены в версию 1.10.0, теперь их можно добавить в будущих релизах.

Constraints​

В течение нескольких релизов dbt-databricks поддерживал как реализацию constraints в dbt, так и собственную, более раннюю альтернативу под названием persist_constraints. С флагом use_materialization_v2 мы начинаем постепенно выводить persist_constraints из использования и полностью переходим на нативную поддержку ограничений в dbt.

Одним из новых улучшений стала поддержка поля expression для первичных и внешних ключей. Это позволяет передавать дополнительные опции Databricks — например, использование RELY, чтобы сообщить оптимизатору Databricks, что он может использовать ограничение для переписывания запросов.

Разделение create и insert также меняет поведение ограничений. Ранее таблица создавалась сразу с данными, а затем применялись ограничения. Если новые данные нарушали ограничение, выполнение завершалось ошибкой — но к этому моменту корректная таблица из предыдущего запуска уже была заменена.

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

use_safer_relation_operations​

При использовании этой конфигурации для таблиц сначала создаётся staging-таблица. После успешной вставки данных она переименовывается и заменяет целевую materialization. Поскольку Databricks не поддерживает откаты, это более безопасный подход: если ошибка произойдёт до переименования, исходная таблица останется нетронутой. Это даёт время на отладку без риска нарушить работу downstream-зависимостей.

Если этот параметр установлен в false (значение по умолчанию), целевая таблица всё равно не будет содержать данные, нарушающие ограничения, однако она может оказаться пустой, если вставка завершится ошибкой из-за constraint. Ключевое различие — заменяем ли мы целевую таблицу напрямую или используем подход staging + rename.

Этот параметр конфигурации может увеличить затраты и повлиять на историю Unity Catalog.

Как и в случае с view, использование дополнительных временных объектов приводит к созданию большего числа объектов UC со своей историей. Тщательно оцените, действительно ли вам необходимо такое поведение.

Изменения в materialization Incremental​

Все изменения, описанные в разделе Table materialization, также применимы к incremental materialization.

Также был добавлен новый параметр конфигурации: incremental_apply_config_changes.

Этот параметр позволяет контролировать, должен ли dbt применять изменения таких свойств, как tags, tblproperties и комментарии, во время incremental-запусков. Многие пользователи хотели иметь возможность настраивать метаданные таблиц в Databricks — например, AI-сгенерированные комментарии — без того, чтобы dbt их перезаписывал. Ранее dbt-databricks всегда применял обнаруженные изменения при incremental-запусках.

При использовании материализации V2 теперь можно установить incremental_apply_config_changes в false, чтобы отключить это поведение. (По умолчанию используется значение true, чтобы сохранить прежнее поведение.)

Пример конфигурации:

schema.yml
models:
- name: incremental_market_updates
config:
materialized: incremental
incremental_apply_config_changes: false
...

Используйте управляемый Iceberg​

Когда вы задаёте для table_format значение iceberg, флаг use_managed_iceberg определяет, как создаётся таблица. По умолчанию этот флаг имеет значение false, и dbt создаёт таблицу UniForm. Если установить значение true, dbt создаёт управляемую таблицу Iceberg.

Используйте replace on для стратегии insert_overwrite​

Флаг use_replace_on_for_insert_overwrite определяет, какой синтаксис SQL генерирует dbt для инкрементальных моделей, использующих стратегию insert_overwrite. По умолчанию этот флаг имеет значение true, при котором для динамической перезаписи разделов/кластеров используется синтаксис insert into ... replace on, что соответствует поведению при использовании кластерных вычислительных ресурсов. Когда флаг установлен в false, insert_overwrite полностью очищает таблицу при использовании SQL-хранилищ. Флаг не влияет на кластерные вычислительные ресурсы, поскольку при их использовании insert_overwrite всегда выполнял динамическую перезапись разделов/кластеров.

Значение флагаГенерируемый SQLОписание
true (по умолчанию)INSERT INTO ... REPLACE ONИспользует новейший рекомендуемый синтаксис Databricks для замены соответствующих разделов.
falseINSERT OVERWRITEИспользует более старый синтаксис Spark для перезаписи разделов. Зависит от настроек сеанса Spark.

Если ранее вы полагались на это поведение для полной замены содержимого таблицы без удаления существующих метаданных, оно сохраняется и при значении флага true, если вы не используете разделы или кластеры liquid clustering. Такие способы оптимизации размещения данных обычно дают существенный эффект только для таблиц размером около 1 ТБ и более, а при таком объёме регулярная замена всех данных, вероятно, уже не лучший подход.

Использование DESCRIBE AS JSON для получения метаданных отношений​

Флаг use_describe_as_json_for_relation_metadata определяет, как dbt получает метаданные на уровне отношений для таблиц и представлений Databricks, такие как ограничения (первичный ключ, внешний ключ и запрет значений NULL), маски столбцов, фильтры строк и описания представлений. Он принимает два значения:

  • false (по умолчанию): dbt выполняет несколько запросов к information_schema для каждого отношения, чтобы получить эти метаданные.
  • true: dbt получает все эти метаданные одним вызовом DESCRIBE TABLE EXTENDED ... AS JSON для каждого отношения.

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

Требования​

dbt использует DESCRIBE AS JSON для конкретного отношения, только когда выполняются все следующие условия:

  • Отношение находится в Unity Catalog (а не в Hive metastore).
  • Отношение не является внешней таблицей (foreign table).
  • Вычислительный ресурс является SQL-хранилищем или работает на DBR версии 17.3 или более поздней.

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

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

0
Loading