Настройки Databricks
Конфигурация таблиц
При материализации модели как table вы можете указать несколько необязательных параметров конфигурации, специфичных для плагина dbt-databricks, в дополнение к стандартным параметрам конфигурации моделей.
В dbt-databricks v1.9 добавлена поддержка параметра конфигурации table_format: iceberg. Попробуйте его уже сейчас в канале выпусков dbt v1 Latest. Все остальные параметры конфигурации таблиц также поддерживались в версии 1.8.
dbt-databricks v1.9 добавляет поддержку конфигурации table_format: iceberg. Попробуйте уже сейчас в ветке релизов "Latest". Все остальные конфигурации таблиц также поддерживались в версии 1.8.
| Параметр | Описание | Обязательный? | Поддержка моделей | Пример |
|---|---|---|---|---|
| table_format | Определяет, нужно ли обеспечивать совместимость материализации с Iceberg | Необязательный | SQL, Python | iceberg |
| use_uniform 1 | Определяет, создает ли dbt управляемую таблицу Iceberg в Unity Catalog (false) или таблицу Delta в формате UniForm с поддержкой чтения через Iceberg (true), когда table_format имеет значение iceberg. Подробнее см. в разделе Поддержка Iceberg в Databricks. | Необязательный | SQL, Python | true |
| file_format 2 | Формат файлов, используемый при создании таблиц (parquet, delta, hudi, csv, json, text, jdbc, orc, hive или libsvm). | Необязательный | SQL, Python | delta |
| location_root | Созданная таблица использует указанный каталог для хранения своих данных. К пути этого каталога добавляется псевдоним таблицы. | Необязательный | SQL, Python | /mnt/root |
| include_full_name_in_path | Определяет, нужно ли использовать полный путь таблицы для уточнения корневого каталога хранения. Если параметр включен, к пути корневого каталога добавляются база данных, схема и псевдоним таблицы. | Необязательный | SQL, Python | true |
| partition_by | Разбивает созданную таблицу на партиции по указанным столбцам. Для каждой партиции создается отдельный каталог. | Необязательный | SQL, Python | date_day |
| liquid_clustered_by3 | Кластеризует созданную таблицу по указанным столбцам. Метод кластеризации основан на функции Liquid Clustering в Delta. Доступен начиная с dbt-databricks 1.6.2. | Необязательный | SQL, Python | date_day |
| auto_liquid_cluster4 | Созданная таблица автоматически кластеризуется средствами Databricks. Доступен начиная с dbt-databricks 1.10.0 | Необязательный | SQL, Python | auto_liquid_cluster: true |
| clustered_by | Каждая партиция созданной таблицы разбивается на фиксированное количество бакетов по указанным столбцам. | Необязательный | SQL, Python | country_code |
| buckets | Количество бакетов, создаваемых при кластеризации | Обязательный, если указан clustered_by | SQL, Python | 8 |
| tblproperties | Свойства таблицы (Tblproperties), задаваемые для созданной таблицы | Необязательный | SQL, Python5 | {'this.is.my.key': 12} |
| databricks_tags | Теги, задаваемые для созданной таблицы | Необязательный | SQL 6 , Python 6 | {'my_tag': 'my_value'} |
| compression | Задает алгоритм сжатия. | Необязательный | SQL, Python | zstd |
| skip_optimize7 | Пропускает операцию OPTIMIZE после материализации этой модели, сохраняя zorder / liquid_clustered_by / auto_liquid_cluster в определении таблицы. Доступен начиная с dbt-databricks 1.12.2. | Необязательный | SQL, Python | skip_optimize: true |
1 use_uniform применяется только к dbt v2. dbt-databricks пока не поддерживает этот параметр — адаптер записывает предупреждение в журнал и игнорирует значение. В dbt-databricks вместо него используйте флаг поведения use_managed_iceberg.
2 Если table_format равен iceberg, в dbt-databricks укажите file_format: delta. Это требование относится только к dbt-databricks. Управляемые Iceberg-таблицы в dbt v2 используют parquet.
3 При настройке liquid_clustered_by адаптер dbt-databricks выполняет OPTIMIZE (Liquid Clustering) после каждого запуска. Чтобы отключить операцию, задайте переменную окружения DATABRICKS_SKIP_OPTIMIZE=true или передайте параметр в команду dbt run --vars "{'databricks_skip_optimize': true}". См. задачу #802.
4 Не используйте liquid_clustered_by и auto_liquid_cluster в одной модели.
5 В PySpark пока нет API для задания tblproperties при создании таблицы, поэтому эта функция предназначена прежде всего для того, чтобы пользователи могли добавлять tblproperties к таблицам, созданным с помощью Python.
6 databricks_tags применяются с помощью операторов ALTER. После применения теги нельзя удалить через dbt-databricks. Для удаления тегов используйте Databricks напрямую или post-hook. Начиная с dbt-databricks v1.12, значения databricks_tags, заданные на нескольких уровнях иерархии конфигурации, объединяются с добавлением значений, а не полностью заменяются значениями с нижнего (более конкретного) уровня.
7 skip_optimize позволяет управлять вызовом OPTIMIZE после материализации для каждой модели отдельно. Поскольку это стандартный параметр конфигурации модели dbt, его также можно задать на уровне папки или проекта через наследование конфигурации. Переменная DATABRICKS_SKIP_OPTIMIZE, действующая на весь запуск, имеет приоритет над skip_optimize: если задать DATABRICKS_SKIP_OPTIMIZE=true (или databricks_skip_optimize: true), переменная отключит OPTIMIZE для всех моделей, и повторно включить его для отдельной модели с помощью skip_optimize: false будет невозможно. Используйте skip_optimize, если хотите оставить OPTIMIZE включённым для большинства моделей, но отключить его для отдельных моделей — например, если вы передаёте выполнение OPTIMIZE механизму Predictive Optimization или запускаете его отдельно по расписанию. См. issue #703.
В dbt-databricks v1.10 появилось несколько новых вариантов конфигурации моделей, доступных при включённом флаге use_materialization_v2.
Подробнее см. документацию по флагам поведения Databricks.
Методы отправки Python
Доступно в версиях 1.9 и выше
В dbt-databricks v1.9 (попробуйте уже сейчас в треке релизов dbt v1 Latest) для submission_method доступны четыре варианта:
all_purpose_cluster: выполняет модель Python либо напрямую через command API, либо загружая блокнот и создавая одноразовый запуск заданияjob_cluster: создаёт новый кластер заданий для выполнения загруженного блокнота в рамках одноразового запуска заданияserverless_cluster: использует бессерверный кластер для выполнения загруженного блокнота в рамках одноразового запуска заданияworkflow_job: создаёт или обновляет многократно используемый рабочий процесс и загруженный блокнот для выполнения на универсальных кластерах, кластерах заданий или бессерверных кластерах.предупреждениеЭтот подход дает вам максимальную гибкость, но создаст постоянные артефакты в Databricks (рабочий процесс), которые пользователи могут запускать вне dbt.
В настоящее время мы находимся в переходном периоде, когда существует разрыв между старыми методами отправки (которые были сгруппированы по вычислениям) и логически различными методами отправки (команда, запуск задания, рабочий процесс).
Таким образом, матрица поддерживаемых конфигураций довольно сложна. В столбце По умолчанию [] означает пустой список, а {} — пустой словарь (значения ещё не заданы).
| Параметр | Назначение | По умолчанию | all_purpose_cluster* | job_cluster | serverless_cluster | workflow_job |
|---|---|---|---|---|---|---|
create_notebook | если задано false, используется Command API, иначе загружается блокнот и запускается задание | false | ✅ | ❌ | ❌ | ❌ |
timeout | максимальное время ожидания выполнения команды или задания | 0 (без ограничения времени) | ✅ | ✅ | ✅ | ✅ |
job_cluster_config | настраивает новый кластер для выполнения модели | {} | ❌ | ✅ | ❌ | ✅ |
access_control_list | определяет, кто может просматривать задание Databricks, выполняющее эту Python-модель, или управлять им | [] | ✅ | ✅ | ✅ | ✅ |
notebook_access_control_list | определяет, кто может просматривать, запускать или редактировать блокнот, который dbt создаёт в Databricks на основе этой Python-модели | [] | ✅ | ✅ | ✅ | ✅ |
packages | список пакетов для установки на кластере, выполняющем модель | [] | ✅ | ✅ | ✅ | ✅ |
index_url | URL для установки packages | None (используется pypi) | ✅ | ✅ | ✅ | ✅ |
additional_libs | напрямую настраивает библиотеки | [] | ✅ | ✅ | ✅ | ✅ |
python_job_config | дополнительная конфигурация заданий и рабочих процессов (см. таблицу ниже) | {} | ✅ | ✅ | ✅ | ✅ |
cluster_id | идентификатор существующего универсального кластера для выполнения модели | None | ✅ | ❌ | ❌ | ✅ |
http_path | путь к существующему универсальному кластеру для выполнения модели | None | ✅ | ❌ | ❌ | ❌ |
* Если create_notebook имеет значение false, поддерживаются только timeout и cluster_id/http_path. Параметр notebook_access_control_list применяется только тогда, когда dbt создаёт блокнот в Databricks.
Когда dbt создаёт блокнот для Python-модели, он копирует код модели в ваше рабочее пространство Databricks и запускает этот блокнот как задание. Исключение — метод отправки all_purpose_cluster, который по умолчанию выполняет код непосредственно на универсальном кластере, не создавая блокнот или задание.
Когда dbt создаёт блокнот и задание, вы можете управлять доступом к каждому из них:
access_control_listопределяет, кто может просматривать задание или управлять им. Уровни разрешений описаны в разделе Списки управления доступом к заданиям.notebook_access_control_listопределяет, кто может открывать блокнот, например для изучения кода после неудачного запуска. Уровни разрешений описаны в разделе Списки управления доступом к блокнотам.
Рекомендуем использовать названия разрешений, которые ожидает API Databricks, например CAN_READ, а не CAN VIEW, как в пользовательском интерфейсе.
С введением метода отправки workflow_job, мы выбрали дальнейшую сегрегацию конфигурации отправки модели Python под верхнеуровневую конфигурацию, названную python_job_config. Это позволяет конфигурационным опциям для заданий и рабочих процессов быть пространственно именованными таким образом, чтобы они не мешали другим конфигурациям модели, что позволяет нам быть гораздо более гибкими в том, что поддерживается для выполнения заданий.
Матрица поддержки для этой функции разделена на workflow_job и все остальные (предполагая all_purpose_cluster с create_notebook==true).
Каждая опция конфигурации, указанная ниже, должна быть вложена под python_job_config:
| Конфигурация | Использование | По умолчанию | workflow_job | Все остальные |
|---|---|---|---|---|
name | Имя, которое будет присвоено (или использовано для поиска) созданному рабочему процессу | None | ✅ | ❌ |
grants | Упрощенный способ указать контроль доступа для рабочего процесса | {} | ✅ | ✅ |
existing_job_id | Идентификатор для использования при поиске созданного рабочего процесса (вместо name) | None | ✅ | ❌ |
post_hook_tasks | Задачи, которые будут включены после выполнения блокнота модели | [] | ✅ | ❌ |
additional_task_settings | Дополнительная конфигурация задачи, которая будет включена в задачу модели | {} | ✅ | ❌ |
| Другие настройки запуска задания | Конфигурация будет скопирована в запрос, вне задачи модели | None | ❌ | ✅ |
| Другие настройки рабочего процесса | Конфигурация будет скопирована в запрос, вне задачи модели | None | ✅ | ❌ |
Этот пример использует новые опции конфигурации из предыдущей таблицы:
models:
- name: my_model
config:
submission_method: workflow_job
# Определите кластер заданий для создания для выполнения этого рабочего процесса
# В качестве альтернативы можно указать cluster_id для использования существующего кластера или не указывать ни одного, чтобы использовать безсерверный кластер
job_cluster_config:
spark_version: "15.3.x-scala2.12"
node_type_id: "rd-fleet.2xlarge"
runtime_engine: "{{ var('job_cluster_defaults.runtime_engine') }}"
data_security_mode: "{{ var('job_cluster_defaults.data_security_mode') }}"
autoscale: { "min_workers": 1, "max_workers": 4 }
python_job_config:
# Эти настройки передаются, как есть, в запрос
email_notifications: { on_failure: ["me@example.com"] }
max_retries: 2
name: my_workflow_name
# Переопределите настройки для задачи dbt вашей модели. Например, вы можете
# изменить ключ задачи
additional_task_settings: { "task_key": "my_dbt_task" }
# Определите задачи для выполнения до/после модели
# Этот пример предполагает, что вы уже загрузили блокнот в /my_notebook_path для выполнения оптимизации и очистки
post_hook_tasks:
[
{
"depends_on": [{ "task_key": "my_dbt_task" }],
"task_key": "OPTIMIZE_AND_VACUUM",
"notebook_task":
{ "notebook_path": "/my_notebook_path", "source": "WORKSPACE" },
},
]
# Упрощенная структура, вместо необходимости указывать разрешения отдельно для каждого пользователя
grants:
view: [{ "group_name": "marketing-team" }]
run: [{ "user_name": "other_user@example.com" }]
manage: []
Настройка колонок
Доступно в версиях 1.10 и выше
При материализации моделей различных типов вы можете указывать несколько необязательных конфигураций на уровне колонок, которые специфичны для плагина dbt-databricks, в дополнение к стандартным настройкам колонок. Поддержка тегов колонок и масок колонок была добавлена в dbt-databricks версии 1.10.4.
| Параметр | Описание | Обязательный? | Поддерживаемые модели | Поддерживаемые материализации | Пример |
|---|---|---|---|---|---|
| databricks_tags | Теги для отдельных столбцов | Нет | SQL†, Python† | Table, Incremental, Materialized View, Streaming Table | {'data_classification': 'pii'} |
| column_mask | Маска столбца для динамического маскирования. Принимает function и необязательное поле using_columns* | Нет | SQL, Python | Table, Incremental, Streaming Table | {'function': 'my_catalog.my_schema.mask_email'} |
* В using_columns поддерживаются все типы параметров из раздела Параметры маски столбца Databricks.
† Теги databricks_tags применяются через инструкции ALTER. После применения их нельзя удалить средствами dbt-databricks. Удалите теги в Databricks или через post-hook. Начиная с dbt-databricks v1.12, теги с разных уровней конфигурации объединяются, а более конкретный уровень больше не заменяет весь набор вышестоящего.
В примере используются настройки столбцов из таблицы выше:
models:
- name: customers
columns:
- name: customer_id
databricks_tags:
data_classification: "public"
- name: email
databricks_tags:
data_classification: "pii"
column_mask:
function: my_catalog.my_schema.mask_email
using_columns: "customer_id, 'literal string'"
Настройка фильтров строк
Доступно в версиях 1.12 и выше
Вы можете задать row_filter, чтобы применить к модели фильтр строк Unity Catalog, ограничивающий строки, возвращаемые запросом, с помощью SQL UDF. dbt применяет фильтр с помощью предложения WITH ROW FILTER при создании отношения и выполняет ALTER ... SET ROW FILTER / ALTER ... DROP ROW FILTER для добавления, обновления или удаления фильтра при последующих запусках.
row_filter — необязательная конфигурация уровня модели. Если вы задаёте её, оба следующих свойства обязательны:
| Свойство | Описание | Обязательно? | Пример |
|---|---|---|---|
| function | UDF для фильтрации строк, которую нужно применить. Укажите либо неквалифицированное имя (dbt дополнит его каталогом и схемой модели), либо полностью квалифицированное имя catalog.schema.function. dbt отклоняет имя из двух частей schema.function как неоднозначное. | Да | region_filter |
| columns | Столбцы, передаваемые в качестве аргументов функции фильтрации. Можно указать одну строку или список. Обязательно, если задано свойство function. | Да | [region] |
Фильтры строк поддерживаются для материализаций table, incremental, materialized_view и streaming_table. Они не поддерживаются для обычных представлений и отношений в Hive Metastore. Настройка row_filter для любого из этих двух типов объектов вызывает ошибку компиляции.
В этом примере к модели применяется фильтр строк:
models:
- name: orders
config:
row_filter:
function: my_catalog.my_schema.region_filter
columns: [region]
Инкрементальные модели
Доступно в версиях 1.9 и выше
dbt-databricks v1.11.0 требует Databricks Runtime 12.2 LTS или выше для инкрементальных моделей
В этой версии добавлено исправление проблемы с несоответствием порядка колонок в инкрементальных моделях за счёт использования синтаксиса Databricks INSERT BY NAME (доступен начиная с DBR 12.2). Это предотвращает повреждение данных, которое могло возникать при изменении порядка колонок в моделях с настройкой on_schema_change: sync_all_columns.
Если вы используете более старую версию runtime:
- Зафиксируйте версию
dbt-databricksна1.10.x - Или обновитесь до DBR 12.2 LTS или выше
Это ломающее изменение затрагивает все стратегии инкрементальной загрузки: append, insert_overwrite, replace_where, delete+insert и merge (через создание промежуточной таблицы).
Подробнее об изменениях в v1.11.0 см. в dbt-databricks v1.11.0 changelog.
Плагин dbt-databricks в значительной степени опирается на конфигурацию incremental_strategy. Эта настройка определяет, как инкрементальная материализация будет собирать модель при запусках после первого. Она может принимать одно из шести значений:
append: Вставляет новые записи, не обновляя и не перезаписывая существующие данные.insert_overwrite: Если заданpartition_by, перезаписывает соответствующие партиции в таблица новыми данными. Еслиpartition_byне указан, перезаписывает всю таблицу новыми данными.merge(по умолчанию; только для форматов файлов Delta и Hudi): Сопоставляет записи на основеunique_key, обновляя существующие записи и вставляя новые. (Еслиunique_keyне указан, все новые данные вставляются — аналогичноappend.)replace_where(только для формата файлов Delta): Сопоставляет записи на основеincremental_predicates, заменяя все записи в существующей таблице, которые соответствуют предикатам, на записи из новых данных с теми же предикатами. (Еслиincremental_predicatesне указаны, все новые данные вставляются — аналогичноappend.)delete+insert(только для формата файлов Delta, доступно в v1.11+): Сопоставляет записи на основе обязательногоunique_key, удаляет совпадающие записи и вставляет новые. Дополнительно может применяться фильтрация с помощьюincremental_predicates.microbatch(только для формата файлов Delta): Реализует стратегию microbatch, используяreplace_whereс предикатами, которые генерируются на основеevent_time.
Каждая из этих стратегий имеет свои плюсы и минусы, которые мы обсудим ниже. Как и в случае любой конфигурации модели, incremental_strategy может быть указана в dbt_project.yml или в блоке config() файла модели.
Стратегия append
Следуя стратегии append, dbt выполнит оператор insert into со всеми новыми данными. Привлекательность этой стратегии заключается в том, что она проста и функциональна на всех платформах, типах файлов, методах подключения и версиях Apache Spark. Однако эта стратегия не может обновлять, перезаписывать или удалять существующие данные, поэтому она, вероятно, будет вставлять дублирующиеся записи для многих источников данных.
- Исходный код
- Код выполнения
{{ config(
materialized='incremental',
incremental_strategy='append',
) }}
-- Все строки, возвращаемые этим запросом, будут добавлены к существующей таблице
select * from {{ ref('events') }}
{% if is_incremental() %}
where event_ts > (select max(event_ts) from {{ this }})
{% endif %}
create temporary view databricks_incremental__dbt_tmp as
select * from analytics.events
where event_ts >= (select max(event_ts) from {{ this }})
;
insert into table analytics.databricks_incremental
select `date_day`, `users` from databricks_incremental__dbt_tmp
Стратегия insert_overwrite
Стратегия insert_overwrite обновляет данные в таблице, заменяя существующие записи, а не просто добавляя новые. Эта стратегия наиболее эффективна, когда она указана вместе с параметром partition_by или liquid_clustered_by в конфигурации модели — это помогает определить конкретные партиции или кластеры, на которые влияет ваш запрос. dbt выполнит атомарный оператор insert into ... replace on, который динамически заменяет все партиции или кластеры, затронутые запросом, вместо перестроения всей таблицы целиком.
Важно! При использовании этой инкрементальной стратегии обязательно повторно выбирайте (re-select) все релевантные данные для соответствующей партиции или кластера.
При использовании liquid_clustered_by ключи replace on будут совпадать с ключами liquid_clustered_by (аналогично поведению partition_by).
Если задать для use_replace_on_for_insert_overwrite значение true (в SQL-хранилищах или при использовании кластерных вычислительных ресурсов), dbt динамически перезаписывает партиции и заменяет только те партиции или кластеры, которые возвращает запрос модели. dbt выполняет оператор insert overwrite с partitionOverwriteMode='dynamic', что помогает сократить количество ненужных перезаписей и повысить производительность.
Если задать для use_replace_on_for_insert_overwrite значение false в SQL-хранилищах, dbt полностью очищает таблицу перед вставкой новых данных. При этом все строки в таблице заменяются при каждом запуске модели, что может увеличить время выполнения и затраты при работе с большими наборами данных
Если вы не укажете partition_by или liquid_clustered_by, стратегия insert_overwrite будет атомарно заменять всё содержимое таблицы, перезаписывая все существующие данные только новыми записями. При этом схема столбцов таблицы остаётся неизменной. В некоторых ограниченных случаях такое поведение может быть желательным, так как оно минимизирует простой во время перезаписи содержимого таблицы. Эта операция сопоставима с выполнением truncate и insert в других базах данных. Для атомарной замены таблиц в формате Delta вместо этого используйте материализацию table (которая выполняет create or replace).
- Исходный код
- Код выполнения
{{ config(
materialized='incremental',
partition_by=['date_day'],
file_format='parquet'
) }}
/*
Каждый раздел, возвращаемый этим запросом, будет перезаписан
при выполнении этой модели
*/
with new_events as (
select * from {{ ref('events') }}
{% if is_incremental() %}
where date_day >= date_add(current_date, -1)
{% endif %}
)
select
date_day,
count(*) as users
from new_events
group by 1
create temporary view databricks_incremental__dbt_tmp as
with new_events as (
select * from analytics.events
where date_day >= date_add(current_date, -1)
)
select
date_day,
count(*) as users
from events
group by 1
;
insert overwrite table analytics.databricks_incremental
partition (date_day)
select `date_day`, `users` from databricks_incremental__dbt_tmp
Стратегия merge
Инкрементальная стратегия merge требует:
file_format: delta или hudi- Databricks Runtime 5.1 и выше для формата файла delta
- Apache Spark для формата файла hudi
Адаптер Databricks выполнит атомарный оператор merge, аналогичный поведению слияния по умолчанию в Snowflake и BigQuery. Если указан unique_key (рекомендуется), dbt обновит старые записи значениями из новых записей, которые совпадают по ключевому столбцу. Если unique_key не указан, dbt пропустит критерии совпадения и просто вставит все новые записи (аналогично стратегии append).
Указание merge в качестве инкрементальной стратегии является необязательным, так как это стратегия по умолчанию, используемая, когда никакая не указана.
- Исходный код
- Код выполнения
{{ config(
materialized='incremental',
file_format='delta', # или 'hudi'
unique_key='user_id',
incremental_strategy='merge'
) }}
with new_events as (
select * from {{ ref('events') }}
{% if is_incremental() %}
where date_day >= date_add(current_date, -1)
{% endif %}
)
select
user_id,
max(date_day) as last_seen
from events
group by 1
create temporary view merge_incremental__dbt_tmp as
with new_events as (
select * from analytics.events
where date_day >= date_add(current_date, -1)
)
select
user_id,
max(date_day) as last_seen
from events
group by 1
;
merge into analytics.merge_incremental as DBT_INTERNAL_DEST
using merge_incremental__dbt_tmp as DBT_INTERNAL_SOURCE
on DBT_INTERNAL_SOURCE.user_id = DBT_INTERNAL_DEST.user_id
when matched then update set *
when not matched then insert *
Начиная с версии 1.9, поведение merge можно изменить с помощью следующих дополнительных параметров конфигурации:
target_alias,source_alias: Алиасы для целевой и исходной таблиц, которые позволяют более наглядно описывать условия merge. По умолчанию используютсяDBT_INTERNAL_DESTиDBT_INTERNAL_SOURCEсоответственно.skip_matched_step: Если установлено вtrue, секцияmatchedв операторе merge не будет включена.skip_not_matched_step: Если установлено вtrue, секцияnot matchedне будет включена.matched_condition: Условие, применяемое к секцииWHEN MATCHED. Для написания условного выражения следует использоватьtarget_aliasиsource_alias, например:DBT_INTERNAL_DEST.col1 = hash(DBT_INTERNAL_SOURCE.col2, DBT_INTERNAL_SOURCE.col3). Это условие дополнительно ограничивает набор строк, считающихся совпавшими.not_matched_condition: Условие, применяемое к секцииWHEN NOT MATCHED [BY TARGET]. Это условие дополнительно ограничивает набор строк в целевой таблице, которые не совпадают с источником и будут вставлены в результирующую таблицу.not_matched_by_source_condition: Условие, применяемое как дополнительный фильтр в секцииWHEN NOT MATCHED BY SOURCE. Используется только совместно сnot_matched_by_source_action.not_matched_by_source_action: Действие, которое выполняется при выполнении условия. Настраивается как выражение. Например:not_matched_by_source_action: "update set t.attr1 = 'deleted', t.tech_change_ts = current_timestamp()".merge_with_schema_evolution: Если установлено вtrue, оператор merge будет включать секциюWITH SCHEMA EVOLUTION.
Для получения более подробной информации о значении каждого условия слияния, пожалуйста, обратитесь к документации Databricks.
Ниже приведен пример, демонстрирующий использование этих новых опций:
- Исходный код
- Код выполнения
{{ config(
materialized = 'incremental',
unique_key = 'id',
incremental_strategy='merge',
target_alias='t',
source_alias='s',
matched_condition='t.tech_change_ts < s.tech_change_ts',
not_matched_condition='s.attr1 IS NOT NULL',
not_matched_by_source_condition='t.tech_change_ts < current_timestamp()',
not_matched_by_source_action='delete',
merge_with_schema_evolution=true
) }}
select
id,
attr1,
attr2,
tech_change_ts
from
{{ ref('source_table') }} as s
create temporary view merge_incremental__dbt_tmp as
select
id,
attr1,
attr2,
tech_change_ts
from upstream.source_table
;
merge
with schema evolution
into
target_table as t
using (
select
id,
attr1,
attr2,
tech_change_ts
from
source_table as s
)
on
t.id <=> s.id
when matched
and t.tech_change_ts < s.tech_change_ts
then update set
id = s.id,
attr1 = s.attr1,
attr2 = s.attr2,
tech_change_ts = s.tech_change_ts
when not matched
and s.attr1 IS NOT NULL
then insert (
id,
attr1,
attr2,
tech_change_ts
) values (
s.id,
s.attr1,
s.attr2,
s.tech_change_ts
)
when not matched by source
and t.tech_change_ts < current_timestamp()
then delete
Стратегия replace_where
Инкрементальная стратегия replace_where требует:
file_format: delta- Databricks Runtime 12.0 и выше
dbt выполнит атомарный оператор replace where, который избирательно перезаписывает данные, соответствующие одному или нескольким incremental_predicates, указанным в виде строки или массива. Только строки, соответствующие предикатам, будут вставлены. Если incremental_predicates не указаны, dbt выполнит атомарную вставку, как в случае append.
replace_where вставляет данные в столбцы в порядке их предоставления, а не по имени столбца. Если вы измените порядок столбцов и данные совместимы с существующей схемой, вы можете незаметно вставить значения в неожиданный столбец. Если входные данные несовместимы с существующей схемой, вы получите ошибку.
- Исходный код
- Код выполнения
{{ config(
materialized='incremental',
file_format='delta',
incremental_strategy = 'replace_where'
incremental_predicates = 'user_id >= 10000' # Никогда не заменяйте пользователей с id < 10000
) }}
with new_events as (
select * from {{ ref('events') }}
{% if is_incremental() %}
where date_day >= date_add(current_date, -1)
{% endif %}
)
select
user_id,
max(date_day) as last_seen
from events
group by 1
create temporary view replace_where__dbt_tmp as
with new_events as (
select * from analytics.events
where date_day >= date_add(current_date, -1)
)
select
user_id,
max(date_day) as last_seen
from events
group by 1
;
insert into analytics.replace_where_incremental
replace where user_id >= 10000
table `replace_where__dbt_tmp`
Стратегия delete+insert
Доступно в версиях 1.11 или выше
Инкрементальная стратегия delete+insert требует:
file_format: delta- Обязательной конфигурации
unique_key - Databricks Runtime 12.2 LTS или выше
Стратегия delete+insert проще, чем merge, когда нужно заменить целые записи вместо обновления отдельных столбцов. Она работает в два шага:
- Удаление: из целевой таблицы удаляются все строки, чей
unique_keyсовпадает с ключом в новых данных. - Вставка: все новые строки из промежуточных данных вставляются в целевую таблицу.
Эта стратегия полезна, если:
- Нужно заменить целые записи, не обновляя отдельные столбцы.
- Бизнес-логика требует сначала удалить, а затем заново вставить запись.
- Для полной замены записей нужна более простая инкрементальная стратегия, чем
merge.
При использовании Databricks Runtime версии 17.1 или выше dbt применяет эффективный синтаксис INSERT INTO ... REPLACE ON для атомарного выполнения этой операции. Для более старых версий runtime dbt выполняет отдельные операторы DELETE и INSERT.
При необходимости вы можете использовать incremental_predicates, чтобы дополнительно отфильтровать обрабатываемые записи, получив больший контроль над тем, какие строки удаляются и вставляются.
- Исходный код
- Выполнение (DBR 17.1+)
- Выполнение (DBR < 17.1)
{{ config(
materialized='incremental',
file_format='delta',
incremental_strategy='delete+insert',
unique_key='user_id',
incremental_predicates='user_id >= 10000' # Never delete/insert users with ids < 10000
) }}
with new_events as (
select * from {{ ref('events') }}
{% if is_incremental() %}
where date_day >= date_add(current_date, -1)
{% endif %}
)
select
user_id,
max(date_day) as last_seen
from new_events
group by 1
create temporary view delete_insert_incremental__dbt_tmp as
with new_events as (
select * from analytics.events
where date_day >= date_add(current_date, -1)
)
select
user_id,
max(date_day) as last_seen
from new_events
group by 1
;
insert into table analytics.delete_insert_incremental as target
replace on (target.user_id <=> temp.user_id)
(select `user_id`, `last_seen`
from delete_insert_incremental__dbt_tmp where user_id >= 10000) as temp
create temporary view delete_insert_incremental__dbt_tmp as
with new_events as (
select * from analytics.events
where date_day >= date_add(current_date, -1)
)
select
user_id,
max(date_day) as last_seen
from new_events
group by 1
;
-- Step 1: Delete matching rows
delete from analytics.delete_insert_incremental
where analytics.delete_insert_incremental.user_id IN (SELECT user_id FROM delete_insert_incremental__dbt_tmp)
and user_id >= 10000;
-- Step 2: Insert new rows
insert into analytics.delete_insert_incremental by name
select `user_id`, `last_seen`
from delete_insert_incremental__dbt_tmp
where user_id >= 10000
Стратегия microbatch
Доступно в версиях 1.9 и выше
Адаптер Databricks реализует стратегию microbatch, используя replace_where. Обратите внимание на требования и предупреждения, указанные выше для replace_where. Дополнительную информацию об этой стратегии см. на странице справки microbatch.
В следующем примере в таблице events добавлен столбец event_time, называемый ts, в ее схеме.
- Исходный код
- Код выполнения
{{ config(
materialized='incremental',
file_format='delta',
incremental_strategy = 'microbatch'
event_time='date' # Используйте 'date' как зерно для этой таблицы микропакетов
) }}
with new_events as (
select * from {{ ref('events') }}
)
select
user_id,
date,
count(*) as visits
from events
group by 1, 2
create temporary view replace_where__dbt_tmp as
with new_events as (
select * from (select * from analytics.events where ts >= '2024-10-01' and ts < '2024-10-02')
)
select
user_id,
date,
count(*) as visits
from events
group by 1, 2
;
insert into analytics.replace_where_incremental
replace where CAST(date as TIMESTAMP) >= '2024-10-01' and CAST(date as TIMESTAMP) < '2024-10-02'
table `replace_where__dbt_tmp`
Настройка моделей Python
Адаптер Databricks поддерживает Python-модели. Databricks использует PySpark в качестве фреймворка обработки для этих моделей.
Методы отправки: Databricks поддерживает несколько различных механизмов отправки кода PySpark, каждый из которых имеет свои относительные преимущества. Одни лучше подходят для итеративной разработки, другие — для более дешёвых продакшн-развёртываний. Доступны следующие варианты:
all_purpose_cluster(по умолчанию): dbt будет запускать вашу Python-модель, используя идентификатор кластера, настроенный какclusterв вашем профиле подключения или для конкретной модели. Эти кластеры дороже, но значительно более отзывчивы. Мы рекомендуем использовать интерактивный all-purpose кластер для более быстрой итерации при разработке.create_notebook: True: dbt загрузит скомпилированный PySpark-код вашей модели в ноутбук в пространстве имён/Shared/dbt_python_model/{schema}, где{schema}— это настроенная схема модели, и выполнит этот ноутбук с использованием all-purpose кластера. Преимущество этого подхода в том, что вы можете легко открыть ноутбук в интерфейсе Databricks для отладки или тонкой настройки сразу после выполнения модели. Не забудьте скопировать все изменения обратно в код вашей dbt-модели.pyперед повторным запуском.create_notebook: False(по умолчанию): dbt будет использовать Command API, который работает немного быстрее.
job_cluster: dbt загрузит скомпилированный PySpark-код вашей модели в ноутбук в пространстве имён/Shared/dbt_python_model/{schema}, где{schema}— это настроенная схема модели, и выполнит этот ноутбук, используя краткоживущий jobs-кластер. Для каждой Python-модели Databricks потребуется поднять кластер, выполнить PySpark-трансформацию модели, а затем остановить кластер. Поэтому job-кластеры требуют больше времени до и после выполнения модели, но они также дешевле, поэтому мы рекомендуем их для длительно выполняющихся Python-моделей в продакшене. Чтобы использовать метод отправкиjob_cluster, ваша модель должна быть настроена сjob_cluster_config, который определяет свойства ключ-значение дляnew_cluster, как описано в JobRunsSubmit API.
Вы можете настроить submission_method для каждой модели всеми стандартными способами задания конфигурации:
def model(dbt, session):
dbt.config(
submission_method="all_purpose_cluster",
create_notebook=True,
cluster_id="abcd-1234-wxyz"
)
...
models:
- name: my_python_model
config:
submission_method: job_cluster
job_cluster_config:
spark_version: ...
node_type_id: ...
# dbt_project.yml
models:
project_name:
subfolder:
# set defaults for all .py models defined in this subfolder
+submission_method: all_purpose_cluster
+create_notebook: False
+cluster_id: abcd-1234-wxyz
Если конфигурация не задана, dbt-spark будет использовать встроенные значения по умолчанию: all-purpose кластер (на основе cluster в вашем профиле подключения) без создания ноутбука. Адаптер dbt-databricks по умолчанию будет использовать кластер, настроенный в http_path. Мы рекомендуем явно настраивать кластеры для Python-моделей в проектах Databricks.
Установка пакетов: если используются универсальные кластеры, установите на них пакеты, нужные для выполнения моделей Python.
Связанная документация:
Выбор вычислительных ресурсов для каждой модели
Начиная с версии 1.7.2, вы можете назначать, какой вычислительный ресурс использовать для каждой модели. Для SQL-моделей вы можете выбрать SQL Warehouse (безсерверный или предоставленный) или кластер общего назначения. Для получения подробной информации о том, как эта функция взаимодействует с моделями Python, см. Указание вычислительных ресурсов для моделей Python.
Это необязательная настройка. Если вы не настроите это, как показано ниже, мы будем использовать вычислительные ресурсы, указанные в http_path в верхнем уровне раздела output в вашем профиле. Это также вычислительные ресурсы, которые будут использоваться для задач, не связанных с конкретной моделью, таких как сбор метаданных для всех таблиц в схеме.
Чтобы воспользоваться этой возможностью, вам нужно будет добавить блоки вычислений в ваш профиль:
profile-name:
target: target-name # это целевой объект по умолчанию
outputs:
target-name:
type: databricks
catalog: optional catalog name if you are using Unity Catalog
schema: schema name # Обязательно
host: yourorg.databrickshost.com # Обязательно
### Этот путь используется как вычислительный ресурс по умолчанию
http_path: /sql/your/http/path # Обязательно
### Новый раздел вычислений
compute:
### Имя, которое вы будете использовать для ссылки на альтернативный вычислительный ресурс
Compute1:
http_path: '/sql/your/http/path' # Обязательно для каждого альтернативного вычислительного ресурса
### Третий именованный вычислительный ресурс, используйте любое имя, которое вам нравится
Compute2:
http_path: '/some/other/path' # Обязательно для каждого альтернативного вычислительного ресурса
...
target-name: # дополнительные целевые объекты
...
### Для каждого целевого объекта вам нужно определить те же вычислительные ресурсы,
### но вы можете указать разные пути
compute:
### Имя, которое вы будете использовать для ссылки на альтернативный вычислительный ресурс
Compute1:
http_path: '/sql/your/http/path' # Обязательно для каждого альтернативного вычислительного ресурса
### Третий именованный вычислительный ресурс, используйте любое имя, которое вам нравится
Compute2:
http_path: '/some/other/path' # Обязательно для каждого альтернативного вычислительного ресурса
...
Новый раздел вычислений представляет собой карту имен, выбранных пользователем, к объектам с свойством http_path. Каждый вычислительный ресурс имеет ключ, который используется в определении/конфигурации модели для указания, какой вычислительный ресурс вы хотите использовать для этой модели/выбора моделей. Мы рекомендуем выбирать имя, которое легко распознается как используемые вами вычислительные ресурсы, например, имя вычислительного ресурса в интерфейсе Databricks.
Вам нужно использовать один и тот же набор имен для вычислительных ресурсов во всех ваших выходных данных, хотя вы можете предоставить разные http_paths, что позволяет использовать разные вычислительные ресурсы в разных сценариях развертывания.
Чтобы настроить это в dbt, используйте функцию расширенных атрибутов в нужных окружениях:
compute:
Compute1:
http_path: /SOME/OTHER/PATH
Compute2:
http_path: /SOME/OTHER/PATH
Указание вычислительных ресурсов для моделей
Как и многие другие параметры конфигурации, вычислительные ресурсы (compute) для модели можно указать несколькими способами, используя databricks_compute.
В файле dbt_project.yml выбранный compute можно задать сразу для всех моделей в определённом каталоге:
...
models:
+databricks_compute: "Compute1" # используйте склад/кластер `Compute1` для всех моделей в проекте...
my_project:
clickstream:
+databricks_compute: "Compute2" # ...за исключением моделей в папке `clickstream`, которые будут использовать `Compute2`.
snapshots:
+databricks_compute: "Compute1" # все модели Snapshot настроены на использование `Compute1`.
Для отдельной модели вычислительные ресурсы могут быть указаны в конфигурации модели в вашем файле схемы.
models:
- name: table_model
config:
databricks_compute: Compute1
columns:
- name: id
data_type: int
В качестве альтернативы хранилище данных можно указать в конфигурации SQL‑файла модели.
{{
config(
materialized='table',
databricks_compute='Compute1'
)
}}
select * from {{ ref('seed') }}
Чтобы убедиться, что указанные вычислительные ресурсы используются, ищите строки в вашем dbt.log, такие как:
Адаптер Databricks ... использует вычислительный ресурс по умолчанию.
или
Адаптер Databricks ... использует вычислительный ресурс <имя вычислительного ресурса>.
Указание вычислительных ресурсов для моделей Python
Материализация python‑модели требует выполнения как SQL, так и Python‑кода.
В частности, если ваша python‑модель является инкрементальной, текущий шаблон выполнения предполагает запуск Python для создания staging‑таблицы, которая затем объединяется (merge) с целевой таблицей с помощью SQL.
Python‑код должен выполняться на all purpose кластере (или serverless кластере, см. Python Submission Methods), тогда как SQL‑код может выполняться как на all purpose кластере, так и на SQL Warehouse.
Когда вы указываете databricks_compute для python‑модели, в настоящее время вы задаёте только то вычислительное окружение, которое используется при выполнении SQL, специфичного для модели.
Если вы хотите использовать другое вычислительное окружение для выполнения самого Python‑кода, необходимо указать альтернативный compute в конфигурации модели.
Например:
def model(dbt, session):
dbt.config(
http_path="sql/protocolv1/..."
)
Если ваш вычислительный ресурс по умолчанию является SQL-складом, вам нужно будет указать http_path кластера общего назначения таким образом.
Сохранение описаний моделей
Поддерживается сохранение документации на уровне relation. Для получения дополнительной информации о настройке сохранения документации см. документацию.
Когда опция persist_docs настроена соответствующим образом, вы сможете
увидеть описания моделей в поле Comment команды describe [table] extended
или show table extended in [database] like '*'.
Теги запросов
Доступно в версиях 1.11 и выше
Теги запросов позволяют добавлять к SQL-запросам в Databricks собственные метаданные в виде пар ключ–значение. Они видны в системных таблицах и истории запросов, где помогают отслеживать расходы, отлаживать запросы и проводить аудит.
Теги запросов могут быть доступны не во всех рабочих областях Databricks. Актуальные сведения см. в документации Databricks.
В dbt-databricks теги запросов можно задать на уровне подключения в профиле и на уровне отдельной модели. При запуске dbt автоматически добавляет теги с метаданными, например именем модели и версией dbt.
Теги запросов по умолчанию
dbt-databricks автоматически добавляет к каждому запросу следующие теги:
| Ключ тега | Описание |
|---|---|
@@dbt_model_name | Имя выполняемой модели |
@@dbt_core_version | Версия dbt |
@@dbt_databricks_version | Версия dbt-databricks |
@@dbt_materialized | Тип материализации: таблица, представление, инкрементальная и т. д. |
Пользовательские теги не могут переопределить эти зарезервированные ключи.
Настройка тегов запросов
Теги задаются на уровне подключения в профиле или на уровне модели в её настройках. Теги модели имеют приоритет над тегами подключения.
Теги запросов на уровне подключения
Чтобы задать теги для всех запросов подключения, добавьте в profiles.yml параметр query_tags в виде строки JSON:
your_profile_name:
target: dev
outputs:
dev:
type: databricks
catalog: my_catalog
schema: my_schema
host: yourorg.databrickshost.com
http_path: /sql/your/http/path
token: dapiXXXXXXXXXXXXXXXXXXXXXXX
query_tags: '{"team": "analytics", "project": "customer_360"}'
Теги запросов на уровне модели
Чтобы задать теги для отдельной модели, используйте настройку query_tags:
{{ config(
query_tags = {'cost_center': 'marketing', 'priority': 'high'}
) }}
select * from {{ ref('upstream_model') }}
Теги для групп моделей можно задать в dbt_project.yml:
models:
my_project:
marketing:
+query_tags: {'department': 'marketing'}
finance:
+query_tags: {'department': 'finance'}
Приоритет и объединение тегов
Если теги заданы на нескольких уровнях, они объединяются в следующем порядке приоритета:
- Теги модели из
config()илиschema.yml. - Теги подключения из
profiles.yml. - Теги по умолчанию, добавленные dbt автоматически.
Если один ключ задан на нескольких уровнях, используется значение с наивысшим приоритетом.
Если задать query_tags на уровне модели в config() или schema.yml, они заменят настройки query_tags из dbt_project.yml целиком. Так dbt обрабатывает параметры конфигурации типа «словарь».
Чтобы обойти это ограничение, задайте query_tags в профиле подключения (profiles.yml). dbt-databricks объединяет теги подключения с тегами модели. Общие теги можно задать один раз в профиле, а в модели добавить или переопределить нужные ключи.
Рекомендуемый подход:
- Задайте общие теги, например команду, проект и среду, в
query_tagsпрофиля. - Для тегов отдельной модели используйте
query_tagsна уровне модели.
Ограничения
- Не более 20 тегов: учитываются все теги запросов, включая добавленные по умолчанию.
- Длина значения: не более 128 символов. Более длинные значения тегов по умолчанию автоматически обрезаются.
- Специальные символы: обратная косая черта (
\), запятая (,) и двоеточие (:) в значениях экранируются автоматически. При этом в журнал пишется предупреждение. - Зарезервированные ключи:
@@dbt_model_name,@@dbt_core_version,@@dbt_databricks_versionи@@dbt_materializedнельзя использовать в пользовательских тегах.
Просмотр тегов запросов
Теги запросов отображаются в системных таблицах и истории запросов Databricks. Как запрашивать и анализировать их, описано в документации Databricks.
Конфигурации формата файлов по умолчанию
Чтобы получить доступ к расширенным функциям инкрементальных стратегий, таким как
снимки и инкрементальная стратегия merge, вы захотите
использовать формат файлов Delta или Hudi в качестве формата файлов по умолчанию при материализации моделей как таблиц.
Это довольно удобно сделать, установив верхнеуровневую конфигурацию в вашем файле проекта:
models:
+file_format: delta # или hudi
seeds:
+file_format: delta # или hudi
snapshots:
+file_format: delta # или hudi
Материализованные представления и стриминговые таблицы
Материализованные представления и потоковые таблицы — это альтернативы инкрементальным таблицам, работающие на базе Delta Live Tables.
Дополнительную информацию и примеры использования см. в разделе Что такое Delta Live Tables?
Чтобы использовать эти стратегии материализации, вам потребуется рабочее пространство, включенное для Unity Catalog и безсерверных SQL-складов.
{{ config(
materialized = 'materialized_view'
) }}
или
{{ config(
materialized = 'streaming_table'
) }}
Мы поддерживаем on_configuration_change для большинства доступных свойств этих материализаций. В следующей таблице приведена сводная информация о поддерживаемых конфигурациях. Подробнее о каждой конфигурации см. в разделе Сведения о конфигурациях:
| Концепция Databricks | Имя конфига | Поддержка MV/ST | Версия |
|---|---|---|---|
| PARTITIONED BY | partition_by | MV/ST | Все |
| CLUSTER BY | liquid_clustered_by | MV/ST | v1.11+ |
| COMMENT | description | MV/ST | Все |
| TBLPROPERTIES | tblproperties | MV/ST | Все |
| TAGS | databricks_tags | MV/ST | v1.11+ |
| SCHEDULE CRON | schedule: { 'cron': '\<cron schedule\>', 'time_zone_value': '\<time zone value\>' } | MV/ST | Все |
| SCHEDULE EVERY | schedule: { 'every': '\<n\> \<unit\>' } | MV/ST | v1.12+ |
| TRIGGER ON UPDATE | schedule: { 'on_update': true, 'at_most_every': '\<n\> \<unit\>' } | MV/ST | v1.12+ |
| WITH ROW FILTER | row_filter | MV/ST | v1.12+ |
| query | определяется SQL-кодом вашей модели | on_configuration_change только для MV | Все |
{{ config(
materialized='materialized_view',
partition_by='id',
schedule = {
'cron': '0 0 * * * ? *',
'time_zone_value': 'Etc/UTC'
},
tblproperties={
'key': 'value'
},
) }}
select * from {{ ref('my_seed') }}
Подробности конфигурации
partition_by
partition_by работает так же, как для представлений и таблиц, т.е. может быть одним столбцом или массивом столбцов для разделения.
liquid_clustered_by
Доступно в версиях 1.11 или выше
liquid_clustered_by включает liquid clustering для материализованных представлений и стриминговых таблиц. Liquid clustering оптимизирует производительность запросов за счёт совместного размещения похожих данных в одних и тех же файлах, что особенно полезно для запросов с селективными фильтрами по кластеризованным столбцам.
Примечание: Нельзя использовать partition_by и liquid_clustered_by одновременно в одной материализации, так как Databricks не позволяет комбинировать эти возможности.
databricks_tags
Доступно в версиях 1.11 или выше
databricks_tags позволяет применять теги Unity Catalog к вашим материализованным представлениям и стриминговым таблицам для управления данными и их организации. Теги представляют собой пары ключ-значение и могут использоваться для классификации данных, политик контроля доступа и управления метаданными.
{{ config(
materialized='streaming_table',
databricks_tags={'pii': 'contains_email', 'team': 'analytics'}
) }}
В dbt-databricks v1.12+ добавлена поддержка тегов, состоящих только из ключа. Чтобы задать тег с ключом, но без значения, укажите в качестве значения тега пустую строку '' или None:
{{ config(
materialized='streaming_table',
databricks_tags={'sensitive': '', 'reviewed': None}
) }}
Это относится к databricks_tags как на уровне таблиц, так и на уровне столбцов. Значения, не являющиеся строками, например числа или логические значения, преобразуются в строки.
Теги применяются с помощью операторов ALTER после создания материализации. После применения теги нельзя удалить путём изменения конфигурации dbt-databricks. Чтобы удалить теги, необходимо использовать Databricks напрямую или post-hook.
Начиная с dbt-databricks v1.12.0, конфигурации databricks_tags объединяются с сохранением тегов на разных уровнях иерархии конфигурации (например, на уровне проекта и на уровне модели), а не полностью заменяются конфигурациями нижележащих уровней.
Если один и тот же ключ тега определён на нескольких уровнях, приоритет имеет значение с нижележащего уровня. Ключи тегов, определённые только на вышележащих уровнях, сохраняются.
Это поведение действует везде, где можно настроить databricks_tags, включая таблицы, столбцы, материализованные представления и потоковые таблицы.
Например, при следующих конфигурациях на уровне проекта и модели:
models:
my_project:
+databricks_tags:
a: "b"
c: "project_value"
{{ config(
databricks_tags={'c': 'model_value', 'k': 'v'}
) }}
В результате будут применены следующие теги:
a: b— сохранён с уровня проектаc: model_value— значение на уровне модели переопределяет значениеcна уровне проектаk: v— добавлен на уровне модели
description
Как и для представлений и таблиц, добавление description в конфигурацию приведёт к добавлению комментария на уровне таблицы к вашей материализации.
tblproperties
tblproperties работает так же, как для представлений и таблиц, с важным исключением: адаптер поддерживает список ключей, которые устанавливаются Databricks при создании материализованного представления или потоковой таблицы, которые игнорируются для определения изменений конфигурации.
schedule
Задайте расписание обновления модели, используя один из трёх взаимоисключающих режимов:
| Режим | Конфигурация | Формат | Версия |
|---|---|---|---|
cron | schedule: { 'cron': '...', 'time_zone_value': '...' } | Строка Cron (формат Databricks). Параметр time_zone_value необязателен. | Все |
every | schedule: { 'every': '<n> <unit>' } | '<n> <unit>', где unit — HOURS, DAYS или WEEKS, например '2 HOURS' | v1.12+ |
on_update | schedule: { 'on_update': true, 'at_most_every': '<n> <unit>' } | Установите true для обновления при изменении вышестоящих данных. Необязательный параметр at_most_every ограничивает частоту обновлений (минимальный интервал — 60 секунд). Например, '15 MINUTES' | v1.12+ |
Поведение обновления в зависимости от режима:
cron: dbt запрашивает ручное обновление при каждом запуске.everyиon_update: Databricks автоматически управляет обновлением; dbt не инициирует ручное обновление при повторном запуске без изменений. Если в Databricks задано расписание, но в вашем проекте dbt оно не указано, при следующем запуске обновление переключается в ручной режим (если дляon_configuration_changeустановлено значениеapply).
query
Для материализованных представлений, если скомпилированный запрос отличается от запроса в базе данных, dbt выполняет действие, заданное параметром on_configuration_change. Изменения запросов для потоковых таблиц в настоящее время не обнаруживаются. Подробнее см. в разделе on_configuration_change.
row_filter
Доступно в версиях 1.12 и выше
row_filter применяет к модели фильтр строк Unity Catalog. Он поддерживается для материализаций table, incremental, materialized_view и streaming_table. Полное описание конфигурации и примеры см. в разделе Настройка фильтров строк.
on_configuration_change
| Материализация | Требуется удаление и повторное создание? | Примечания |
|---|---|---|
| Материализованные представления | Да, для всех изменений, кроме обновлений расписания | Ограничение Databricks SQL API |
| Потоковые таблицы | Только при изменении partition_by | Для всех остальных поддерживаемых изменений используется CREATE OR REFRESH, а для изменения расписания дополнительно используется ALTER |
Примечание об изменениях запросов потоковых таблиц: в настоящее время адаптер не может определить, изменился ли запрос потоковой таблицы. Независимо от поведения on_configuration_change, dbt использует CREATE OR REFRESH, который применяет обновлённый запрос только к будущим строкам — ранее обработанные строки не обрабатываются повторно.
Чтобы повторно обработать доступные исходные данные с обновлённым запросом, выполните запуск с --full-refresh.
Представления метрик
Установите materialized='metric_view', чтобы управлять представлением метрик Unity Catalog с помощью dbt. Вместо SQL тело модели содержит YAML-определение представления метрик: version, source, dimensions, measures и необязательный filter. dbt создаёт представление метрик с помощью CREATE OR REPLACE VIEW ... WITH METRICS LANGUAGE YAML.
{{ config(materialized='metric_view') }}
version: 1.1
source: "{{ ref('source_orders') }}"
filter: status = 'completed'
dimensions:
- name: order_date
expr: order_date
- name: status
expr: status
synonyms: [state, order_state]
measures:
- name: total_orders
expr: count(1)
- name: total_revenue
expr: sum(revenue)
synonyms: [revenue, sales]
Укажите ссылку на исходный объект в source с помощью ref(), чтобы dbt мог определить зависимости. Для запросов к полученному представлению метрик используйте функцию MEASURE().
dbt передаёт YAML-содержимое в Databricks без изменений, поэтому представление метрик поддерживает всю спецификацию YAML для представлений метрик Unity Catalog, а не только показанные выше ключи. Через dbt можно использовать любое поле, которое Databricks принимает на стороне сервера, включая synonyms и display_name для измерений и мер, а также format и window для мер.
Для представления метрик также можно задать databricks_tags и grants. Свойства tblproperties применяются только при обновлении представления на месте (с помощью view_update_via_alter) или его замене, но не при первоначальном создании.
Обновление представления метрик
По умолчанию dbt пересоздаёт представление метрик с помощью CREATE OR REPLACE VIEW при каждом запуске.
Если для view_update_via_alter установлено значение true, dbt применяет изменения на месте, не заменяя представление:
- Изменения YAML-определения применяются с помощью
ALTER VIEW ... AS. - Изменения
databricks_tagsилиtblpropertiesприменяются с помощьюALTER VIEW ... SET.
Если ни определение, ни теги, ни свойства не изменились, dbt пропускает обновление.
Настройка свойств таблиц
Свойства таблиц можно задать в конфигурации таблиц или представлений с помощью tblproperties:
{{ config(
tblproperties={
'delta.autoOptimize.optimizeWrite' : 'true',
'delta.autoOptimize.autoCompact' : 'true'
}
) }}
Эти свойства передаются напрямую в Databricks без проверки в dbt. При изменении tblproperties инкрементальных материализаций потребуется выполнить их полное обновление.
Один из вариантов использования — обеспечение совместимости таблиц delta со средствами чтения iceberg с помощью Universal Format:
{{ config(
tblproperties={
'delta.enableIcebergCompatV2' = 'true'
'delta.universalFormat.enabledFormats' = 'iceberg'
}
) }}
tblproperties можно указать для моделей Python, но из-за ограничения PySpark они применяются с помощью оператора ALTER после создания таблицы.