Интеграция 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 и адаптера ClickHouse
• Устранение распространённых проблем
• Ограничения
• Fivetran

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

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

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

Поддерживаются все возможности вплоть до dbt-core 1.9 включительно. В ближайшее время мы добавим возможности, появившиеся в dbt-core 1.10.

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

Концепции

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

dbt предоставляет 4 типа материализации:

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

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

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

Подробности о поддерживаемых материализациях

Тип	Поддерживается?	Подробности
view materialization	ДА	Создаёт view.
table materialization	ДА	Создаёт table. Список поддерживаемых движков см. ниже.
incremental materialization	ДА	Создаёт таблицу, если она не существует, а затем записывает в неё только обновления.
ephemeral materialized	ДА	Реализует материализацию ephemeral/CTE. Эта модель является внутренней для 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> ] # Пароль для этого пользователя
      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.