Изменения в поведении адаптера Databricks
Ниже приведены текущие флаги изменения поведения, которые специфичны для dbt-databricks:
| Loading table... |
Используйте information schema для столбцов
Флаг 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 и ниже
Флаг use_info_schema_for_columns по умолчанию имел значение False в версиях 1.9 и 1.10.
При установке этого флага в True для получения метаданных колонок таблиц Unity Catalog использовался information_schema, а не describe extended. Это помогало обходить проблемы, при которых describe extended усекал информацию, если тип данных представлял собой сложную структуру (struct).
Если сложный тип получен в результате обработки JSON с помощью from_json, есть альтернативный вариант: использовать parse_json для создания колонки типа variant.
Тип variant может быть разумной альтернативой с точки зрения производительности и при этом позволяет избежать проблем с усечением типов.
Используйте папку пользователя для блокнотов моделей Python
Начиная с 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 и используется для защиты значительных переработок базовых materialization в dbt-databricks, пока они находятся на экспериментальной стадии.
При установке в True dbt-databricks использует обновлённую логику для всех типов моделей (views, tables, incremental, seeds). Также становятся доступными дополнительные, необязательные параметры конфигурации для более тонкой настройки:
view_update_via_alter— при включении этот параметр пытается обновлять view «на месте» с помощьюalter view, вместо использованияcreate or replace.use_safer_relation_operation— при включении (и если не заданview_update_via_alter) этот параметр делает обновления моделей более безопасными за счёт создания временных relations и использования операций переименования, чтобы рабочая версия таблицы или view не была нарушена в случае ошибок.
Эти параметры не обязательны для получения основных преимуществ данного флага — таких как улучшенная производительность и поддержка колонок и ограничений, — однако они находятся за флагом, поскольку вносят более существенные изменения в поведение materialization.
В версии v1.11.0 этот флаг по-прежнему остаётся выключенным по умолчанию. На основании отзывов о недостатке атомарности (обновлений «всё или ничего») в новой materialization мы не будем включать его автоматически. Вместо этого мы будем искать другие способы получить те же преимущества без потери атомарности.
Изменения в materialization Seed
Materialization для seeds должна иметь минимальные отличия между старой и новой реализациями, так как основное изменение заключается в удалении вызовов методов, которые не поддерживаются Databricks, например операций с транзакциями.
Изменения в materialization View
При установленном в True флаге use_materialization_v2 доступны два параметра конфигурации модели, которые позволяют настраивать поведение materialization для view, если в целевом месте уже существует relation.
view_update_via_alter— обновляет view «на месте» с помощьюalter view, вместо использованияcreate or replace. Это позволяет сохранить историю view, метаданные и улучшает совместимость с Unity Catalog. Пример конфигурации:
models:
- name: market_summary
config:
materialized: view
view_update_via_alter: true
columns:
- name: country
data_tests:
- unique
- not_null
...
Поэтому при изменении описания view его необходимо пересоздавать.
use_safer_relation_operations— при включении (и если не заданview_update_via_alter) этот параметр делает обновления моделей более безопасными за счёт создания новой relation во временном месте, её замены на существующую и последующего удаления старой relation. Пример конфигурации:
models:
- name: market_summary
config:
materialized: view
use_safer_relation_operations: true
columns:
- name: country
data_tests:
- unique
- not_null
...
Хотя этот подход эквивалентен стандартной materialization view в dbt, он создаёт больше объектов UC по сравнению с альтернативами.
Так как в этой конфигурации не используется атомарный create or replace..., история объекта в Unity Catalog может вести себя не так, как вы ожидаете.
Тщательно взвесьте необходимость использования этой настройки в широком масштабе.
Изменения в materialization Table
Как и в случае с view, эти изменения materialization могут привести к росту затрат. Используется больше временных объектов, что соответствует materialization в других адаптерах dbt. Мы считаем эти изменения экспериментальными, в том числе потому, что у нас недостаточно данных для точной оценки влияния на стоимость. При этом преимущества заключаются в улучшении производительности, безопасности и возможности реализовать функции, которые невозможно добавить в текущей materialization.
При установленном в True use_materialization_v2 все пути materialization обновляются. Ключевое изменение — разделение создания таблицы и вставки данных. Это значительно улучшает производительность при установке комментариев к таблицам, поскольку добавление комментариев на этапе создания быстрее, чем использование отдельных 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.
Как и в случае с view, использование дополнительных временных объектов приводит к созданию большего числа объектов UC со своей историей. Тщательно оцените, действительно ли вам необходимо такое поведение.
Изменения в materialization Incremental
Все изменения, описанные в разделе Table materialization, также применимы к incremental materialization.
Также был добавлен новый параметр конфигурации: incremental_apply_config_changes.
Этот параметр позволяет контролировать, должен ли dbt применять изменения таких свойств, как tags, tblproperties и комментарии, во время incremental-запусков. Многие пользователи хотели иметь возможность настраивать метаданные таблиц в Databricks — например, AI-сгенерированные комментарии — без того, чтобы dbt их перезаписывал. Ранее dbt-databricks всегда применял обнаруженные изменения при incremental-запусках.
С materialization V2 теперь можно установить incremental_apply_config_changes в False, чтобы отключить это поведение (по умолчанию он равен True, чтобы сохранить прежнюю логику).
Пример конфигурации:
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 создаёт managed Iceberg таблицу.
Используйте replace on для стратегии insert_overwrite
Флаг use_replace_on_for_insert_overwrite актуален только при использовании incremental-моделей со стратегией insert_overwrite в SQL warehouses. По умолчанию флаг равен True, и используется синтаксис insert into ... replace on для выполнения динамической перезаписи партиций или кластеров — это то же поведение, что и в cluster computes. Если флаг установлен в False, insert_overwrite будет очищать всю таблицу при использовании SQL warehouses. Для cluster computes этот флаг не имеет значения, поскольку поведение insert_overwrite там всегда было динамической перезаписью партиций или кластеров.
Если ранее вы полагались на это поведение для полной замены таблицы без удаления существующих метаданных, оно сохраняется при установленном в True флаге, при условии что вы не используете партиции или liquid clustering.
Эти оптимизации организации данных, как правило, дают заметный эффект только для таблиц размером примерно 1 ТБ и более, и в таких случаях регулярная полная замена данных, вероятно, не является оптимальным подходом.
