Skip to main content

​
Адаптер dbt-clickhouse

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

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

Список поддерживаемых возможностей:
  • Материализация таблиц
  • Материализация представлений
  • Инкрементальная материализация
  • Инкрементальная материализация Microbatch
  • Materialized View materializations (использует форму TO для MATERIALIZED VIEW, экспериментально)
  • Seeds
  • Источники
  • Генерация документации
  • Тесты
  • Снимки
  • Большинство макросов dbt-utils (теперь входят в dbt-core)
  • Эфемерная материализация
  • Материализация distributed таблиц (экспериментально)
  • Инкрементальная материализация distributed таблиц (экспериментально)
  • Контракты
  • Специфичные для ClickHouse конфигурации столбцов (кодек, TTL…)
  • Специфичные для ClickHouse настройки таблиц (индексы, проекции…)
Поддерживаются все возможности вплоть до dbt-core 1.10, включая флаг --sample; также устранены все предупреждения об устаревании для будущих версий. Интеграции с каталогами (например, Iceberg), появившиеся в dbt 1.10, пока не поддерживаются адаптером нативно, но доступны обходные решения. Подробности см. в разделе Catalog Support. Этот адаптер по-прежнему недоступен для использования в dbt Cloud, но мы рассчитываем добавить его в ближайшее время. За дополнительной информацией обратитесь в службу поддержки.

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

dbt вводит понятие модели. Она определяется как SQL-оператор, который может объединять множество таблиц. Модель может быть «материализована» несколькими способами. Материализация представляет собой стратегию сборки для SELECT-запроса модели. Код материализации — это типовой SQL-код, который оборачивает ваш запрос SELECT в оператор, чтобы создать новое или обновить существующее отношение. dbt предоставляет 5 типов материализации. Все они поддерживаются dbt-clickhouse:
  • view (по умолчанию): Модель создаётся как представление в базе данных. В ClickHouse это создаётся как view.
  • table: Модель создаётся как таблица в базе данных. В ClickHouse это создаётся как table.
  • ephemeral: Модель не создаётся напрямую в базе данных, а подставляется в зависимые модели как CTE (Common Table Expressions, общие табличные выражения).
  • incremental: Изначально модель материализуется как таблица, а при последующих запусках dbt выполняет вставку новых строк и обновляет изменённые строки в таблице.
  • materialized view: Модель создаётся как materialized view в базе данных. В ClickHouse это создаётся как materialized view.
Дополнительные синтаксические конструкции и секции определяют, как эти модели должны обновляться при изменении лежащих в их основе данных. Как правило, dbt рекомендует начинать с материализации view, пока производительность не станет критичной. Материализация table повышает производительность на этапе выполнения запроса, сохраняя результаты запроса модели в виде таблицы, но ценой увеличения объёма хранилища. Подход incremental развивает эту идею дальше, позволяя фиксировать последующие обновления исходных данных в целевой таблице. Текущий адаптер для ClickHouse также поддерживает материализации dictionary, distributed table и distributed incremental. Адаптер также поддерживает dbt снимки и seed. Ниже перечислены экспериментальные возможности в dbt-clickhouse:

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

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

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

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

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

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

Теперь вы можете использовать этот профиль в одном из существующих проектов или создать новый с помощью:
В каталоге project_name обновите файл dbt_project.yml, указав имя профиля для подключения к серверу ClickHouse.

​
Проверка подключения

Выполните команду 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), чтобы сократить время выполнения проекта и избежать расхождения схем между средами. Чтобы среды разработки оставались синхронизированными и модели не запускались на устаревших развертываниях, можно использовать clone или даже defer. Мы рекомендуем использовать выделенный кластер или сервис ClickHouse для тестовой среды (то есть staging-среды), чтобы не влиять на работу вашей среды продакшн. Чтобы тестовая среда была репрезентативной, важно использовать подмножество данных из продакшн, а также запускать dbt так, чтобы не допускать расхождения схем между средами.
  • Если вам не нужны свежие данные для тестирования, можно восстановить резервную копию данных из продакшн в staging-среду.
  • Если вам нужны свежие данные для тестирования, можно использовать сочетание table function remoteSecure() и refreshable materialized views, чтобы выполнять вставку с нужной частотой. Другой вариант — использовать Объектное хранилище как промежуточное хранилище, периодически записывать в него данные из вашего продакшн-сервиса, а затем импортировать их в staging-среду с помощью table functions для Объектного хранилища или 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 могут конфликтовать, если выполняются одновременно, поскольку внутри они могут использовать одинаковые имена таблиц для одних и тех же операций. Подробнее см. issue #420.
  • Сейчас адаптер материализует модели в виде таблиц с использованием INSERT INTO SELECT. На практике это означает дублирование данных при повторном запуске. Очень большие датасеты (PB) могут приводить к крайне долгому времени выполнения, из-за чего некоторые модели становятся непрактичными. Чтобы повысить производительность, используйте materialized views ClickHouse, реализуя представление как materialized: materialization_view. Кроме того, старайтесь по возможности уменьшать количество строк, возвращаемых любым запросом, используя GROUP BY. Предпочтительнее модели, которые агрегируют данные, а не просто преобразуют их, сохраняя количество строк источника.
  • Чтобы использовать Distributed tables для представления модели, необходимо вручную создать базовые реплицируемые таблицы на каждом узле. Затем поверх них можно создать Distributed таблицу. Адаптер не управляет созданием cluster.
  • Когда dbt создает отношение (table/view) в database, оно обычно создается в виде: {{ database }}.{{ schema }}.{{ table/view id }}. В ClickHouse нет понятия схем. Поэтому адаптер использует {{schema}}.{{ table/view id }}, где schema — это database ClickHouse.
  • Эфемерные модели/CTE не работают, если размещены перед INSERT INTO в операторе вставки ClickHouse, см. https://github.com/ClickHouse/ClickHouse/issues/30323. Это не должно затрагивать большинство моделей, но следует учитывать, где именно эфемерная модель размещается в определениях моделей и других SQL-командах.

​
Fivetran

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