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

Конфигурация DuckDB

Эти настройки относятся к dbt-duckdb. Настройки профиля и подключения описаны в разделе Подключение DuckDB. Общие сведения о dbt см. в разделах Материализации и Инкрементальные модели.

Для некоторых возможностей требуется определённая минимальная версия dbt-duckdb. Требования к версии указаны по ходу текста на этой странице.

Менеджер секретов​

Используйте менеджер секретов DuckDB для управления учётными данными для облачных хранилищ. Настройте поле secrets в своём профиле:

default:
outputs:
dev:
type: duckdb
path: /tmp/dbt.duckdb
extensions:
- httpfs
- parquet
secrets:
- type: s3
region: my-aws-region
key_id: "{{ env_var('S3_ACCESS_KEY_ID') }}"
secret: "{{ env_var('S3_SECRET_ACCESS_KEY') }}"
target: dev

Получение учетных данных из контекста​

Вместо того чтобы указывать учетные данные напрямую, можно использовать поставщик секретов credential_chain, чтобы задействовать любой поддерживаемый механизм AWS (например, токены веб-идентификации). Подробности см. в документации по поставщикам секретов DuckDB.

secrets:
- type: s3
provider: credential_chain

Ограничение области действия учетных данных по префиксу пути в хранилище​

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

secrets:
- type: s3
provider: credential_chain
scope: [ "s3://bucket-in-eu-region", "s3://bucket-2-in-eu-region" ]
region: "eu-central-1"
- type: s3
region: us-west-2
scope: "s3://bucket-in-us-region"

При получении секрета для определенного пути области действия секретов сравниваются с этим путем. Если подходят несколько секретов, выбирается секрет с самым длинным совпадающим префиксом.

Облачные хранилища с fsspec​

В dbt-duckdb 1.4.1 и более поздних версиях доступна экспериментальная возможность использования файловых систем DuckDB, реализованных через fsspec. Библиотека fsspec поддерживает различные системы облачного хранения данных, включая S3, GCS и Azure Blob Storage.

Чтобы использовать реализацию fsspec, установите соответствующие модули Python и настройте filesystems в своем профиле:

default:
outputs:
dev:
type: duckdb
path: /tmp/dbt.duckdb
filesystems:
- fs: s3
anon: false
key: "{{ env_var('S3_ACCESS_KEY_ID') }}"
secret: "{{ env_var('S3_SECRET_ACCESS_KEY') }}"
client_kwargs:
endpoint_url: "http://localhost:4566"
target: dev

Каждая запись должна содержать свойство fs, которое указывает протокол fsspec для загрузки (s3, gcs, abfs и т. д.), а также может содержать дополнительные пары «ключ — значение» для настройки соответствующей реализации.

Произвольные параметры ATTACH​

Базовый синтаксис attach в профиле описан в разделе Подключение к DuckDB. Используйте словарь options, если необходимо передать дополнительные пары «ключ — значение» в инструкцию ATTACH DuckDB:

attach:
- path: /tmp/db1.sqlite
type: sqlite
read_only: true
- path: /tmp/special.duckdb
options:
cache_size: 1GB
threads: 4
enable_fsst: true

Если указать один и тот же параметр и в отдельном поле (type, secret, read_only), и в словаре options, dbt-duckdb выдаст ошибку, чтобы предотвратить конфликты.

DuckLake​

DuckLake — это табличный формат, который обеспечивает транзакции ACID и доступ к историческим версиям данных (time travel) для DuckDB. DuckLake можно использовать как с локальными базами данных, так и с MotherDuck.

DuckLake в MotherDuck​

В dbt-duckdb 1.9.6 и более поздних версиях можно подключиться к DuckLake, размещённому в MotherDuck, создав базу данных DuckLake и задав is_ducklake: true.

Чтобы настроить DuckLake в MotherDuck:

  1. Создайте базу данных DuckLake в MotherDuck:
CREATE DATABASE my_ducklake
(TYPE ducklake, DATA_PATH 's3://...')
  1. Настройте профиль:
default:
outputs:
dev:
type: duckdb
path: "md:my_db?motherduck_token={{ env_var('MOTHERDUCK_TOKEN') }}"
attach:
- path: "md:my_ducklake"
is_ducklake: true
target: dev

Необходимо явно обозначить DuckLake с помощью is_ducklake: true, чтобы dbt применял безопасные операции DDL.

Для локального DuckLake используйте ducklake: в пути:

attach:
- path: "ducklake:my_ducklake.ddb"

Партиционирование таблиц DuckLake​

Для таблиц, хранящихся в DuckLake (включая DuckLake под управлением MotherDuck), можно настроить физическое партиционирование моделей с материализацией table или incremental с помощью partitioned_by:

{{ config(materialized='table', partitioned_by=['year', 'month']) }}

select
*,
year(event_time) as year,
month(event_time) as month
from {{ ref('upstream_model') }}

partition_by допускается в качестве псевдонима для partitioned_by. Эта настройка применяется только к объектам DuckLake; для целевых платформ, не использующих DuckLake, она игнорируется с выдачей предупреждения.

DuckLake применяет партиционирование с помощью ALTER TABLE ... SET PARTITIONED BY (...), причём оно влияет только на новые данные. При первоначальном создании или полном обновлении dbt-duckdb создаёт пустую таблицу, задаёт партиционирование, а затем вставляет данные, чтобы первоначальная загрузка также была партиционирована. Дополнительные сведения см. в документации DuckLake по партиционированию.

Инкрементальные стратегии​

dbt-duckdb поддерживает следующие стратегии для инкрементальных моделей таблиц:

Стратегия append​

КонфигурацияТипПо умолчаниюОписание
incremental_predicates<list>nullSQL-условия для фильтрации добавляемых записей.

Стратегия delete+insert​

КонфигурацияТипПо умолчаниюОписание
unique_key<string>/<list>—Обязательный параметр. Столбцы, используемые для определения записей, подлежащих удалению.
incremental_predicates<list>nullSQL-условия для фильтрации операций удаления и вставки.

Стратегия merge​

Стратегия merge требует DuckDB версии 1.4.0 или более поздней и предоставляет доступ к встроенному оператору MERGE в DuckDB.

Базовая конфигурация

Если указан только unique_key, dbt-duckdb использует операции DuckDB UPDATE BY NAME и INSERT BY NAME, которые автоматически сопоставляют столбцы по имени:

models:
- name: my_incremental_model
config:
materialized: incremental
incremental_strategy: merge
unique_key: id

Расширенная конфигурация

Дополнительные параметры для более точного управления:

КонфигурацияТипПо умолчаниюОписание
unique_key<string/list>—Обязательный параметр. Столбцы, используемые в условии соединения MERGE.
incremental_predicates<list>nullДополнительные SQL-условия для фильтрации операции MERGE.
merge_update_condition<string>nullSQL-условие, определяющее, когда обновлять совпавшие записи.
merge_insert_condition<string>nullSQL-условие, определяющее, когда вставлять записи, для которых не найдено совпадений.
merge_update_columns<list>nullКонкретные столбцы для обновления.
merge_exclude_columns<list>nullСтолбцы, исключаемые из обновления.
merge_update_set_expressions<dict>nullПользовательские выражения для обновления столбцов.

Для максимальной гибкости используйте merge_clauses, чтобы задать собственное поведение when_matched и when_not_matched. При использовании DuckLake в операторах MERGE допускается только одно действие UPDATE или DELETE в предложениях when_matched из-за текущих ограничений реализации MERGE в DuckLake.

В условиях и выражениях используйте DBT_INTERNAL_SOURCE для ссылки на входящие данные, а DBT_INTERNAL_DEST — для ссылки на существующую целевую таблицу.

Стратегия microbatch​

Стратегия microbatch требует dbt версии 1.9 или более поздней и выполняет инкрементальное построение пакетами, сформированными по временным интервалам на основе настроенного столбца event_time.

КонфигурацияТипПо умолчаниюОписание
event_time<string>—Обязательный параметр. Имя столбца с временными метками, используемого для определения временных окон микропакетов.
begin<string>—Обязательный параметр. Начальное время для формирования пакетов (например, 2025-01-01).
batch_size<string>—Обязательный параметр. Временная гранулярность пакета (например, day, hour).
incremental_predicates<list>nullНеобязательные дополнительные предикаты, применяемые внутри каждого пакета.
подсказка

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

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

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

0
Loading