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

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

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

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 никогда не дублируются. Движок таблицы удобен, если вы предоставляете доступ команде или выполняете задачи по расписанию для одной и той же таблицы.

Подключите 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`

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

Для многих интеграций перед первым использованием требуется флаг функции. Если 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). Кластерные варианты доступны для всех поддерживаемых форматов:

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

Для повторяющихся батч-загрузок из таблиц в 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.

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

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

Для таблиц 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

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

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

Начиная с версии 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 должен быть включен для отсечения партиций, 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;

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

Чтобы читать только строки, изменившиеся между двумя снимками 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). Обработайте их перед загрузкой в целевую таблицу. Общий шаблон работы со снимками см. в разделе Ограничение батч-чтений диапазоном снимков.

Помимо allow_delta_lake_writes (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 предоставляет три системные таблицы для отладки на уровне метаданных. Включайте логирование только на время выполнения запроса. Они не предназначены для постоянного мониторинга.

Выполните запрос с включенным логированием, сбросьте журнал, затем просмотрите записи для этого 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
• Матрица поддержки — Сравнение возможностей форматов, каталогов и бэкендов хранилищ