Лучшие практики для озер данных

Рекомендации для продакшна по работе с открытыми табличными форматами в ClickHouse: варианты интеграции, настройка производительности, настройка каталога и отладка.

Руководство «Начало работы» поможет вам выполнить первые запросы к Apache Iceberg, Delta Lake, Apache Hudi и Apache Paimon. После завершения начальной настройки используйте эту страницу, чтобы выбрать подходящий паттерн доступа, настроить производительность запросов и отлаживать запросы к озеру данных в продакшне.

​

Выберите способ доступа

Способ доступа	Когда использовать	Примеры
Табличная функция	Разовые запросы к известному пути	icebergS3(), deltaLake(), hudi(), paimon()
Движок таблицы	Регулярные запросы к одному и тому же пути без каталога	IcebergS3, DeltaLake, Hudi
DataLakeCatalog движок базы данных	Рабочие нагрузки в продакшне с каталогом; федеративные запросы ко множеству таблиц	AWS Glue, Unity Catalog, REST-каталог

​

Табличные функции

Укажите путь к хранилищу и учетные данные прямо в запросе, если вам известно расположение и не нужно сохранять определение таблицы.

SELECT count()
FROM icebergS3('https://my-bucket.s3.amazonaws.com/warehouse/my_table/')
WHERE event_date >= today() - 7

Используйте вариант S3 для AWS S3 и GCS. Для Azure и локальной файловой системы предусмотрены отдельные варианты (icebergAzure, icebergLocal и эквиваленты для других форматов). Полный список см. в разделе Прямое выполнение запросов.

Paimon предоставляет табличные функции и экспериментальные движки таблиц.

​

Движки таблиц

Создайте таблицу с движком таблицы, если планируете многократно выполнять запросы к одному и тому же path. ClickHouse хранит path и учетные данные в метаданных таблицы, поэтому можно выполнять запросы к обычной таблице по ее имени, не воссоздавая каждый раз вызов функции.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')

SELECT count() FROM events WHERE event_date = today()

Движки таблиц поддерживают те же возможности чтения, что и табличные функции, включая кэширование данных и кэширование метаданных. Данные в ClickHouse никогда не дублируются. Движок таблицы удобен, если вы предоставляете доступ команде или выполняете задачи по расписанию для одной и той же таблицы.

​

DataLakeCatalog движок базы данных

Подключите ClickHouse один раз к внешнему каталогу данных, в котором зарегистрированы таблицы. Каждая таблица из каталога автоматически становится таблицей ClickHouse, включая таблицы, добавленные после создания подключения.

CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
    catalog_type = 'glue',
    region = 'us-east-1',
    aws_access_key_id = '<key>',
    aws_secret_access_key = '<secret>'

SELECT count() FROM my_lake.`analytics.events`

Этот вариант масштабируется лучше, чем создание отдельных определений таблиц, если вы управляете большим числом таблиц или несколькими каталогами. См. Подключение к каталогам и руководства по каталогам.

Обратные кавычки для составных имён таблиц

В каталогах часто используется формат именования database.table. Заключайте полное имя с указанием базы данных в обратные кавычки, как в примере выше.

​

Обязательные настройки

Для многих интеграций перед первым использованием требуется флаг функции. Если CREATE DATABASE завершается ошибкой прав доступа, проверьте версию вашего сервиса.

Для подключений к каталогам у каждого типа каталога есть свой флаг. Общую информацию см. в Подключение к каталогам, а сведения о настройках — в справочнике DataLakeCatalog. Инструкции по настройке для конкретных каталогов приведены в руководствах по каталогам.

Для записи в Iceberg требуется allow_insert_into_iceberg (25.7+, бета с 26.2). См. Запись в озера данных. Для Delta Lake требуется allow_delta_lake_writes (25.9+). В матрице поддержки указано, какие флаги применяются к каждому формату и операции.

​

Повысьте производительность запросов

Номера версий на этой странице соответствуют версиям релизов ClickHouse (Cloud и самоуправляемых установок). Перед включением какой-либо настройки или возможности проверьте версию своего сервиса.

Производительность запросов к Lake зависит от объёма метаданных и количества файлов Parquet, которые ClickHouse читает из Объектного хранилища. Как и в случае с любой таблицей ClickHouse, производительность запросов повышается при фильтрации по столбцам партиции и выборе меньшего числа столбцов.

​

Рекомендации по написанию запросов

Фильтруйте по столбцам партиций в WHERE. Iceberg и Delta Lake хранят метаданные партиций, которые позволяют ClickHouse пропускать ненужные файлы на этапе планирования запроса. Если условие фильтрации относится к столбцу вне спецификации партиционирования, ClickHouse будет сканировать каждый подходящий файл.

Для таблиц Iceberg со скрытым партиционированием фильтруйте по исходному столбцу в схеме таблицы, а не по отдельному столбцу партиции или имени преобразованного поля. Если таблица партиционирована по day(event_time), добавьте условие для event_time. ClickHouse выполнит отсечение партиций на основе этого фильтра, используя спецификацию партиционирования Iceberg. См. Отсечение партиций и спецификацию Iceberg.

SELECT count()
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
  AND event_time < '2026-03-02'

Указывайте только нужные столбцы вместо SELECT *. ClickHouse читает Parquet из Объектного хранилища постолбцово, поэтому чем меньше столбцов выбирается, тем меньше данных передаётся и распаковывается.

Помещайте избирательные фильтры в WHERE. Начиная с ClickHouse 26.2+, PREWHERE также поддерживается при чтении таблиц Iceberg и других lake-таблиц: в этом случае фильтрация выполняется на уровне Parquet до чтения остальных столбцов. Однако отсечение партиций по-прежнему зависит от фильтрации исходных столбцов партиции, а не только от PREWHERE.

Для таблиц Iceberg с большим количеством position or equality deletes при сканировании применяется фильтрация merge-on-read. Ожидайте, что на каждый файл потребуется больше работы, чем можно предположить только по отсечению на уровне манифеста.

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

​

Параллельное чтение в многоузловых кластерах

В ClickHouse Cloud и самоуправляемых многоузловых сервисах кластерные варианты lake-табличных функций распределяют чтение файлов Parquet между репликами. Узел-инициатор параллельно распределяет файлы между воркерами. Используйте кластерные варианты для батч-чтения и загрузок по расписанию при работе с большими таблицами. В одноузловых развертываниях достаточно стандартной табличной функции.

Передайте имя вашего кластера первым аргументом ('default' в ClickHouse Cloud). Кластерные варианты доступны для всех поддерживаемых форматов:

Формат	Кластерные функции
Iceberg	icebergS3Cluster(), icebergAzureCluster()
Delta Lake	deltaLakeCluster(), deltaLakeAzureCluster()
Hudi	hudiCluster()
Paimon	paimonS3Cluster()

Кластерное чтение можно сочетать с другими настройками производительности.

​

Кластерные функции и On-Demand Compute

Кластерные варианты функций, такие как icebergS3Cluster и deltaLakeCluster, распределяют чтение файлов между узлами вашего существующего кластера. Сама кластерная функция не добавляет вычислительных ресурсов. On-Demand Compute — это возможность ClickHouse Cloud, которая временно выделяет подходящим запросам дополнительных воркеров из управляемого пула, используя ваш существующий сервис и конечную точку.

В период закрытой предварительной версии On-Demand Compute поддерживает только подходящие запросы SELECT к поддерживаемым данным Apache Iceberg и Delta Lake. Условия применимости и ограничения см. в документации по On-Demand Compute.

​

Ограничение батч-чтений диапазоном снимков

Для повторяющихся батч-загрузок из таблиц в data lake ограничивайте каждый запуск диапазоном снимков, а не перечитывайте всю таблицу целиком. Без таких границ ClickHouse может при каждом запуске сканировать все версии и файлы, что увеличивает число чтений из Объектного хранилища и время выполнения запроса.

Сохраняйте идентификатор снимка из последней успешной загрузки и используйте его как нижнюю границу при следующем запуске.

• Для Iceberg читайте состояние на определённый момент времени с помощью iceberg_snapshot_id или iceberg_timestamp_ms (25.4+). Для таблиц, в которые данные только добавляются, сочетайте настройки снимков с фильтрами по партициям в WHERE. Используйте system.iceberg_history (25.6+), чтобы находить ID снимков между запусками.
• Для Delta Lake читайте изменения между двумя версиями с помощью delta_lake_snapshot_start_version и delta_lake_snapshot_end_version (25.12+). Чтобы прочитать один снимок, используйте delta_lake_snapshot_version (25.8+). Пример CDF см. в разделе change data feed в Delta.

​

Локальное кэширование файлов Parquet

Оба формата поддерживают enable_filesystem_cache, чтобы сохранять часто используемые файлы Parquet на локальном диске между запросами. В самоуправляемых развертываниях настройте диск файлового кэша в конфигурации сервера, чтобы этому параметру было куда записывать данные. В ClickHouse Cloud кэширование настраивается автоматически. При бенчмаркинге установите enable_filesystem_cache = 0, чтобы попадания в кэш не скрывали изменения между запусками.

​

Apache Iceberg

Большинство оптимизаций чтения в Iceberg включено по умолчанию. Приведённые ниже настройки управляют отсечением партиций, кэшированием метаданных и числом обращений к каталогу.

​

Настройки чтения

Настройка	С версии	По умолчанию	Примечания
use_iceberg_partition_pruning	25.1	1 с 25.6	Пропускает файлы данных на основе метаданных партиций в манифестах
use_iceberg_metadata_files_cache	25.4	1	Кэширует в памяти списки манифестов и JSON-файлы метаданных
iceberg_metadata_staleness_ms	26.3	0	Настройка запроса. Использует кэшированные метаданные, если они не старше этого окна, вместо обращения к каталогу при каждом запросе
iceberg_use_version_hint	25.6	—	Читает version-hint.text для более быстрого определения метаданных при прямом доступе по пути

​

Снизить задержку каталога

Для таблиц Iceberg, подключённых к каталогу, при каждом запросе приходится получать метаданные, если она не кэшируется. Используйте две настройки вместе (26.4+):

1. Установите iceberg_metadata_async_prefetch_period_ms при создании таблицы, чтобы предварительно подгружать метаданные в фоновом режиме.
2. Установите iceberg_metadata_staleness_ms (26.3+) в запросах, чтобы допускать слегка устаревшие метаданные и тем самым избежать лишнего обращения к каталогу.

CREATE TABLE events
    ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')
SETTINGS iceberg_metadata_async_prefetch_period_ms = 60000;

SELECT count()
FROM events
SETTINGS iceberg_metadata_staleness_ms = 60000;

Значение 0 для staleness всегда получает самые актуальные метаданные. Увеличьте это окно для рабочих нагрузок с преобладанием чтения, в которых таблицы изменяются редко.

Если ClickHouse выбирает неправильный файл метаданных (когда в пути таблицы несколько файлов .metadata.json), явно укажите его через iceberg_metadata_file_path (25.4+) или iceberg_metadata_table_uuid при создании таблицы. См. Определение файла метаданных.

​

Доступ к прошлым версиям

Чтобы прочитать исторический снимок, используйте iceberg_timestamp_ms или iceberg_snapshot_id (оба параметра доступны в 25.4+). Не задавайте оба параметра в одном запросе. Перед выбором идентификатора просмотрите историю снимков в system.iceberg_history (25.6+). Для повторяющихся батч-загрузок см. ограничение батч-чтений диапазоном снимков.

SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000

​

Запись в Iceberg

Помимо allow_insert_into_iceberg (25.7+, бета с 26.2), можно управлять размером выходных файлов и количеством партиций при вставке:

Настройка	С версии	Назначение
iceberg_insert_max_rows_in_data_file	25.9	Ограничение числа строк в выходном файле данных
iceberg_insert_max_bytes_in_data_file	25.9	Ограничение размера выходного файла данных в байтах
iceberg_insert_max_partitions	25.12	Ограничение на число партиций, записываемых за одну вставку

См. Запись в озера данных и справочник по движку Iceberg.

​

Delta Lake

Начиная с версии 25.6 ClickHouse читает Delta Lake из S3 и GCS с помощью Rust-ядра Delta Lake. В версии 26.8 и более поздних версиях параметр называется allow_delta_kernel_rs, а в версиях с 25.5 по 26.7 — allow_experimental_delta_kernel_rs. Для Azure Blob Storage используйте deltaLakeAzure() со старым механизмом чтения, поскольку там это ядро отключено. Без ядра недоступны отсечение партиций, change data feed и чтение версий снимков.

​

Delta Kernel

Параметр Delta kernel должен быть включен для отсечения партиций, change data feed и чтения версии снимка. Начиная с версии 25.5, он включен по умолчанию для S3 и GCS. При его явном включении используйте имя, соответствующее вашей версии ClickHouse.

Для версии 26.8 и более поздних:

SET allow_delta_kernel_rs = 1;

Для версий с 25.5 по 26.7:

SET allow_experimental_delta_kernel_rs = 1;

​

Настройки чтения

Setting	Since	Default	Notes
delta_lake_enable_engine_predicate	25.8	1	Передает фильтры в kernel для отсечения партиций. Требует Delta Kernel
delta_lake_reload_schema_for_consistency	26.3	0	Перезагружает схему перед каждым запросом, если при параллельной записи схема изменяется
delta_lake_snapshot_start_version / delta_lake_snapshot_end_version	25.12	-1	Читает изменения CDF между двумя версиями снимка. Требует, чтобы CDF был включен в upstream
delta_lake_snapshot_version	25.8	-1	Читает один исторический снимок. Укажите -1 для последнего (0 также допустимо)

Таблицы с deletion vectors (26.2+) применяют фильтрацию на уровне строки при чтении. ClickHouse обрабатывает это автоматически, но scan по таблицам с большим количеством DV требует больше работы для каждого файла.

​

Change data feed в Delta

Чтобы читать только строки, изменившиеся между двумя снимками Delta, задайте delta_lake_snapshot_start_version и delta_lake_snapshot_end_version (25.12+). Для таблицы в исходной Delta-системе должен быть включен change data feed (delta.enableChangeDataFeed). Укажите и начальную, и конечную версии в параметрах запроса. Если указать только конечную версию, возникнет ошибка.

SELECT *
FROM deltaLake('s3://my-bucket/warehouse/ga4_events/')
SETTINGS
    delta_lake_snapshot_start_version = 42,
    delta_lake_snapshot_end_version = 47

Сохраняйте конечную версию после каждой успешной загрузки и передавайте её как начальную версию при следующем запуске. Результат содержит столбцы CDF (_change_type, _commit_version, _commit_timestamp). Обработайте их перед загрузкой в целевую таблицу. Общий шаблон работы со снимками см. в разделе Ограничение батч-чтений диапазоном снимков.

​

Запись в Delta Lake

Помимо allow_delta_lake_writes (25.9+), можно управлять размером выходного файла данных при вставке:

Настройка	С версии	Назначение
delta_lake_insert_max_rows_in_data_file	25.9	Ограничение на число строк в выходном файле данных
delta_lake_insert_max_bytes_in_data_file	25.9	Ограничение на размер выходного файла данных в байтах

SET allow_delta_lake_writes = 1;

INSERT INTO my_delta_table
SETTINGS
    delta_lake_insert_max_rows_in_data_file = 1000000,
    delta_lake_insert_max_bytes_in_data_file = 134217728
SELECT * FROM source_table

Для записи требуется Delta Kernel в S3 или GCS. Примеры см. в справочнике по движку DeltaLake.

​

Отладка запросов к озеру данных

Медленные запросы к озеру данных или запросы, возвращающие неожиданные результаты, обычно связаны с чтением метаданных, отсечением партиций или доступностью каталога. Начните с приведённых ниже проверок, а затем при необходимости используйте журналы метаданных для конкретного формата.

​

Проверьте доступность каталога

CREATE DATABASE с DataLakeCatalog не проверяет учетные данные. База данных может существовать, даже если соединение с каталогом не работает. Начиная с ClickHouse 26.4, выполните легковесную проверку работоспособности:

CHECK DATABASE my_lake;

В более ранних версиях проверьте подключение с помощью SHOW TABLES FROM my_lake и изучите сообщение об ошибке. Используйте SHOW CREATE TABLE с именем таблицы в обратных кавычках, чтобы проверить вычисленный путь к хранилищу и тип движка:

SHOW CREATE TABLE my_lake.`db.table`;

Если таблицы каталога не отображаются в system.tables, включите show_remote_databases_in_system_tables (25.8+). По умолчанию таблицы каталога скрыты при системной интроспекции. В версиях до 26.6 используйте его прежнее название: show_data_lake_catalogs_in_system_tables.

​

Посмотреть, какие файлы читаются

Iceberg и Delta Lake предоставляют виртуальные столбцы (_path, _file, _size, _time, _etag) при каждом чтении. Сгруппируйте по _path, чтобы проверить, работает ли отсечение партиций или запрос сканирует больше файлов, чем ожидалось. Для таблиц Iceberg со скрытым партиционированием фильтруйте по исходному столбцу (например, event_time), а не по отдельному столбцу партиции:

SELECT _path, count() AS rows
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
  AND event_time < '2026-03-02'
GROUP BY _path
ORDER BY rows DESC;

​

Проверьте объём сканирования

Сравните read_rows и read_bytes в system.query_log до и после добавления фильтров или изменения настроек. ProfileEvents, такие как ReadBufferFromS3Bytes и CachedReadBufferReadFromCacheBytes, показывают, какой объём данных поступил из Объектного хранилища, а какой — из локального кэша. Полное пошаговое руководство по query_log и EXPLAIN см. в разделе Диагностика медленных запросов.

Отключайте enable_filesystem_cache при проведении бенчмаркинга, чтобы попадания в кэш не скрывали различия между запусками.

​

Журналы метаданных

ClickHouse предоставляет три системные таблицы для отладки на уровне метаданных. Включайте логирование только на время выполнения запроса. Они не предназначены для постоянного мониторинга.

System table	Формат	С версии	Включается с помощью	Используется для
system.iceberg_metadata_log	Iceberg	25.9	iceberg_metadata_log_level в запросе	Отслеживания чтения файлов метаданных и решений по отсечению партиций
system.iceberg_history	Iceberg	25.6	Автоматически заполняется для таблиц Iceberg в ClickHouse	Анализа истории снимков перед запросами доступа к прошлым версиям
system.delta_lake_metadata_log	Delta Lake	25.10	delta_lake_log_metadata = 1 в запросе	Отслеживания файлов метаданных Delta и процесса выбора снимка

Выполните запрос с включенным логированием, сбросьте журнал, затем просмотрите записи для этого query_id:

SELECT count() FROM my_iceberg_table
SETTINGS iceberg_metadata_log_level = 'manifest_file_entry';

SYSTEM FLUSH LOGS iceberg_metadata_log;

SELECT content_type, file_path, pruning_status
FROM system.iceberg_metadata_log
WHERE query_id = '<previous_query_id>';

В ClickHouse Cloud данные логов локальны для каждого узла. Используйте clusterAllReplicas, чтобы увидеть полную картину по всем репликам.

Подробные уровни логирования Iceberg отключают кэширование метаданных для списков манифестов и файлов, что замедляет последующие запросы к той же таблице. Используйте высокий уровень детализации только во время активного расследования. При проблемах с предикатами Delta Lake включите delta_lake_throw_on_engine_predicate_error (25.8+), чтобы сразу завершать запрос с ошибкой, если ядро не может передать фильтр на уровень движка.

См. справочные страницы iceberg_metadata_log и delta_lake_metadata_log: там описаны столбцы и параметры детализации.

​

Следующие шаги

• Начало работы — Полное руководство: от прямого выполнения запросов до обратной записи данных
• Прямое выполнение запросов — Табличные функции, движки и кластерные варианты для всех четырёх форматов
• Подключение к каталогам — Настройка DataLakeCatalog с Unity Catalog
• Запись в озёра данных — Обратная запись данных в Iceberg и Delta Lake
• Матрица поддержки — Сравнение возможностей форматов, каталогов и бэкендов хранилищ