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

Эти настройки относятся к `dbt-duckdb`. Настройки профиля и подключения описаны в разделе [Подключение DuckDB](https://docs.getdbt.tech/docs/local/connect-data-platform/duckdb-setup.md). Общие сведения о dbt см. в разделах [Материализации](https://docs.getdbt.tech/docs/build/materializations.md) и [Инкрементальные модели](https://docs.getdbt.tech/docs/build/incremental-models.md).

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

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

Используйте [менеджер секретов DuckDB](https://duckdb.org/docs/configuration/secrets_manager.html) для управления учётными данными для облачных хранилищ. Настройте поле `secrets` в своём профиле:

```yml
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](https://duckdb.org/docs/configuration/secrets_manager.html#secret-providers).

```yml
secrets:
  - type: s3
    provider: credential_chain
```

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

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

```yml
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](https://duckdb.org/docs/guides/python/filesystems.html). Библиотека `fsspec` поддерживает [различные системы облачного хранения данных](https://filesystem-spec.readthedocs.io/en/latest/api.html#other-known-implementations), включая S3, GCS и Azure Blob Storage.

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

```yml
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](https://docs.getdbt.tech/docs/local/connect-data-platform/duckdb-setup.md#attaching-additional-databases). Используйте словарь `options`, если необходимо передать дополнительные пары «ключ — значение» в инструкцию `ATTACH` DuckDB:

```yml
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](https://ducklake.select) — это табличный формат, который обеспечивает транзакции ACID и доступ к историческим версиям данных (time travel) для DuckDB. DuckLake можно использовать как с локальными базами данных, так и с MotherDuck.

### DuckLake в MotherDuck

В `dbt-duckdb 1.9.6` и более поздних версиях можно подключиться к [DuckLake, размещённому в MotherDuck](https://motherduck.com/blog/ducklake-motherduck/), создав базу данных DuckLake и задав `is_ducklake: true`.

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

1. Создайте базу данных DuckLake в MotherDuck:

```sql
CREATE DATABASE my_ducklake
  (TYPE ducklake, DATA_PATH 's3://...')
```

2. Настройте профиль:

```yml
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:` в пути:

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

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

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

```sql
{{ 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 по партиционированию](https://ducklake.select/docs/stable/duckdb/advanced_features/partitioning).

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

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

* [`append`](#append-strategy)
* [`delete+insert`](#deleteinsert-strategy)
* [`merge`](#merge-strategy)
* [`microbatch`](#microbatch-strategy)

### Стратегия append

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

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

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

### Стратегия merge

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

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

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

```yml
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>`      | null         | SQL-условие, определяющее, когда обновлять совпавшие записи.                          |
| `merge_insert_condition`       | `<string>`      | null         | SQL-условие, определяющее, когда вставлять записи, для которых не найдено совпадений. |
| `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). Обязательно протестируйте разное количество потоков, чтобы подобрать подходящее для вашего сценария.

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

* Сведения о режимах подключения и настройке профиля см. в разделе [Подключение DuckDB](https://docs.getdbt.tech/docs/local/connect-data-platform/duckdb-setup.md).
* Исходный код адаптера и плагины см. в [репозитории `dbt-duckdb`](https://github.com/duckdb/dbt-duckdb). Примечания к выпускам адаптера см. на [странице выпусков `dbt-duckdb`](https://github.com/duckdb/dbt-duckdb/releases).
* О концепциях dbt, используемых на этой странице, см. в разделах [Материализации](https://docs.getdbt.tech/docs/build/materializations.md), [Инкрементальные модели](https://docs.getdbt.tech/docs/build/incremental-models.md) и [Модели Python](https://docs.getdbt.tech/docs/build/python-models.md).
