Выберите способ доступа
Табличные функции
icebergAzure, icebergLocal и эквиваленты для других форматов). Полный список см. в разделе Прямые запросы.
Для Paimon доступны только табличные функции.
Движки таблиц
DataLakeCatalog движок базы данных
Обратные кавычки для составных имён таблицВ каталогах часто используется формат именования
database.table. Заключайте полное имя с указанием базы данных в обратные кавычки, как в примере выше.Обязательные настройки
CREATE DATABASE завершается ошибкой прав доступа, проверьте версию вашего сервиса.
Для подключений к каталогам у каждого типа каталога есть свой флаг. Общую информацию см. в Подключение к каталогам, а сведения о настройках — в справочнике DataLakeCatalog. Инструкции по настройке для конкретных каталогов приведены в руководствах по каталогам.
Для записи в Iceberg требуется allow_insert_into_iceberg (25.7+, бета с 26.2). См. Запись в озера данных. Для Delta Lake требуется allow_delta_lake_writes (25.9+). В матрице поддержки указано, какие флаги применяются к каждому формату и операции.
Повысьте производительность запросов
Рекомендации по написанию запросов
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, чтобы распределить чтение файлов между репликами.
Параллельное чтение в многоузловых кластерах
'default' в ClickHouse Cloud). Кластерные варианты доступны для всех поддерживаемых форматов:
Кластерное чтение можно сочетать с другими настройками производительности.
Ограничение батч-чтений диапазоном снимков
- Для 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 = 0, чтобы попадания в кэш не скрывали изменения между запусками.
Apache Iceberg
Настройки чтения
Снизить задержку каталога
- Установите iceberg_metadata_async_prefetch_period_ms при создании таблицы, чтобы предварительно подгружать metadata в фоновом режиме.
- Установите iceberg_metadata_staleness_ms (26.3+) в запросах, чтобы допускать слегка устаревшую metadata и тем самым избежать лишнего обращения к каталогу.
0 для staleness всегда получает самые актуальные метаданные. Увеличьте это окно для рабочих нагрузок с преобладанием чтения, в которых таблицы изменяются редко.
Если ClickHouse выбирает неправильный файл метаданных (когда в пути таблицы несколько файлов .metadata.json), явно укажите его через iceberg_metadata_file_path (25.4+) или iceberg_metadata_table_uuid при создании таблицы. См. Определение файла метаданных.
Доступ к прошлым версиям
Запись в Iceberg
См. Запись в озера данных и справочник по движку Iceberg.
Delta Lake
Delta Kernel
Настройки чтения
Таблицы с deletion vectors (26.2+) применяют фильтрацию на уровне строки при чтении. ClickHouse обрабатывает это автоматически, но scan по таблицам с большим количеством DV требует больше работы для каждого файла.
Change data feed в Delta
delta.enableChangeDataFeed). Укажите и начальную, и конечную версии в параметрах запроса. Если указать только конечную версию, возникнет ошибка.
_change_type, _commit_version, _commit_timestamp). Обработайте их перед загрузкой в целевую таблицу. Общий шаблон работы со снимками см. в разделе Ограничение батч-чтений диапазоном снимков.
Запись в Delta Lake
Отладка запросов к озеру данных
Проверьте доступность каталога
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.
Посмотреть, какие файлы читаются
_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 при проведении бенчмаркинга, чтобы попадания в кэш не скрывали различия между запусками.
Журналы метаданных
Выполните запрос с включенным логированием, сбросьте журнал, затем просмотрите записи для этого
query_id:
clusterAllReplicas, чтобы увидеть полную картину по всем репликам.
Подробные уровни логирования Iceberg отключают кэширование метаданных для manifest lists и файлов, что замедляет последующие запросы к той же таблице. Используйте высокий уровень детализации только во время активного расследования. При проблемах с предикатами Delta Lake включите delta_lake_throw_on_engine_predicate_error (25.8+), чтобы сразу завершать запрос с ошибкой, если ядро не может передать фильтр на уровень движка.
См. справочные страницы iceberg_metadata_log и delta_lake_metadata_log: там описаны столбцы и параметры детализации.
Дальнейшие шаги
- Начало работы — Сквозное руководство: от прямых запросов до обратной записи данных
- Прямые запросы — Табличные функции, движки и кластерные варианты для всех четырёх форматов
- Подключение к каталогам — Настройка
DataLakeCatalogс Unity Catalog - Запись в озера данных — Обратная запись данных в Iceberg и Delta Lake
- Матрица поддержки — Сравнение возможностей для разных форматов, каталогов и бэкендов хранилища