Skip to main content
В этом разделе описаны все материализации, доступные в dbt-clickhouse, включая экспериментальные возможности.

Общие конфигурации материализаций

В следующей таблице показаны конфигурации, общие для некоторых доступных материализаций. Подробную информацию об общих конфигурациях моделей dbt см. в документации dbt:

Поддерживаемые движки таблиц

Примечание: для материализованных представлений поддерживаются все движки *MergeTree.

Экспериментально поддерживаемые движки таблиц

Если при подключении dbt к ClickHouse с использованием одного из указанных выше движков у вас возникают проблемы, сообщите о них здесь.

Примечание о настройках модели

В ClickHouse есть несколько типов/уровней «настроек». В приведенной выше конфигурации модели можно настраивать два их типа. settings означает предложение SETTINGS, используемое в DDL-операторах типа CREATE TABLE/VIEW, то есть обычно это настройки, специфичные для конкретного движка таблицы ClickHouse. Новый query_settings используется для добавления предложения SETTINGS в запросы INSERT и DELETE, применяемые при материализации модели ( включая инкрементные материализации). Существуют сотни настроек ClickHouse, и не всегда очевидно, какая из них является настройкой таблицы, а какая — настройкой пользователя (хотя последние, как правило, доступны в таблице system.settings.) В целом рекомендуется использовать значения по умолчанию, а к использованию этих свойств следует подходить только после тщательного изучения и тестирования.

Конфигурация столбца

ПРИМЕЧАНИЕ: Чтобы использовать указанные ниже параметры конфигурации столбца, необходимо включить контракты моделей.

Пример конфигурации схемы

Добавление сложных типов

dbt автоматически определяет тип данных каждого столбца, анализируя SQL, используемый для создания модели. Однако в некоторых случаях этот процесс может определять тип данных неточно, что приводит к конфликтам с типами, указанными в свойстве data_type контракта. Чтобы избежать этого, мы рекомендуем использовать функцию CAST() в SQL модели, чтобы явно указать нужный тип. Например:

Материализация: представление

Модель dbt можно создать как представление ClickHouse и настроить, используя следующий синтаксис: Файл проекта (dbt_project.yml):
Или блок config (models/<model_name>.sql):

Материализация: таблица

Модель dbt можно создать в виде таблицы ClickHouse и настроить, используя следующий синтаксис: Файл проекта (dbt_project.yml):
Или блок config (models/<model_name>.sql):

Индексы пропуска данных

Вы можете добавлять индексы пропуска данных к материализациям table, используя конфигурацию indexes:

Проекции

Вы можете добавлять проекции в материализации table и distributed_table с помощью конфигурации projections:
Примечание: Для distributed таблиц проекция применяется к таблицам _local, а не к прокси-таблице distributed.

Материализация: инкрементальная

Модель типа table будет пересоздаваться при каждом запуске dbt. Это может оказаться непрактичным и чрезвычайно затратным для больших результирующих наборов или сложных преобразований. Чтобы решить эту проблему и сократить время сборки, модель dbt можно создать как инкрементальную таблицу ClickHouse и настроить с помощью следующего синтаксиса: Определение модели в dbt_project.yml:
Или блок config в models/<model_name>.sql:

Конфигурации

Ниже перечислены конфигурации, характерные для этого типа материализации:

Стратегии инкрементальных моделей

dbt-clickhouse поддерживает три стратегии для инкрементальных моделей.

Стратегия по умолчанию (устаревшая)

Исторически ClickHouse поддерживал обновления и удаления лишь ограниченно — в виде асинхронных «мутаций». Чтобы эмулировать ожидаемое поведение dbt, dbt-clickhouse по умолчанию создает новую временную таблицу, содержащую все незатронутые (не удаленные и не измененные) «старые» записи, а также все новые или обновленные записи, а затем меняет местами или выполняет EXCHANGE этой временной таблицы с существующим отношением инкрементальной модели. Это единственная стратегия, которая сохраняет исходное отношение, если что-то пойдет не так до завершения операции; однако, поскольку она требует полного копирования исходной таблицы, ее выполнение может быть довольно дорогим и медленным.

Стратегия Delete+Insert

ClickHouse добавил “легковесные удаления” как экспериментальную возможность в версии 22.8. Легковесные удаления значительно быстрее, чем операции ALTER TABLE … DELETE, поскольку не требуют перезаписи частей данных ClickHouse. Инкрементальная стратегия delete+insert использует легковесные удаления для реализации инкрементальных материализаций, которые работают значительно лучше, чем “устаревшая” стратегия. Однако при использовании этой стратегии есть важные оговорки:
  • Легковесные удаления должны быть включены на вашем сервере ClickHouse с помощью настройки allow_experimental_lightweight_delete=1, либо необходимо установить use_lw_deletes=true в вашем профиле (это включит эту настройку для ваших сеансов dbt)
  • Легковесные удаления теперь готовы для продакшн, но в версиях ClickHouse ниже 23.3 возможны проблемы с производительностью и другие неполадки.
  • Эта стратегия работает напрямую с затронутой таблицей/отношением (без создания каких-либо промежуточных или временных таблиц), поэтому, если во время операции возникнет проблема, данные в инкрементальной модели, скорее всего, окажутся в некорректном состоянии
  • При использовании легковесных удалений dbt-clickhouse включает настройку allow_nondeterministic_mutations. В некоторых очень редких случаях использование недетерминированных incremental_predicates может привести к состоянию гонки для обновляемых/удаляемых элементов (и связанным сообщениям лога в журналах ClickHouse). Чтобы обеспечить согласованные результаты, инкрементальные предикаты должны включать только подзапросы к данным, которые не будут изменяться во время инкрементальной материализации.

Стратегия Microbatch (требуется dbt-core >= 1.9)

Инкрементальная стратегия microbatch доступна в dbt-core начиная с версии 1.9 и предназначена для эффективной обработки масштабных преобразований временных рядов. В dbt-clickhouse она основана на существующей инкрементальной стратегии delete_insert, разбивая инкрементальную обработку на заранее определённые батчи временных рядов на основе конфигураций модели event_time и batch_size. Помимо обработки масштабных преобразований, Microbatch позволяет: Подробные сведения об использовании Microbatch см. в официальной документации.
Доступные конфигурации Microbatch

Стратегия Append

Эта стратегия заменяет настройку inserts_only в предыдущих версиях dbt-clickhouse. При таком подходе новые строки просто добавляются в существующее отношение. В результате дубликаты строк не удаляются, и временная или промежуточная таблица не используется. Это самый быстрый подход, если дубликаты либо допустимы в данных, либо исключаются предложением WHERE/фильтром в инкрементальном запросе.

Стратегия insert_overwrite (экспериментальная)

[IMPORTANT] В настоящее время стратегия insert_overwrite не полностью поддерживается для распределённых материализаций.
Выполняет следующие шаги:
  1. Создаёт staging-таблицу (временную) с той же структурой, что и отношение инкрементальной модели: CREATE TABLE <staging> AS <target>.
  2. Выполняет вставку только новых записей (созданных SELECT) в staging-таблицу.
  3. Заменяет в целевой таблице только новые партиции (присутствующие в staging-таблице).
У этого подхода есть следующие преимущества:
  • Он быстрее стратегии по умолчанию, потому что не копирует таблицу целиком.
  • Он безопаснее других стратегий, потому что не изменяет исходную таблицу, пока операция INSERT не завершится успешно: в случае сбоя на промежуточном этапе исходная таблица не изменяется.
  • Он реализует лучшую практику data engineering — «неизменяемость партиций». Это упрощает инкрементальную и параллельную обработку данных, откаты и т. д.
Для этой стратегии в config модели должен быть задан partition_by. Все остальные параметры config модели, специфичные для стратегии, игнорируются.

Материализация: materialized_view

Материализация materialized_view создаёт в ClickHouse materialized view, который служит триггером вставки: он автоматически преобразует и вставляет новые строки из исходной таблицы в целевую таблицу. Это одна из самых мощных материализаций в dbt-clickhouse. Из-за объёма материала эта материализация вынесена на отдельную страницу. Перейдите к руководству по Materialized Views, чтобы ознакомиться с полной документацией

Материализация: словарь (экспериментальный)

См. тесты в https://github.com/ClickHouse/dbt-clickhouse/blob/main/tests/integration/adapter/dictionary/test&#95;dictionary.py с примерами того, как реализовать материализации для словарей ClickHouse

Материализация: distributed_table (экспериментальная)

distributed таблица создается следующим образом:
  1. Создается временное представление с SQL-запросом, чтобы получить нужную структуру
  2. Создаются пустые локальные таблицы на основе представления
  3. Создается distributed таблица на основе локальных таблиц.
  4. Данные вставляются в distributed таблицу и распределяются по сегментам без дублирования.
Примечания:
  • Запросы dbt-clickhouse теперь автоматически включают настройку insert_distributed_sync = 1, чтобы последующие операции инкрементальной материализации выполнялись корректно. Из-за этого некоторые вставки в distributed таблицу могут выполняться медленнее, чем ожидалось.

Пример модели для distributed таблицы

Сгенерированные миграции

Конфигурации

Ниже перечислены конфигурации, специфичные для этого типа материализации:

материализация: distributed_incremental (экспериментальная)

Инкрементальная модель, основанная на той же идее, что и distributed таблица; основная сложность заключается в корректной обработке всех инкрементальных стратегий.
  1. Стратегия Append просто выполняет вставку данных в distributed таблицу.
  2. Стратегия Delete+Insert создает временную distributed таблицу для работы со всеми данными на каждом сегменте.
  3. Стратегия Default (Legacy) создает временную и промежуточную distributed таблицы по той же причине.
Заменяются только таблицы сегментов, поскольку distributed таблица не хранит данные. Distributed таблица перезагружается только при включенном режиме full_refresh или если структура таблицы могла измениться.

Пример инкрементальной модели Distributed

Созданные миграции

Снимок

Снимки dbt позволяют отслеживать изменения в изменяемой модели с течением времени. Это, в свою очередь, позволяет выполнять запросы к моделям на определённый момент времени, при которых аналитики могут “заглянуть в прошлое” и увидеть предыдущее состояние модели. Эта функциональность поддерживается коннектором ClickHouse и настраивается с помощью следующего синтаксиса: Блок config в snapshots/<model_name>.sql:
Чтобы узнать больше о конфигурации, см. справочную страницу по конфигурациям снимков.

Контракты и ограничения

Поддерживаются только контракты, в которых типы столбцов должны точно совпадать. Например, контракт с типом столбца UInt32 завершится ошибкой, если модель возвращает UInt64 или другой целочисленный тип. ClickHouse также поддерживает только ограничения CHECK для всей таблицы/модели. Первичный ключ, внешний ключ, уникальные ограничения и ограничения CHECK на уровне столбца не поддерживаются. (См. документацию ClickHouse о первичных ключах и ключах ORDER BY.)
Последнее изменение 24 июля 2026 г.