(Версии dbt: v2.0 и новее)

Подключение DuckDB к dbt v2

DuckDB с dbt v2 — самый простой способ запустить проект dbt локально — без учётной записи хранилища и учётных данных. DuckDB — это встраиваемая база данных, которая работает целиком внутри процесса, поэтому dbt подключается напрямую к локальному файлу .duckdb без дополнительной настройки.

DuckDB не требует аутентификации — она работает локально на вашем компьютере.

Установка dbt-duckdb

Адаптер DuckDB встроен в v2. Чтобы начать работу, установите dbt. В качестве интерфейса разработки рекомендуем использовать расширение для VS Code.

Драйвер и расширения DuckDB

dbt v2 поставляется со встроенным драйвером DuckDB. Однако этот драйвер не поддерживает загрузку расширений DuckDB (например, httpfs, parquet или spatial).

Чтобы использовать расширения DuckDB с dbt v2, установите драйвер DuckDB с помощью dbc. dbt v2 сначала проверяет наличие установленного в системе драйвера DuckDB и использует встроенный драйвер, если системный не найден.

Примеры подключения и общие настройки профиля приведены в разделе Подключение к DuckDB.

Ограничения

Некоторые возможности адаптера dbt-duckdb для dbt v1 пока не поддерживаются.

Текущая работа по обеспечению паритета возможностей адаптера и устранению пробелов в анализе SQL отслеживается в dbt#14393.

Статический анализ и локальные файлы данных

dbt v2 выполняет статический анализ SQL-моделей, чтобы определять типы столбцов и происхождение данных без выполнения запросов. Если ваши модели обращаются к локальным файлам данных (CSV, Parquet или JSON) через функции DuckDB read_csv(), read_parquet() или read_json(), dbt v2 может не определить схему этих файлов на этапе анализа. В результате могут появляться предупреждения об определении типов или ошибки компиляции, даже если при выполнении запрос завершился бы успешно. Подробнее см. в разделе Новые концепции.

Подключение к DuckDB

DuckDB — это встраиваемая база данных, похожая на SQLite, но предназначенная для аналитики в стиле OLAP, а не OLTP. Подключить dbt к DuckDB можно несколькими способами в зависимости от того, где вы хотите хранить данные. Настройте profiles.yml, используя примеры из следующих разделов:

• В памяти
• Локальный файл
• MotherDuck
• Подключение дополнительных баз данных

В следующей таблице перечислены поля для использования в 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, загружаемых при запуске.	httpfs, parquet
settings	Словарь параметров конфигурации DuckDB, задаваемых при запуске.	s3_region: us-east-1

Если вы используете dbt v2, для загрузки расширений необходимо установить драйвер DuckDB с помощью dbc. Подробнее см. в разделе Драйвер и расширения DuckDB.

В памяти

Для самой простой конфигурации достаточно указать в профиле только type: duckdb. При этом база данных работает в памяти — все данные теряются после завершения запуска. Это удобно для тестирования конвейеров и рабочих процессов, которые используют исключительно внешние файлы CSV, Parquet или JSON.

profiles.yml

default:
  outputs:
    dev:
      type: duckdb
  target: dev

Сообщить об ошибке в коде

Локальный файл

Чтобы сохранять данные между запусками, укажите в path путь к файлу .duckdb в локальной файловой системе. DuckDB автоматически создаст файл, если он не существует.

profiles.yml

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, указав в path строку подключения md::

profiles.yml

your_profile_name:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: "md:my_db?motherduck_token={{ env_var('MOTHERDUCK_TOKEN') }}"
      threads: 4

Сообщить об ошибке в коде

Базы данных MotherDuck в целом работают так же, как локальные базы данных DuckDB, с некоторыми отличиями, описанными в документации MotherDuck. MotherDuck предварительно загружает распространённые расширения DuckDB, но не поддерживает загрузку сторонних расширений или пользовательских функций.

Подключение дополнительных баз данных

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

profiles.yml

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.

Для локальных баз данных DuckLake используйте ducklake:. Для DuckLake под управлением MotherDuck используйте md: с is_ducklake: true. Подробнее см. в разделе Конфигурация DuckLake.

Расширения

Вы можете загружать любые поддерживаемые расширения DuckDB, перечислив их в поле extensions своего профиля. Также можно задавать любые дополнительные параметры конфигурации DuckDB в поле settings.

profiles.yml

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:

extensions:
  - httpfs
  - parquet
  - name: h3
    repo: community
  - name: uc_catalog
    repo: core_nightly

Сообщить об ошибке в коде

О настройке доступа к облачному хранилищу с помощью Secrets Manager в DuckDB или файловых систем fsspec см. на странице Конфигурации DuckDB.

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

Информацию о специфичных для DuckDB настройках можно найти в справочном руководстве по адаптеру DuckDB.

Исходный код адаптера доступен в репозитории dbt-duckdb. Примечания к выпускам адаптера см. на странице выпусков dbt-duckdb.

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

Создать GitHub Issue