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

ClickHouse Supported

Адаптер dbt-clickhouse

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

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

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

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

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

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

• Материализация таблиц
• Материализация представлений
• Инкрементальная материализация
• Микробатчовая инкрементальная материализация
• Материализации Materialized View (используют форму TO оператора MATERIALIZED VIEW, экспериментально)
• Seeds
• Sources
• Генерация документации
• Тесты
• Снимки (Snapshots)
• Большинство макросов dbt-utils (теперь входят в dbt-core)
• Эфемерная материализация
• Материализация distributed таблиц (экспериментально)
• Инкрементальная материализация для distributed таблиц (экспериментально)
• Контракты
• Специфичные для 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.

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

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

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

Тип	Поддерживается?	Подробности
Материализация Materialized View	ДА, экспериментальная	Создаёт materialized view.
Материализация distributed таблица	ДА, экспериментальная	Создаёт distributed таблица.
Материализация distributed incremental	ДА, экспериментальная	Инкрементальная модель, основанная на той же идее, что и distributed таблица. Обратите внимание, что поддерживаются не все стратегии. Дополнительные сведения см. здесь.
Материализация 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. Полный список параметров конфигурации подключения доступен на странице Features and configurations:

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 внутри задачи CI (job) и затем запускать ваши модели на нём. Вы можете загрузить демонстрационные данные в этот кластер перед запуском моделей. Для наполнения стейджинг-среды подмножеством боевых данных можно использовать seed.

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

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

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

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

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

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

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

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

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

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

Подключения

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

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

Понимание длительных операций

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

Ограничения

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

• Плагин использует синтаксис, который требует ClickHouse версии 25.3 или новее. Мы не тестируем более старые версии ClickHouse. Также в настоящее время мы не тестируем Replicated-таблицы.
• Разные запуски dbt-adapter могут конфликтовать, если выполняются одновременно, так как внутренне могут использовать одинаковые имена таблиц для одних и тех же операций. Дополнительную информацию см. в задаче #420.
• В настоящий момент адаптер материализует модели как таблицы, используя INSERT INTO SELECT. Фактически это означает дублирование данных при повторном запуске. Очень большие наборы данных (петабайты) могут приводить к чрезвычайно длительному времени выполнения, делая некоторые модели непрактичными. Для повышения производительности используйте ClickHouse Materialized Views, реализуя представление как materialized: materialization_view. Кроме того, стремитесь минимизировать количество строк, возвращаемых любым запросом, используя GROUP BY, где это возможно. Отдавайте предпочтение моделям, которые агрегируют данные, а не просто трансформируют их при сохранении исходного количества строк.
• Чтобы использовать Distributed-таблицы для представления модели, вы должны вручную создать лежащие в основе Replicated-таблицы на каждом узле. Distributed-таблица, в свою очередь, может быть создана поверх них. Адаптер не управляет созданием кластера.
• Когда dbt создаёт отношение (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, что обеспечивает бесшовную интеграцию и выполнение трансформаций непосредственно на платформе Fivetran с использованием dbt.