Общие конфигурации материализаций
Поддерживаемые движки таблиц
Примечание: для материализованных представлений поддерживаются все движки *MergeTree.
Экспериментально поддерживаемые движки таблиц
Если при подключении dbt к ClickHouse с использованием одного из указанных выше движков у вас возникают проблемы, сообщите о них здесь.
Примечание о настройках модели
settings означает предложение SETTINGS,
используемое в DDL-операторах типа CREATE TABLE/VIEW, то есть обычно это настройки, специфичные для
конкретного движка таблицы ClickHouse. Новый
query_settings используется для добавления предложения SETTINGS в запросы INSERT и DELETE, применяемые при материализации модели (
включая инкрементные материализации).
Существуют сотни настроек ClickHouse, и не всегда очевидно, какая из них является настройкой таблицы, а какая — настройкой пользователя
(хотя последние, как правило,
доступны в таблице system.settings.) В целом рекомендуется использовать значения по умолчанию, а к использованию этих свойств
следует подходить только после тщательного изучения и тестирования.
Конфигурация столбца
ПРИМЕЧАНИЕ: Чтобы использовать указанные ниже параметры конфигурации столбца, необходимо включить контракты моделей.
Пример конфигурации схемы
Добавление сложных типов
data_type контракта. Чтобы избежать этого, мы рекомендуем использовать функцию CAST() в SQL модели, чтобы явно указать нужный тип. Например:
Материализация: представление
dbt_project.yml):
config (models/<model_name>.sql):
Материализация: таблица
dbt_project.yml):
models/<model_name>.sql):
Индексы пропуска данных
table, используя конфигурацию indexes:
Проекции
table и distributed_table с помощью конфигурации projections. Для каждой записи проекции требуется ключ query или index (но не оба).
Примечание: Для distributed таблиц проекция применяется к таблицам _local, а не к прокси-таблице distributed.
Примечание: Указание одновременно query и index в одной записи проекции вызывает ошибку на этапе компиляции.
Проекции запросов
query, чтобы задать полный запрос проекции:
Индексные проекции
index как синтаксический сахар для легковесных индексных проекций, использующих виртуальный столбец _part_offset. В качестве ключа сортировки укажите имя одного столбца или список столбцов:
Материализация: инкрементальная
dbt_project.yml:
config в models/<model_name>.sql:
Конфигурации
Стратегии инкрементальных моделей
dbt-clickhouse поддерживает три стратегии для инкрементальных моделей.
Стратегия по умолчанию (устаревшая)
Стратегия Delete+Insert
delete+insert использует легковесное удаление, чтобы удалить затронутые строки, а затем вставить новые. Поскольку она не копирует всю таблицу, её производительность значительно выше, чем у стратегии «legacy». Если в профиле задать use_lw_deletes: true, delete+insert станет инкрементальной стратегией по умолчанию.
При использовании этой стратегии следует учитывать несколько важных ограничений:
- Она работает непосредственно с затронутой таблицей, не создавая промежуточных или временных таблиц, поэтому при возникновении проблемы во время операции данные в инкрементальной модели, скорее всего, окажутся в некорректном состоянии.
- Для неё требуется настройка ClickHouse
allow_nondeterministic_mutations. Адаптер автоматически включает её в своих сеансах, когда это возможно. Если включить её нельзя (например, она доступна пользователю dbt только для чтения), поведение зависит от способа выбора стратегии: модели, использующие стратегию по умолчанию, незаметно переключаются на стратегию legacy, модели, в которых явно заданаdelete+insertилиmicrobatch, завершаются ошибкой во время выполнения, аuse_lw_deletes: trueв профиле вызывает ошибку при подключении. - В некоторых крайне редких случаях использование недетерминированных
incremental_predicatesможет привести к состоянию гонки для обновляемых или удаляемых элементов. Чтобы обеспечить согласованные результаты, инкрементальные предикаты должны включать только подзапросы к данным, которые не будут изменяться во время инкрементальной материализации.
Стратегия Microbatch (требуется dbt-core >= 1.9)
microbatch доступна в dbt-core начиная с версии 1.9 и предназначена для эффективной обработки масштабных преобразований временных рядов. В dbt-clickhouse она основана на существующей инкрементальной стратегии delete_insert, разбивая инкрементальную обработку на заранее определённые батчи временных рядов на основе конфигураций модели event_time и batch_size.
Помимо обработки масштабных преобразований, Microbatch позволяет:
- Повторно обрабатывать неуспешные батчи.
- Автоматически определять параллельное выполнение батчей.
- Избавиться от необходимости в сложной условной логике при дозагрузке.
Доступные конфигурации Microbatch
Стратегия Append
inserts_only в предыдущих версиях dbt-clickhouse. При таком подходе новые строки просто добавляются
в существующее отношение.
В результате дубликаты строк не удаляются, и временная или промежуточная таблица не используется. Это самый быстрый
подход, если дубликаты либо допустимы
в данных, либо исключаются предложением WHERE/фильтром в инкрементальном запросе.
Стратегия insert_overwrite (экспериментальная)
[IMPORTANT] В настоящее время стратегия insert_overwrite не полностью поддерживается для распределённых материализаций.Выполняет следующие шаги:
- Создаёт staging-таблицу (временную) с той же структурой, что и отношение инкрементальной модели:
CREATE TABLE <staging> AS <target>. - Выполняет вставку только новых записей (созданных
SELECT) в staging-таблицу. - Заменяет в целевой таблице только новые партиции (присутствующие в staging-таблице).
- Он быстрее стратегии по умолчанию, потому что не копирует таблицу целиком.
- Он безопаснее других стратегий, потому что не изменяет исходную таблицу, пока операция INSERT не завершится успешно: в случае сбоя на промежуточном этапе исходная таблица не изменяется.
- Он реализует лучшую практику data engineering — «неизменяемость партиций». Это упрощает инкрементальную и параллельную обработку данных, откаты и т. д.
partition_by. Все остальные параметры config модели,
специфичные для стратегии, игнорируются.
Материализация: materialized_view
materialized_view создаёт в ClickHouse materialized view, который служит триггером вставки: он автоматически преобразует и вставляет новые строки из исходной таблицы в целевую таблицу. Это одна из самых мощных материализаций в dbt-clickhouse.
Из-за объёма материала эта материализация вынесена на отдельную страницу. Перейдите к руководству по Materialized Views, чтобы ознакомиться с полной документацией
Материализация: словарь (экспериментальный)
dbt run словарь заменяется текущим определением модели с помощью CREATE OR REPLACE DICTIONARY.
Конфигурации
Пример с источником данных ClickHouse
Пример с HTTP-источником
source_type='http' (или параметра table) источником служит не SQL модели, однако dbt по-прежнему требует тело запроса — используйте в качестве заполнителя select 1:
Материализация: distributed_table (экспериментальная)
- Создается временное представление с SQL-запросом, чтобы получить нужную структуру
- Создаются пустые локальные таблицы на основе представления
- Создается distributed таблица на основе локальных таблиц.
- Данные вставляются в distributed таблицу и распределяются по сегментам без дублирования.
- Запросы dbt-clickhouse теперь автоматически включают настройку
insert_distributed_sync = 1, чтобы последующие операции инкрементальной материализации выполнялись корректно. Из-за этого некоторые вставки в distributed таблицу могут выполняться медленнее, чем ожидалось.
Пример модели для distributed таблицы
Сгенерированные миграции
Конфигурации
материализация: distributed_incremental (экспериментальная)
- Стратегия Append просто выполняет вставку данных в distributed таблицу.
- Стратегия Delete+Insert создает временную distributed таблицу для работы со всеми данными на каждом сегменте.
- Стратегия Default (Legacy) создает временную и промежуточную distributed таблицы по той же причине.
Пример инкрементальной модели Distributed
Созданные миграции
Снимок
snapshots/<model_name>.sql:
Контракты и ограничения
CHECK для всей таблицы/модели. Первичный ключ, внешний ключ, уникальные ограничения и
ограничения CHECK на уровне столбца не поддерживаются.
(См. документацию ClickHouse о первичных ключах и ключах ORDER BY.)