Skip to main content
В этом разделе описаны некоторые возможности dbt для ClickHouse.

Настройки Profile.yml

Чтобы подключить dbt к ClickHouse, нужно добавить профиль в файл profiles.yml. Профиль ClickHouse имеет следующий синтаксис:

Схема и база данных

Идентификатор отношения модели dbt database.schema.table несовместим с ClickHouse, поскольку ClickHouse не поддерживает schema. Поэтому используется упрощённый вариант schema.table, где schema — это база данных ClickHouse. Использовать базу данных default не рекомендуется.

Предупреждение об операторе SET

Во многих средах использование оператора SET для сохранения настройки ClickHouse во всех запросах DBT ненадежно и может приводить к неожиданным сбоям. Это особенно актуально при использовании HTTP-соединений через балансировщик нагрузки, который распределяет запросы между несколькими узлами (например, в ClickHouse Cloud), хотя в некоторых случаях это также может происходить и при использовании нативных соединений ClickHouse. Поэтому в качестве рекомендуемой практики мы советуем задавать все необходимые настройки ClickHouse в свойстве “custom_settings” профиля DBT, а не полагаться на pre-hook-оператор “SET”, как иногда рекомендуется.

Настройка quote_columns

Чтобы избежать предупреждения, явно задайте значение quote_columns в файле dbt_project.yml. Подробнее см. в документации по quote_columns.

О кластере ClickHouse

При использовании кластера ClickHouse нужно учитывать две вещи:
  • Настройку параметра cluster.
  • Обеспечение согласованности чтения после записи, особенно если вы используете более одного threads.

Параметр cluster

Параметр cluster в профиле позволяет dbt-clickhouse работать с кластером ClickHouse. Если в профиле задан cluster, по умолчанию все модели будут создаваться с предложением ON CLUSTER — кроме тех, которые используют движок Replicated. Сюда входят:
  • Создание базы данных
  • Материализации представлений
  • Материализации таблиц и incremental-моделей
  • Распределённая материализация
Для движков Replicated предложение ON CLUSTER не добавляется, поскольку они сами управляют репликацией. Чтобы отключить создание через кластер для конкретной модели, добавьте config disable_on_cluster:
Материализации table и incremental с нереплицируемым движком не будут зависеть от настройки cluster (модель будет создана только на том узле, к которому установлено подключение). Совместимость Если модель была создана без настройки cluster, dbt-clickhouse обнаружит это и выполнит все DDL/DML без предложения on cluster для этой модели.

Согласованность чтения после записи

dbt использует модель согласованности чтения после вставки. Она несовместима с кластерами ClickHouse, в которых больше одной реплики, если нельзя гарантировать, что все операции будут направляться в одну и ту же реплику. В повседневной работе с dbt вы можете и не столкнуться с проблемами, но в зависимости от конфигурации кластера есть несколько способов обеспечить такую гарантию:
  • Если вы используете кластер ClickHouse Cloud, достаточно задать select_sequential_consistency: 1 в свойстве custom_settings вашего профиля. Подробнее об этой настройке можно узнать здесь.
  • Если вы используете самоуправляемый кластер, убедитесь, что все запросы dbt отправляются в одну и ту же реплику ClickHouse. Если перед ним установлен балансировщик нагрузки, попробуйте использовать механизм replica aware routing/sticky sessions, чтобы всегда попадать в одну и ту же реплику. Добавлять настройку select_sequential_consistency = 1 в кластерах вне ClickHouse Cloud не рекомендуется.

Дополнительные макросы ClickHouse

Вспомогательные макросы материализации моделей

Следующие макросы включены для упрощения создания таблиц и представлений ClickHouse:
  • engine_clause — Использует свойство конфигурации model engine для назначения движка таблицы ClickHouse. dbt-clickhouse по умолчанию использует движок MergeTree.
  • partition_cols — Использует свойство конфигурации model partition_by для назначения ключа партиционирования ClickHouse. По умолчанию ключ партиционирования не назначается.
  • order_cols — Использует конфигурацию model order_by для назначения ключа сортировки ClickHouse (ORDER BY). Если не указано, ClickHouse будет использовать пустой tuple(), и таблица не будет отсортирована
  • primary_key_clause — Использует свойство конфигурации model primary_key для назначения первичного ключа ClickHouse. По умолчанию первичный ключ задан, и ClickHouse будет использовать предложение ORDER BY в качестве первичного ключа.
  • on_cluster_clause — Использует свойство профиля cluster для добавления предложения ON CLUSTER к некоторым операциям dbt: распределённым материализациям, созданию представлений, созданию баз данных.
  • ttl_config — Использует свойство конфигурации model ttl для назначения выражения TTL таблицы ClickHouse. По умолчанию TTL не назначается.

Вспомогательный макрос s3Source

Макрос s3source упрощает выборку данных ClickHouse напрямую из S3 с помощью табличной функции S3 в ClickHouse. Он работает, подставляя параметры табличной функции S3 из именованного словаря конфигурации (имя словаря должно оканчиваться на s3). Макрос сначала ищет словарь в vars профиля, а затем в конфигурации модели. Словарь может содержать любые из следующих ключей, используемых для заполнения параметров табличной функции S3: См. тестовый файл S3 с примерами использования этого макроса.

Поддержка макросов для разных баз данных

dbt-clickhouse теперь поддерживает большинство макросов для разных баз данных, включённых в dbt Core, за следующими исключениями:
  • SQL-функция split_part реализована в ClickHouse с помощью функции splitByChar. Эта функция требует использования константной строки в качестве разделителя для split, поэтому параметр delimeter, используемый в этом макросе, будет интерпретироваться как строка, а не как имя столбца
  • Аналогично, SQL-функция replace в ClickHouse требует константных строк для параметров old_chars и new_chars, поэтому при вызове этого макроса эти параметры будут интерпретироваться как строки, а не как имена столбцов.

Поддержка каталога

Статус интеграции с каталогом в dbt

В dbt Core v1.10 появилась поддержка интеграции с каталогами, которая позволяет адаптерам материализовывать модели во внешние каталоги, управляющие открытыми табличными форматами, такими как Apache Iceberg. Эта возможность пока ещё не реализована в dbt-clickhouse на нативном уровне. Отслеживать ход реализации этой возможности можно в issue #489 на GitHub.

Поддержка каталогов в ClickHouse

Недавно ClickHouse добавил встроенную поддержку таблиц Apache Iceberg и каталогов данных. Большинство возможностей всё ещё имеют статус experimental, но ими уже можно пользоваться, если у вас установлена актуальная версия ClickHouse.
  • Вы можете использовать ClickHouse, чтобы выполнять запросы к таблицам Iceberg, хранящимся в объектном хранилище (S3, Azure Blob Storage, Google Cloud Storage), с помощью движка таблицы Iceberg и табличной функции iceberg.
  • Кроме того, ClickHouse предоставляет движок базы данных DataLakeCatalog, который позволяет подключаться к внешним каталогам данных, включая Каталог AWS Glue, Databricks Unity Catalog, Hive Metastore и REST-каталоги. Это позволяет напрямую выполнять запросы к данным в открытых табличных форматах (Iceberg, Delta Lake) из внешних каталогов без дублирования данных.

Обходные решения для работы с Iceberg и каталогами

Вы можете читать данные из таблиц Iceberg или каталогов в своем проекте dbt, если уже настроили их в кластере ClickHouse с помощью описанных выше инструментов. Для обращения к этим таблицам в проектах dbt можно использовать функциональность source. Например, если вы хотите получить доступ к своим таблицам в REST Catalog, вы можете:
  1. Создать базу данных, указывающую на внешний каталог:
  1. Определите базу данных каталога и её таблицы как источники в dbt: убедитесь, что эти таблицы уже доступны в ClickHouse
  1. Используйте таблицы каталога в моделях dbt:

Примечания по обходным решениям

Преимущества этих обходных решений:
  • Вы получите немедленный доступ к различным типам внешних таблиц и внешним каталогам без необходимости ждать появления встроенной интеграции каталогов в dbt.
  • У вас будет плавный путь миграции, когда станет доступна встроенная поддержка каталогов.
Но сейчас есть и некоторые ограничения:
  • Ручная настройка: таблицы Iceberg и базы данных каталогов необходимо создавать вручную в ClickHouse, прежде чем на них можно будет ссылаться в dbt.
  • Нет DDL на уровне каталога: dbt не может управлять операциями на уровне каталога, такими как создание или удаление таблиц Iceberg во внешних каталогах. Поэтому сейчас вы не сможете создавать их из коннектора dbt. Возможность создания таблиц с движками Iceberg() может появиться в будущем.
  • Операции записи: В настоящее время возможности записи в таблицы Iceberg/Data Catalog ограничены. Ознакомьтесь с документацией ClickHouse, чтобы понять, какие варианты доступны.
Последнее изменение 24 июля 2026 г.