(Версии dbt: v2.0 и новее) # Подключение DuckDB к dbt v2 Локальная разработка DuckDB с dbt v2 — самый простой способ запустить проект dbt локально — без учётной записи хранилища и учётных данных. [DuckDB](https://duckdb.org) — это встраиваемая база данных, которая работает целиком внутри процесса, поэтому dbt подключается напрямую к локальному файлу `.duckdb` без дополнительной настройки. DuckDB не требует аутентификации — она работает локально на вашем компьютере. ### Установка dbt-duckdb Адаптер DuckDB встроен в v2. Чтобы начать работу, [установите dbt](https://docs.getdbt.tech/docs/local/install-dbt.md). В качестве интерфейса разработки рекомендуем использовать [расширение для VS Code](https://docs.getdbt.tech/docs/local/install-dbt.md?version=2). #### Драйвер и расширения DuckDB dbt v2 поставляется со встроенным драйвером DuckDB. Однако этот драйвер *не* поддерживает загрузку расширений DuckDB (например, `httpfs`, `parquet` или `spatial`). Чтобы использовать [расширения DuckDB](https://duckdb.org/docs/current/extensions/overview) с dbt v2, установите драйвер DuckDB с помощью [`dbc`](https://docs.columnar.tech/dbc/#__tabbed_2_4). dbt v2 сначала проверяет наличие установленного в системе драйвера DuckDB и использует встроенный драйвер, если системный не найден. Примеры подключения и общие настройки профиля приведены в разделе [Подключение к DuckDB](#connecting-to-duckdb). ### Ограничения Некоторые возможности адаптера `dbt-duckdb` для dbt v1 пока не поддерживаются. Текущая работа по обеспечению паритета возможностей адаптера и устранению пробелов в анализе SQL отслеживается в [dbt#14393](https://github.com/dbt-labs/dbt/issues/14393). #### Статический анализ и локальные файлы данных dbt v2 выполняет статический анализ SQL-моделей, чтобы определять типы столбцов и происхождение данных без выполнения запросов. Если ваши модели обращаются к локальным файлам данных (CSV, Parquet или JSON) через функции DuckDB `read_csv()`, `read_parquet()` или `read_json()`, dbt v2 может не определить схему этих файлов на этапе анализа. В результате могут появляться предупреждения об определении типов или ошибки компиляции, даже если при выполнении запрос завершился бы успешно. Подробнее см. в разделе [Новые концепции](https://docs.getdbt.tech/docs/build/about-static-analysis.md). ## Подключение к DuckDB [DuckDB](https://duckdb.org) — это встраиваемая база данных, похожая на SQLite, но предназначенная для аналитики в стиле OLAP, а не OLTP. Подключить dbt к DuckDB можно несколькими способами в зависимости от того, где вы хотите хранить данные. Настройте `profiles.yml`, используя примеры из следующих разделов: * [В памяти](#in-memory) * [Локальный файл](#local-file) * [MotherDuck](#motherduck) * [Подключение дополнительных баз данных](#attaching-additional-databases) В следующей таблице перечислены поля для использования в `profiles.yml`. Поле `type: duckdb` обязательно *всегда*. Используйте `path` для локальных файлов или строк подключения MotherDuck, а для базы данных в памяти укажите `:memory:` или не задавайте `path`. | Поле профиля | Описание | Пример | | ------------ | ------------------------------------------------------------------------------------------------------------- | ---------------------- | | `type` | Тип адаптера. | `duckdb` | | `path` | Путь к файлу базы данных DuckDB, строка подключения MotherDuck `md:` или `:memory:` для базы данных в памяти. | `./jaffle_shop.duckdb` | | `schema` | Имя схемы, в которой dbt создаёт объекты. | `main` | | `threads` | Количество потоков, используемых dbt для параллельного построения моделей. | `4` | | `extensions` | Список [расширений DuckDB](https://duckdb.org/docs/extensions/overview), загружаемых при запуске. | `httpfs`, `parquet` | | `settings` | Словарь [параметров конфигурации DuckDB](https://duckdb.org/docs/sql/configuration), задаваемых при запуске. | `s3_region: us-east-1` | Если вы используете dbt v2, для загрузки расширений необходимо установить драйвер DuckDB с помощью [`dbc`](https://docs.columnar.tech/dbc/#__tabbed_2_4). Подробнее см. в разделе [Драйвер и расширения DuckDB](#driver-and-extensions). ### В памяти Для самой простой конфигурации достаточно указать в профиле только `type: duckdb`. При этом база данных работает в памяти — все данные теряются после завершения запуска. Это удобно для тестирования конвейеров и рабочих процессов, которые используют исключительно внешние файлы CSV, Parquet или JSON. profiles.yml ```yaml default: outputs: dev: type: duckdb target: dev ``` ### Локальный файл Чтобы сохранять данные между запусками, укажите в `path` путь к файлу `.duckdb` в локальной файловой системе. DuckDB автоматически создаст файл, если он не существует. profiles.yml ```yaml your_profile_name: target: dev outputs: dev: type: duckdb path: './my_project.duckdb' schema: main # optional; defaults to main threads: 4 # optional ``` Можно использовать относительный путь (отсчитываемый от расположения файла `profiles.yml`) или абсолютный путь. `dbt-duckdb` автоматически задаёт свойству `database` значение, равное имени файла без расширения (например, для `/tmp/a/dbfile.duckdb` свойство `database` получает значение `dbfile`). ### MotherDuck В `dbt-duckdb 1.5.2` и более поздних версиях можно подключиться к экземпляру DuckDB, работающему в [MotherDuck](https://motherduck.com), указав в `path` строку подключения `md:`: profiles.yml ```yaml your_profile_name: target: dev outputs: dev: type: duckdb path: "md:my_db?motherduck_token={{ env_var('MOTHERDUCK_TOKEN') }}" threads: 4 ``` Базы данных MotherDuck в целом работают так же, как локальные базы данных DuckDB, с некоторыми отличиями, описанными в [документации MotherDuck](https://motherduck.com/docs/architecture-and-capabilities#considerations-and-limitations). MotherDuck предварительно загружает распространённые расширения DuckDB, но не поддерживает загрузку сторонних расширений или пользовательских функций. ### Подключение дополнительных баз данных DuckDB поддерживает [подключение дополнительных баз данных](https://duckdb.org/docs/sql/statements/attach.html), что позволяет читать и записывать данные в нескольких базах данных. Настройте дополнительные базы данных с помощью аргумента `attach` в профиле: profiles.yml ```yaml default: outputs: dev: type: duckdb path: /tmp/dbt.duckdb attach: - path: /tmp/other.duckdb - path: ./yet/another.duckdb alias: yet_another - path: s3://yep/even/this/works.duckdb read_only: true - path: sqlite.db type: sqlite - path: postgresql://username@hostname/dbname type: postgres target: dev ``` К подключённым базам данных можно обращаться по имени файла (без расширения) или по указанному вами `alias`. Аргумент `type` поддерживает значения `duckdb`, `sqlite` и `postgres`. Также можно передавать произвольные параметры с помощью словаря `options` — подробнее см. в разделе [Произвольные параметры ATTACH](https://docs.getdbt.tech/reference/resource-configs/duckdb-configs.md#arbitrary-attach-options). Для локальных баз данных DuckLake используйте `ducklake:`. Для DuckLake под управлением MotherDuck используйте `md:` с `is_ducklake: true`. Подробнее см. в разделе [Конфигурация DuckLake](https://docs.getdbt.tech/reference/resource-configs/duckdb-configs.md#ducklake). ## Расширения Вы можете загружать любые поддерживаемые [расширения DuckDB](https://duckdb.org/docs/extensions/overview), перечислив их в поле `extensions` своего профиля. Также можно задавать любые дополнительные [параметры конфигурации DuckDB](https://duckdb.org/docs/sql/configuration) в поле `settings`. profiles.yml ```yaml your_profile_name: target: dev outputs: dev: type: duckdb path: 'file_path/database_name.duckdb' extensions: - httpfs - parquet settings: s3_region: my-aws-region s3_access_key_id: "{{ env_var('S3_ACCESS_KEY_ID') }}" s3_secret_access_key: "{{ env_var('S3_SECRET_ACCESS_KEY') }}" ``` Также можно настроить расширения из других репозиториев, помимо основного (например, расширения сообщества), указав пару `name`/`repo`: ```yml extensions: - httpfs - parquet - name: h3 repo: community - name: uc_catalog repo: core_nightly ``` О настройке доступа к облачному хранилищу с помощью Secrets Manager в DuckDB или файловых систем fsspec см. на странице [Конфигурации DuckDB](https://docs.getdbt.tech/reference/resource-configs/duckdb-configs.md). ## Дополнительная информация Информацию о специфичных для DuckDB настройках можно найти в [справочном руководстве по адаптеру DuckDB](https://docs.getdbt.tech/reference/resource-configs/duckdb-configs.md). Исходный код адаптера доступен в [репозитории `dbt-duckdb`](https://github.com/duckdb/dbt-duckdb). Примечания к выпускам адаптера см. на [странице выпусков `dbt-duckdb`](https://github.com/duckdb/dbt-duckdb/releases).