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

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

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

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

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

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

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

Подключите ClickHouse один раз к внешнему каталогу данных, в котором зарегистрированы таблицы. Каждая таблица из каталога автоматически становится таблицей ClickHouse, включая таблицы, добавленные после создания подключения.
Этот вариант масштабируется лучше, чем создание отдельных определений таблиц, если вы управляете большим числом таблиц или несколькими каталогами. См. Подключение к каталогам и руководства по каталогам.
Обратные кавычки для составных имён таблицВ каталогах часто используется формат именования 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 *. ClickHouse читает Parquet из Объектного хранилища постолбцово, поэтому чем меньше столбцов выбирается, тем меньше данных передаётся и распаковывается. Помещайте избирательные фильтры в WHERE. Начиная с ClickHouse 26.2+, PREWHERE также поддерживается при чтении таблиц Iceberg и других lake-таблиц: в этом случае фильтрация выполняется на уровне Parquet до чтения остальных столбцов. Однако отсечение партиций по-прежнему зависит от фильтрации исходных столбцов партиции, а не только от PREWHERE. Для таблиц Iceberg с большим количеством position or equality deletes при сканировании применяется фильтрация merge-on-read. Ожидайте, что на каждый файл потребуется больше работы, чем можно предположить только по отсечению на уровне манифеста. В многоузловых развертываниях используйте cluster table functions, чтобы распределить чтение файлов между репликами.

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

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

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

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

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

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

Apache Iceberg

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

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

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

Для таблиц Iceberg, подключённых к каталогу, при каждом запросе приходится получать metadata, если она не кэшируется. Используйте две настройки вместе (26.4+):
  1. Установите iceberg_metadata_async_prefetch_period_ms при создании таблицы, чтобы предварительно подгружать metadata в фоновом режиме.
  2. Установите iceberg_metadata_staleness_ms (26.3+) в запросах, чтобы допускать слегка устаревшую metadata и тем самым избежать лишнего обращения к каталогу.
Значение 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+). Для повторяющихся батч-загрузок см. ограничение батч-чтений диапазоном снимков.

Запись в Iceberg

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

Delta Lake

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

Delta Kernel

allow_experimental_delta_kernel_rs должен быть включен для pruning партиций, change data feed и чтения версии снимка. Начиная с версии 25.5, он включен по умолчанию для S3 и GCS. Явно включите его в более старых версиях или при устранении неполадок:

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

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

Запись в Delta Lake

Помимо allow_delta_lake_writes (25.9+), можно управлять размером выходного файла данных при вставке:
Для записи требуется Delta Kernel в S3 или GCS. Примеры см. в справочнике по движку DeltaLake.

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

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

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

CREATE DATABASE с DataLakeCatalog не проверяет учетные данные. База данных может существовать, даже если соединение с каталогом не работает. Начиная с ClickHouse 26.4, выполните легковесную проверку работоспособности:
В более ранних версиях проверьте подключение с помощью SHOW TABLES FROM my_lake и изучите сообщение об ошибке. Используйте SHOW CREATE 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), а не по отдельному столбцу партиции:

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

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

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

ClickHouse предоставляет три системные таблицы для отладки на уровне метаданных. Включайте логирование только на время выполнения запроса. Они не предназначены для постоянного мониторинга. Выполните запрос с включенным логированием, сбросьте журнал, затем просмотрите записи для этого query_id:
В ClickHouse Cloud данные логов локальны для каждого узла. Используйте clusterAllReplicas, чтобы увидеть полную картину по всем репликам. Подробные уровни логирования Iceberg отключают кэширование метаданных для manifest lists и файлов, что замедляет последующие запросы к той же таблице. Используйте высокий уровень детализации только во время активного расследования. При проблемах с предикатами Delta Lake включите delta_lake_throw_on_engine_predicate_error (25.8+), чтобы сразу завершать запрос с ошибкой, если ядро не может передать фильтр на уровень движка. См. справочные страницы iceberg_metadata_log и delta_lake_metadata_log: там описаны столбцы и параметры детализации.

Дальнейшие шаги

Последнее изменение 23 июля 2026 г.