'
SELECT count() FROM my_lake.`analytics.events`
```
Этот вариант масштабируется лучше, чем создание отдельных определений таблиц, если вы управляете большим числом таблиц или несколькими каталогами. См. [Подключение к каталогам](/docs/ru/use-cases/data-lake/getting-started/connecting-catalogs) и [руководства по каталогам](/docs/ru/use-cases/data-lake/reference).
**Обратные кавычки для составных имён таблиц**
В каталогах часто используется формат именования `database.table`. Заключайте полное имя с указанием базы данных в обратные кавычки, как в примере выше.
## Обязательные настройки
Для многих интеграций перед первым использованием требуется флаг функции. Если `CREATE DATABASE` завершается ошибкой прав доступа, проверьте версию вашего сервиса.
Для подключений к каталогам у каждого типа каталога есть свой флаг. Общую информацию см. в [Подключение к каталогам](/docs/ru/use-cases/data-lake/getting-started/connecting-catalogs), а сведения о настройках — в [справочнике DataLakeCatalog](/docs/ru/engines/database-engines/datalakecatalog). Инструкции по настройке для конкретных каталогов приведены в [руководствах по каталогам](/docs/ru/use-cases/data-lake/reference).
Для записи в Iceberg требуется [allow\_insert\_into\_iceberg](/docs/ru/operations/settings/settings#allow_insert_into_iceberg) (25.7+, бета с 26.2). См. [Запись в озера данных](/docs/ru/use-cases/data-lake/getting-started/writing-data). Для Delta Lake требуется [allow\_delta\_lake\_writes](/docs/ru/operations/settings/settings#allow_experimental_delta_lake_writes) (25.9+). В [матрице поддержки](/docs/ru/use-cases/data-lake/support-matrix) указано, какие флаги применяются к каждому формату и операции.
## Повысьте производительность запросов
Номера версий на этой странице соответствуют версиям релизов ClickHouse (Cloud и самоуправляемых установок). Перед включением какой-либо настройки или возможности проверьте версию своего сервиса.
Производительность запросов к Lake зависит от объёма метаданных и количества файлов [Parquet](/docs/ru/interfaces/formats/Parquet), которые ClickHouse читает из Объектного хранилища. Как и в случае с любой таблицей ClickHouse, производительность запросов повышается при фильтрации по столбцам партиции и выборе меньшего числа столбцов.
### Рекомендации по написанию запросов
Фильтруйте по столбцам партиций в `WHERE`. Iceberg и Delta Lake хранят метаданные партиций, которые позволяют ClickHouse пропускать ненужные файлы на этапе планирования запроса. Если условие фильтрации относится к столбцу вне спецификации партиционирования, ClickHouse будет сканировать каждый подходящий файл.
Для таблиц Iceberg со [скрытым партиционированием](https://iceberg.apache.org/docs/latest/partitioning/) фильтруйте по **исходному столбцу** в схеме таблицы, а не по отдельному столбцу партиции или имени преобразованного поля. Если таблица партиционирована по `day(event_time)`, добавьте условие для `event_time`. ClickHouse выполнит отсечение партиций на основе этого фильтра, используя спецификацию партиционирования Iceberg. См. [Отсечение партиций](/docs/ru/engines/table-engines/integrations/iceberg#partition-pruning) и [спецификацию Iceberg](https://iceberg.apache.org/spec/#partitioning).
```sql theme={null}
SELECT count()
FROM my_lake.`logs.application`
WHERE event_time >= '2026-03-01'
AND event_time < '2026-03-02'
```
Указывайте только нужные столбцы вместо `SELECT *`. ClickHouse читает [Parquet](/docs/ru/interfaces/formats/Parquet) из Объектного хранилища постолбцово, поэтому чем меньше столбцов выбирается, тем меньше данных передаётся и распаковывается.
Помещайте избирательные фильтры в `WHERE`. Начиная с ClickHouse 26.2+, [PREWHERE](/docs/ru/optimize/prewhere) также поддерживается при чтении таблиц Iceberg и других lake-таблиц: в этом случае фильтрация выполняется на уровне Parquet до чтения остальных столбцов. Однако отсечение партиций по-прежнему зависит от фильтрации исходных столбцов партиции, а не только от PREWHERE.
Для таблиц Iceberg с большим количеством [position or equality deletes](/docs/ru/engines/table-engines/integrations/iceberg#deleted-rows) при сканировании применяется фильтрация merge-on-read. Ожидайте, что на каждый файл потребуется больше работы, чем можно предположить только по отсечению на уровне манифеста.
В многоузловых развертываниях используйте [cluster table functions](#parallel-cluster-reads), чтобы распределить чтение файлов между репликами.
### Параллельное чтение в многоузловых кластерах
В ClickHouse Cloud и самоуправляемых многоузловых сервисах кластерные варианты lake-табличных функций распределяют чтение файлов [Parquet](/docs/ru/interfaces/formats/Parquet) между репликами. Узел-инициатор параллельно распределяет файлы между воркерами. Используйте кластерные варианты для батч-чтения и загрузок по расписанию при работе с большими таблицами. В одноузловых развертываниях достаточно стандартной табличной функции.
Передайте имя вашего кластера первым аргументом (`'default'` в ClickHouse Cloud). Кластерные варианты доступны для всех поддерживаемых форматов:
| Формат | Кластерные функции |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Iceberg | [icebergS3Cluster()](/docs/ru/sql-reference/table-functions/icebergCluster), [icebergAzureCluster()](/docs/ru/sql-reference/table-functions/icebergCluster) |
| Delta Lake | [deltaLakeCluster()](/docs/ru/sql-reference/table-functions/deltalakeCluster), [deltaLakeAzureCluster()](/docs/ru/sql-reference/table-functions/deltalakeCluster) |
| Hudi | [hudiCluster()](/docs/ru/sql-reference/table-functions/hudiCluster) |
| Paimon | [paimonS3Cluster()](/docs/ru/sql-reference/table-functions/paimonCluster) |
Кластерное чтение можно сочетать с другими настройками производительности.
### Ограничение батч-чтений диапазоном снимков
Для повторяющихся батч-загрузок из таблиц в data lake ограничивайте каждый запуск диапазоном снимков, а не перечитывайте всю таблицу целиком. Без таких границ ClickHouse может при каждом запуске сканировать все версии и файлы, что увеличивает число чтений из Объектного хранилища и время выполнения запроса.
Сохраняйте идентификатор снимка из последней успешной загрузки и используйте его как нижнюю границу при следующем запуске.
* Для Iceberg читайте состояние на определённый момент времени с помощью [iceberg\_snapshot\_id](/docs/ru/operations/settings/settings#iceberg_snapshot_id) или [iceberg\_timestamp\_ms](/docs/ru/operations/settings/settings#iceberg_timestamp_ms) (25.4+). Для таблиц, в которые данные только добавляются, сочетайте настройки снимков с фильтрами по партициям в `WHERE`. Используйте [system.iceberg\_history](/docs/ru/operations/system-tables/iceberg_history) (25.6+), чтобы находить ID снимков между запусками.
* Для Delta Lake читайте изменения между двумя версиями с помощью [delta\_lake\_snapshot\_start\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_start_version) и [delta\_lake\_snapshot\_end\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_end_version) (25.12+). Чтобы прочитать один снимок, используйте [delta\_lake\_snapshot\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_version) (25.8+). Пример CDF см. в разделе [change data feed в Delta](#delta-incremental-sync).
### Локальное кэширование файлов Parquet
Оба формата поддерживают [enable\_filesystem\_cache](/docs/ru/operations/settings/settings#enable_filesystem_cache), чтобы сохранять часто используемые файлы [Parquet](/docs/ru/interfaces/formats/Parquet) на локальном диске между запросами. В самоуправляемых развертываниях настройте [диск файлового кэша](/docs/ru/operations/storing-data#using-local-cache) в конфигурации сервера, чтобы этому параметру было куда записывать данные. В ClickHouse Cloud кэширование настраивается автоматически. При бенчмаркинге установите `enable_filesystem_cache = 0`, чтобы попадания в кэш не скрывали изменения между запусками.
### Apache Iceberg
Большинство оптимизаций чтения в Iceberg включено по умолчанию. Приведённые ниже настройки управляют отсечением партиций, кэшированием метаданных и числом обращений к каталогу.
#### Настройки чтения
| Настройка | С версии | По умолчанию | Примечания |
| --------------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| [use\_iceberg\_partition\_pruning](/docs/ru/operations/settings/settings#use_iceberg_partition_pruning) | 25.1 | `1` с 25.6 | Пропускает файлы данных на основе метаданных партиций в манифестах |
| [use\_iceberg\_metadata\_files\_cache](/docs/ru/operations/settings/settings#use_iceberg_metadata_files_cache) | 25.4 | `1` | Кэширует в памяти списки манифестов и JSON-файлы метаданных |
| [iceberg\_metadata\_staleness\_ms](/docs/ru/operations/settings/settings#iceberg_metadata_staleness_ms) | 26.3 | `0` | Настройка запроса. Использует кэшированные метаданные, если они не старше этого окна, вместо обращения к каталогу при каждом запросе |
| [iceberg\_use\_version\_hint](/docs/ru/sql-reference/table-functions/iceberg#writes-into-iceberg-table) | 25.6 | — | Читает `version-hint.text` для более быстрого определения метаданных при прямом доступе по пути |
#### Снизить задержку каталога
Для таблиц Iceberg, подключённых к каталогу, при каждом запросе приходится получать metadata, если она не кэшируется. Используйте две настройки вместе (26.4+):
1. Установите [iceberg\_metadata\_async\_prefetch\_period\_ms](/docs/ru/engines/table-engines/integrations/iceberg#async-metadata-prefetch) при создании таблицы, чтобы предварительно подгружать metadata в фоновом режиме.
2. Установите [iceberg\_metadata\_staleness\_ms](/docs/ru/operations/settings/settings#iceberg_metadata_staleness_ms) (26.3+) в запросах, чтобы допускать слегка устаревшую metadata и тем самым избежать лишнего обращения к каталогу.
```sql theme={null}
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](/docs/ru/engines/table-engines/integrations/iceberg#metadata-file-resolution) (25.4+) или [iceberg\_metadata\_table\_uuid](/docs/ru/engines/table-engines/integrations/iceberg#metadata-file-resolution) при создании таблицы. См. [Определение файла метаданных](/docs/ru/engines/table-engines/integrations/iceberg#metadata-file-resolution).
#### Доступ к прошлым версиям
Чтобы прочитать исторический снимок, используйте [iceberg\_timestamp\_ms](/docs/ru/operations/settings/settings#iceberg_timestamp_ms) или [iceberg\_snapshot\_id](/docs/ru/operations/settings/settings#iceberg_snapshot_id) (оба параметра доступны в 25.4+). Не задавайте оба параметра в одном запросе. Перед выбором идентификатора просмотрите историю снимков в [system.iceberg\_history](/docs/ru/operations/system-tables/iceberg_history) (25.6+). Для повторяющихся батч-загрузок см. [ограничение батч-чтений диапазоном снимков](#snapshot-bounds).
```sql theme={null}
SELECT count()
FROM my_iceberg_table
SETTINGS iceberg_timestamp_ms = 1714636800000
```
#### Запись в Iceberg
Помимо [allow\_insert\_into\_iceberg](/docs/ru/operations/settings/settings#allow_insert_into_iceberg) (25.7+, бета с 26.2), можно управлять размером выходных файлов и количеством партиций при вставке:
| Настройка | С версии | Назначение |
| --------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------------- |
| [iceberg\_insert\_max\_rows\_in\_data\_file](/docs/ru/operations/settings/settings#iceberg_insert_max_rows_in_data_file) | 25.9 | Ограничение числа строк в выходном файле данных |
| [iceberg\_insert\_max\_bytes\_in\_data\_file](/docs/ru/operations/settings/settings#iceberg_insert_max_bytes_in_data_file) | 25.9 | Ограничение размера выходного файла данных в байтах |
| [iceberg\_insert\_max\_partitions](/docs/ru/operations/settings/settings#iceberg_insert_max_partitions) | 25.12 | Ограничение на число партиций, записываемых за одну вставку |
См. [Запись в озера данных](/docs/ru/use-cases/data-lake/getting-started/writing-data) и [справочник по движку Iceberg](/docs/ru/engines/table-engines/integrations/iceberg).
### Delta Lake
Начиная с версии 25.6 ClickHouse читает Delta Lake из S3 и GCS с помощью Rust-ядра Delta Lake ([allow\_experimental\_delta\_kernel\_rs](/docs/ru/operations/settings/settings#allow_experimental_delta_kernel_rs), 25.5+). Для Azure Blob Storage используйте [deltaLakeAzure()](/docs/ru/sql-reference/table-functions/deltalake) со старым механизмом чтения, поскольку там это ядро отключено. Без ядра недоступны отсечение партиций, change data feed и чтение версий снимков.
#### Delta Kernel
[allow\_experimental\_delta\_kernel\_rs](/docs/ru/operations/settings/settings#allow_experimental_delta_kernel_rs) должен быть включен для pruning партиций, change data feed и чтения версии снимка. Начиная с версии 25.5, он включен по умолчанию для S3 и GCS. Явно включите его в более старых версиях или при устранении неполадок:
```sql theme={null}
SET allow_experimental_delta_kernel_rs = 1;
```
#### Настройки чтения
| Setting | Since | Default | Notes |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------- | ------------------------------------------------------------------------------------------- |
| [delta\_lake\_enable\_engine\_predicate](/docs/ru/operations/settings/settings#delta_lake_enable_engine_predicate) | 25.8 | `1` | Передает фильтры в kernel для отсечения партиций. Требует [Delta Kernel](#delta-kernel) |
| [delta\_lake\_reload\_schema\_for\_consistency](/docs/ru/operations/settings/settings#delta_lake_reload_schema_for_consistency) | 26.3 | `0` | Перезагружает схему перед каждым запросом, если при параллельной записи схема изменяется |
| [delta\_lake\_snapshot\_start\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_start_version) / [delta\_lake\_snapshot\_end\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_end_version) | 25.12 | `-1` | Читает изменения CDF между двумя версиями снимка. Требует, чтобы CDF был включен в upstream |
| [delta\_lake\_snapshot\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_version) | 25.8 | `-1` | Читает один исторический снимок. Укажите `-1` для последнего (`0` также допустимо) |
Таблицы с [deletion vectors](https://docs.delta.io/latest/delta-deletion-vectors.html) (26.2+) применяют фильтрацию на уровне строки при чтении. ClickHouse обрабатывает это автоматически, но scan по таблицам с большим количеством DV требует больше работы для каждого файла.
#### Change data feed в Delta
Чтобы читать только строки, изменившиеся между двумя снимками Delta, задайте [delta\_lake\_snapshot\_start\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_start_version) и [delta\_lake\_snapshot\_end\_version](/docs/ru/operations/settings/settings#delta_lake_snapshot_end_version) (25.12+). Для таблицы в исходной Delta-системе должен быть включен change data feed (`delta.enableChangeDataFeed`). Укажите и начальную, и конечную версии в параметрах запроса. Если указать только конечную версию, возникнет ошибка.
```sql theme={null}
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`). Обработайте их перед загрузкой в целевую таблицу. Общий шаблон работы со снимками см. в разделе [Ограничение батч-чтений диапазоном снимков](#snapshot-bounds).
#### Запись в Delta Lake
Помимо [allow\_delta\_lake\_writes](/docs/ru/operations/settings/settings#allow_experimental_delta_lake_writes) (25.9+), можно управлять размером выходного файла данных при вставке:
| Настройка | С версии | Назначение |
| ---------------------------------------------------------------------------------------------------------------------------- | -------- | ----------------------------------------------------- |
| [delta\_lake\_insert\_max\_rows\_in\_data\_file](/docs/ru/operations/settings/settings#delta_lake_insert_max_rows_in_data_file) | 25.9 | Ограничение на число строк в выходном файле данных |
| [delta\_lake\_insert\_max\_bytes\_in\_data\_file](/docs/ru/operations/settings/settings#delta_lake_insert_max_bytes_in_data_file) | 25.9 | Ограничение на размер выходного файла данных в байтах |
```sql theme={null}
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](/docs/ru/engines/table-engines/integrations/deltalake).
## Отладка запросов к озеру данных
Медленные запросы к озеру данных или запросы, возвращающие неожиданные результаты, обычно связаны с чтением метаданных, отсечением партиций или доступностью каталога. Начните с приведённых ниже проверок, а затем при необходимости используйте журналы метаданных для конкретного формата.
### Проверьте доступность каталога
`CREATE DATABASE` с `DataLakeCatalog` не проверяет учетные данные. База данных может существовать, даже если соединение с каталогом не работает. Начиная с ClickHouse 26.4, выполните легковесную проверку работоспособности:
```sql theme={null}
CHECK DATABASE my_lake;
```
В более ранних версиях проверьте подключение с помощью `SHOW TABLES FROM my_lake` и изучите сообщение об ошибке. Используйте `SHOW CREATE TABLE` с именем таблицы в обратных кавычках, чтобы проверить вычисленный путь к хранилищу и тип движка:
```sql theme={null}
SHOW CREATE TABLE my_lake.`db.table`;
```
Если таблицы каталога не отображаются в `system.tables`, включите [show\_remote\_databases\_in\_system\_tables](/docs/ru/operations/settings/settings#show_remote_databases_in_system_tables) (25.8+). По умолчанию таблицы каталога скрыты при системной интроспекции. В версиях до 26.6 используйте его прежнее название: `show_data_lake_catalogs_in_system_tables`.
### Посмотреть, какие файлы читаются
Iceberg и Delta Lake предоставляют [виртуальные столбцы](/docs/ru/sql-reference/table-functions/iceberg#virtual-columns) (`_path`, `_file`, `_size`, `_time`, `_etag`) при каждом чтении. Сгруппируйте по `_path`, чтобы проверить, работает ли отсечение партиций или запрос сканирует больше файлов, чем ожидалось. Для таблиц Iceberg со скрытым партиционированием фильтруйте по исходному столбцу (например, `event_time`), а не по отдельному столбцу партиции:
```sql theme={null}
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](/docs/ru/operations/system-tables/query_log) до и после добавления фильтров или изменения настроек. ProfileEvents, такие как `ReadBufferFromS3Bytes` и `CachedReadBufferReadFromCacheBytes`, показывают, какой объём данных поступил из Объектного хранилища, а какой — из локального кэша. Полное пошаговое руководство по `query_log` и EXPLAIN см. в разделе [Оптимизация запросов](/docs/ru/optimize/query-optimization).
Отключайте [enable\_filesystem\_cache](/docs/ru/operations/settings/settings#enable_filesystem_cache) при проведении бенчмаркинга, чтобы попадания в кэш не скрывали различия между запусками.
### Журналы метаданных
ClickHouse предоставляет три системные таблицы для отладки на уровне метаданных. Включайте логирование только на время выполнения запроса. Они не предназначены для постоянного мониторинга.
| System table | Формат | С версии | Включается с помощью | Используется для |
| ----------------------------------------------------------------------------------------- | ---------- | -------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| [system.iceberg\_metadata\_log](/docs/ru/operations/system-tables/iceberg_metadata_log) | Iceberg | 25.9 | [iceberg\_metadata\_log\_level](/docs/ru/operations/settings/settings#iceberg_metadata_log_level) в запросе | Отслеживания чтения файлов метаданных и решений по отсечению партиций |
| [system.iceberg\_history](/docs/ru/operations/system-tables/iceberg_history) | Iceberg | 25.6 | Автоматически заполняется для таблиц Iceberg в ClickHouse | Анализа истории снимков перед запросами доступа к прошлым версиям |
| [system.delta\_lake\_metadata\_log](/docs/ru/operations/system-tables/delta_lake_metadata_log) | Delta Lake | 25.10 | [delta\_lake\_log\_metadata](/docs/ru/operations/settings/settings#delta_lake_log_metadata) = `1` в запросе | Отслеживания файлов метаданных Delta и процесса выбора снимка |
Выполните запрос с включенным логированием, сбросьте журнал, затем просмотрите записи для этого `query_id`:
```sql theme={null}
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 = '';
```
В ClickHouse Cloud данные логов локальны для каждого узла. Используйте `clusterAllReplicas`, чтобы увидеть полную картину по всем репликам.
Подробные уровни логирования Iceberg отключают кэширование метаданных для manifest lists и файлов, что замедляет последующие запросы к той же таблице. Используйте высокий уровень детализации только во время активного расследования. При проблемах с предикатами Delta Lake включите [delta\_lake\_throw\_on\_engine\_predicate\_error](/docs/ru/operations/settings/settings#delta_lake_throw_on_engine_predicate_error) (25.8+), чтобы сразу завершать запрос с ошибкой, если ядро не может передать фильтр на уровень движка.
См. справочные страницы [iceberg\_metadata\_log](/docs/ru/operations/system-tables/iceberg_metadata_log) и [delta\_lake\_metadata\_log](/docs/ru/operations/system-tables/delta_lake_metadata_log): там описаны столбцы и параметры детализации.
## Дальнейшие шаги
* [Начало работы](/docs/ru/use-cases/data-lake/getting-started) — Сквозное руководство: от прямых запросов до обратной записи данных
* [Прямые запросы](/docs/ru/use-cases/data-lake/getting-started/querying-directly) — Табличные функции, движки и кластерные варианты для всех четырёх форматов
* [Подключение к каталогам](/docs/ru/use-cases/data-lake/getting-started/connecting-catalogs) — Настройка `DataLakeCatalog` с Unity Catalog
* [Запись в озера данных](/docs/ru/use-cases/data-lake/getting-started/writing-data) — Обратная запись данных в Iceberg и Delta Lake
* [Матрица поддержки](/docs/ru/use-cases/data-lake/support-matrix) — Сравнение возможностей для разных форматов, каталогов и бэкендов хранилища