Интеграция dbt и ClickHouse

ClickHouse Supported

Адаптер dbt-clickhouse

dbt (data build tool) позволяет инженерам по аналитике преобразовывать данные в их хранилищах, просто записывая запросы SELECT. dbt материализует эти запросы SELECT в объекты базы данных в виде таблиц и представлений, выполняя этап Transform (T) в процессе Extract, Load, Transform (ELT). Пользователи могут создавать модель, определяемую запросом SELECT.

В dbt эти модели могут ссылаться друг на друга и образовывать слои, что позволяет формировать более высокоуровневые абстракции. Шаблонный SQL, необходимый для соединения моделей, генерируется автоматически. Кроме того, dbt определяет зависимости между моделями и гарантирует, что они создаются в правильном порядке с использованием ориентированного ациклического графа (DAG).

dbt совместим с ClickHouse через адаптер, официально поддерживаемый ClickHouse.

• Адаптер dbt-clickhouse
• Поддерживаемые возможности
• Концепции dbt и поддерживаемые материализации
• Настройка dbt и адаптера ClickHouse
• Устранение распространённых проблем
• Ограничения
• Fivetran

Поддерживаемые возможности

Список поддерживаемых возможностей:

• Материализация таблиц
• Материализация представлений
• Инкрементальная материализация
• Микробатчевая инкрементальная материализация
• Материализация с использованием материализованного представления (использует форму TO для MATERIALIZED VIEW, экспериментально)
• Seeds
• Источники
• Генерация документации
• Тесты
• Снапшоты
• Большинство макросов dbt-utils (теперь входят в состав dbt-core)
• Эфемерная материализация
• Распределённая материализация таблиц (экспериментально)
• Распределённая инкрементальная материализация (экспериментально)
• Контракты
• Специфические для ClickHouse конфигурации столбцов (Codec, TTL...)
• Специфические для ClickHouse настройки таблиц (индексы, проекции...)

Поддерживаются все возможности вплоть до dbt-core 1.10 включительно, включая флаг --sample, а также устранены все предупреждения об устаревании, подготовленные для будущих релизов. Интеграции с каталогами (например, Iceberg), появившиеся в dbt 1.10, пока ещё не поддерживаются нативно в адаптере, но доступны обходные решения. См. раздел Catalog Support для подробностей.

Этот адаптер всё ещё недоступен для использования в dbt Cloud, но мы рассчитываем сделать его доступным в ближайшее время. Пожалуйста, свяжитесь со службой поддержки, чтобы получить дополнительную информацию.

Концепции dbt и поддерживаемые материализации

dbt вводит концепцию модели. Она определяется как SQL-запрос, потенциально объединяющий множество таблиц. Модель может быть «материализована» несколькими способами. Материализация представляет собой стратегию построения для SELECT-запроса модели. Код, лежащий в основе материализации, — это шаблонный SQL, который оборачивает ваш SELECT-запрос в команду для создания нового или обновления существующего relation (объекта базы данных).

dbt предоставляет 5 типов материализации. Все они поддерживаются dbt-clickhouse:

• view (по умолчанию): Модель создаётся как view в базе данных. В ClickHouse это соответствует view.
• table: Модель создаётся как таблица в базе данных. В ClickHouse это соответствует table.
• ephemeral: Модель не создаётся напрямую в базе данных, а вместо этого подставляется в зависимые модели как CTE (Common Table Expressions).
• incremental: Модель изначально материализуется как таблица, а при последующих запусках dbt добавляет новые строки и обновляет изменённые строки в таблице.
• materialized view: Модель создаётся как materialized view в базе данных. В ClickHouse это соответствует materialized view.

Дополнительный синтаксис и конструкции SQL определяют, как эти модели должны обновляться при изменении исходных данных. В целом dbt рекомендует начинать с материализации view, пока производительность не станет проблемой. Материализация table обеспечивает улучшение производительности при выполнении запросов за счёт сохранения результатов запроса модели в виде таблицы, ценой увеличения объёма хранения данных. Инкрементальный подход развивает эту идею дальше, позволяя фиксировать последующие изменения исходных данных в целевой таблице.

Текущий адаптер для ClickHouse также поддерживает материализации dictionary, distributed table и distributed incremental. Адаптер также поддерживает dbt snapshots и seeds.

Следующие возможности являются экспериментальными функциями в dbt-clickhouse:

Тип	Поддерживается?	Подробности
Materialized View materialization	ДА, экспериментальная	Создаёт materialized view.
Distributed table materialization	ДА, экспериментальная	Создаёт distributed table.
Distributed incremental materialization	ДА, экспериментальная	Инкрементальная модель, основанная на той же идее, что и distributed table. Обратите внимание, что поддерживаются не все стратегии; для получения дополнительной информации см. это.
Dictionary materialization	ДА, экспериментальная	Создаёт dictionary.

Настройка dbt и адаптера ClickHouse

Установка dbt-core и dbt-clickhouse

dbt предоставляет несколько способов установки интерфейса командной строки (CLI), которые подробно описаны здесь. Мы рекомендуем использовать pip для установки как dbt, так и dbt-clickhouse.

pip install dbt-core dbt-clickhouse

Укажите в dbt параметры подключения к нашему экземпляру ClickHouse.

Настройте профиль clickhouse-service в файле ~/.dbt/profiles.yml и задайте параметры schema, host, port, user и password. Полный список параметров конфигурации подключения доступен на странице Возможности и параметры конфигурации:

clickhouse-service:
  target: dev
  outputs:
    dev:
      type: clickhouse
      schema: [ default ] # ClickHouse database for dbt models

      # Optional
      host: [ localhost ]
      port: [ 8123 ]  # Defaults to 8123, 8443, 9000, 9440 depending on the secure and driver settings 
      user: [ default ] # User for all database operations
      password: [ <empty string> ] # Password for the user
      secure: True  # Use TLS (native protocol) or HTTPS (http protocol)

Создайте проект dbt

Теперь вы можете использовать этот профиль в одном из существующих проектов или создать новый с помощью:

dbt init project_name

В каталоге project_name измените файл dbt_project.yml, указав имя профиля для подключения к серверу ClickHouse.

profile: 'clickhouse-service'

Тестирование соединения

Выполните dbt debug с помощью инструмента командной строки (CLI), чтобы проверить, может ли dbt подключиться к ClickHouse. Убедитесь, что в ответе присутствует строка Connection test: [OK connection ok], означающая успешное соединение.

Перейдите на страницу руководств, чтобы узнать больше о том, как использовать dbt с ClickHouse.

Тестирование и развертывание моделей (CI/CD)

Существует множество способов тестировать и развертывать ваш dbt‑проект. У dbt есть рекомендации по рабочим процессам, основанным на лучших практиках и CI‑заданиям. Мы рассмотрим несколько стратегий, но имейте в виду, что их может потребоваться существенно адаптировать под ваш конкретный сценарий.

CI/CD с простыми тестами данных и модульными тестами

Один из простых способов запустить ваш CI‑конвейер — развернуть кластер ClickHouse внутри задания и запускать ваши модели на нём. Перед запуском моделей вы можете загрузить демонстрационные данные в этот кластер. Можно просто использовать seed, чтобы наполнить промежуточную среду подмножеством ваших боевых данных.

После загрузки данных вы можете запустить свои тесты данных и модульные тесты.

Шаг CD может быть столь же простым, как запуск dbt build для вашего боевого кластера ClickHouse.

Более полный этап CI/CD: используйте актуальные данные, тестируйте только затронутые модели

Одна из распространённых стратегий — использовать задания Slim CI, при которых повторно разворачиваются только изменённые модели (и их зависимости, как зависящие, так и зависимые). Этот подход использует артефакты из ваших продакшн-запусков (то есть dbt manifest), чтобы сократить время выполнения вашего проекта и гарантировать отсутствие расхождения схем между средами.

Чтобы держать ваши среды разработки синхронизированными и избежать запуска моделей по устаревшим развёртываниям, вы можете использовать команду clone или даже defer.

Мы рекомендуем использовать выделенный кластер или сервис ClickHouse для тестовой среды (например, промежуточной / staging-среды), чтобы избежать влияния на работу вашей продакшн-среды. Чтобы тестовая среда была репрезентативной, важно использовать подмножество ваших продакшн-данных, а также запускать dbt таким образом, чтобы предотвращать расхождение схем между средами.

• Если вам не нужны свежие данные для тестирования, вы можете восстановить резервную копию ваших продакшн-данных в staging-среду.
• Если вам нужны свежие данные для тестирования, вы можете использовать комбинацию табличной функции remoteSecure() и обновляемых материализованных представлений для вставки данных с нужной частотой. Другой вариант — использовать объектное хранилище как промежуточный слой и периодически записывать данные из вашего продакшн-сервиса, а затем импортировать их в staging-среду с помощью табличных функций для объектного хранилища или ClickPipes (для непрерывной ингестии).

Использование выделенной среды для CI-тестирования также позволяет выполнять ручное тестирование без влияния на вашу продакшн-среду. Например, вы можете направить BI-инструмент на эту среду для тестирования.

Для развертывания (то есть шага CD) мы рекомендуем использовать артефакты из ваших продакшн-развертываний, чтобы обновлять только те модели, которые изменились. Для этого необходимо настроить объектное хранилище (например, S3) как промежуточное хранилище для артефактов dbt. После этого вы можете выполнить команду dbt build --select state:modified+ --state path/to/last/deploy/state.json, чтобы выборочно перестроить минимальное количество моделей, необходимых с учётом изменений, произошедших с момента последнего запуска в продакшн-среде.

Устранение распространённых проблем

Подключения

Если у вас возникают проблемы с подключением к ClickHouse из dbt, убедитесь, что выполнены следующие условия:

• Движок таблицы должен быть одним из поддерживаемых движков.
• У вас должны быть достаточные права доступа к базе данных.
• Если вы не используете движок таблицы по умолчанию для базы данных, укажите движок таблицы в конфигурации модели.

Анализ длительно выполняющихся операций

Некоторые операции могут выполняться дольше ожидаемого из‑за специфических запросов к ClickHouse. Чтобы лучше понять, какие запросы занимают больше времени, увеличьте уровень логирования до debug — это выведет время, затраченное на каждый запрос. Например, этого можно добиться, добавив --log-level debug к командам dbt.

Ограничения

Текущий адаптер ClickHouse для dbt имеет несколько ограничений, о которых пользователям следует знать:

• Плагин использует синтаксис, который требует ClickHouse версии 25.3 или новее. Мы не тестируем более старые версии ClickHouse. В настоящее время мы также не тестируем реплицируемые таблицы (Replicated).
• Разные запуски dbt-adapter могут конфликтовать, если выполняются одновременно, так как внутри они могут использовать одинаковые имена таблиц для одних и тех же операций. Дополнительную информацию см. в задаче #420.
• В настоящее время адаптер материализует модели как таблицы, используя INSERT INTO SELECT. Это фактически приводит к дублированию данных при повторном запуске. Очень большие наборы данных (петабайтного масштаба) могут приводить к чрезвычайно долгому времени выполнения, делая некоторые модели непрактичными. Для повышения производительности используйте материализованные представления ClickHouse, реализуя представление как materialized: materialization_view. Кроме того, стремитесь минимизировать количество строк, возвращаемых любым запросом, используя GROUP BY, где это возможно. Отдавайте предпочтение моделям, которые агрегируют данные, а не тем, которые лишь трансформируют их, сохраняя количество строк источника.
• Чтобы использовать Distributed-таблицы для представления модели, пользователи должны вручную создать базовые реплицируемые таблицы на каждом узле. Distributed-таблица, в свою очередь, может быть создана поверх них. Адаптер не управляет созданием кластера.
• Когда dbt создаёт relation (table/view) в базе данных, он обычно создаёт его как: {{ database }}.{{ schema }}.{{ table/view id }}. В ClickHouse нет понятия схем. Поэтому адаптер использует {{schema}}.{{ table/view id }}, где schema — это база данных ClickHouse.
• Эфемерные модели/CTE не работают, если они размещены перед INSERT INTO в операторе вставки ClickHouse, см. https://github.com/ClickHouse/ClickHouse/issues/30323. Это не должно затрагивать большинство моделей, но следует внимательно относиться к месту размещения эфемерной модели в определениях моделей и других SQL-операторах.

Fivetran

Коннектор dbt-clickhouse также доступен для использования в Fivetran transformations, что обеспечивает бесшовную интеграцию и выполнение преобразований непосредственно в платформе Fivetran с использованием dbt.