> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Лучшие практики для озер данных
> Рекомендации для продакшна по работе с открытыми табличными форматами в ClickHouse: варианты интеграции, настройка производительности, настройка каталога и отладка.
[Руководство «Начало работы»](/ru/guides/use-cases/data-warehousing/getting-started/overview) поможет вам выполнить первые запросы к [Apache Iceberg](/ru/reference/engines/table-engines/integrations/iceberg), [Delta Lake](/ru/reference/engines/table-engines/integrations/deltalake), [Apache Hudi](/ru/reference/engines/table-engines/integrations/hudi) и [Apache Paimon](/ru/reference/functions/table-functions/paimon). После завершения начальной настройки используйте эту страницу, чтобы выбрать подходящий паттерн доступа, настроить производительность запросов и отлаживать запросы к озеру данных в продакшне.
Выберите способ доступа
| Способ доступа | Когда использовать | Примеры |
| - | - | - |
| Табличная функция | Разовые запросы к известному пути | [icebergS3()](/ru/reference/functions/table-functions/iceberg), [deltaLake()](/ru/reference/functions/table-functions/deltalake), [hudi()](/ru/reference/functions/table-functions/hudi), [paimon()](/ru/reference/functions/table-functions/paimon) |
| Движок таблицы | Регулярные запросы к одному и тому же пути без каталога | [IcebergS3](/ru/reference/engines/table-engines/integrations/iceberg), [DeltaLake](/ru/reference/engines/table-engines/integrations/deltalake), [Hudi](/ru/reference/engines/table-engines/integrations/hudi) |
| `DataLakeCatalog` движок базы данных | Рабочие нагрузки в продакшне с каталогом; федеративные запросы ко множеству таблиц | [AWS Glue](/ru/guides/use-cases/data-warehousing/glue-catalog), [Unity Catalog](/ru/guides/use-cases/data-warehousing/unity-catalog), [REST-каталог](/ru/guides/use-cases/data-warehousing/rest-catalog) |
Табличные функции
Укажите путь к хранилищу и учетные данные прямо в запросе, если вам известно расположение и не нужно сохранять определение таблицы.
```sql theme={null}
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` и эквиваленты для других форматов). Полный список см. в разделе [Прямое выполнение запросов](/ru/guides/use-cases/data-warehousing/getting-started/querying-directly).
[Paimon](/ru/reference/functions/table-functions/paimon) предоставляет табличные функции и [экспериментальные движки таблиц](/ru/reference/engines/table-engines/integrations/paimon).
Движки таблиц
Создайте таблицу с движком таблицы, если планируете многократно выполнять запросы к одному и тому же path. ClickHouse хранит path и учетные данные в метаданных таблицы, поэтому можно выполнять запросы к обычной таблице по ее имени, не воссоздавая каждый раз вызов функции.
```sql theme={null}
CREATE TABLE events
ENGINE = IcebergS3('https://my-bucket.s3.amazonaws.com/warehouse/events/')
SELECT count() FROM events WHERE event_date = today()
```
Движки таблиц поддерживают те же возможности чтения, что и табличные функции, включая [кэширование данных](/ru/reference/engines/table-engines/integrations/iceberg#data-cache) и [кэширование метаданных](/ru/reference/engines/table-engines/integrations/iceberg#metadata-cache). Данные в ClickHouse никогда не дублируются. Движок таблицы удобен, если вы предоставляете доступ команде или выполняете задачи по расписанию для одной и той же таблицы.
`DataLakeCatalog` движок базы данных
Подключите ClickHouse один раз к внешнему [каталогу данных](/ru/guides/use-cases/data-warehousing/getting-started/connecting-catalogs), в котором зарегистрированы таблицы. Каждая таблица из каталога автоматически становится таблицей ClickHouse, включая таблицы, добавленные после создания подключения.
```sql theme={null}
CREATE DATABASE my_lake
ENGINE = DataLakeCatalog
SETTINGS
catalog_type = 'glue',
region = 'us-east-1',
aws_access_key_id = '',
aws_secret_access_key = ''
SELECT count() FROM my_lake.`analytics.events`
```
Этот вариант масштабируется лучше, чем создание отдельных определений таблиц, если вы управляете большим числом таблиц или несколькими каталогами. См. [Подключение к каталогам](/ru/guides/use-cases/data-warehousing/getting-started/connecting-catalogs) и [руководства по каталогам](/ru/guides/use-cases/data-warehousing/reference).
**Обратные кавычки для составных имён таблиц**
В каталогах часто используется формат именования `database.table`. Заключайте полное имя с указанием базы данных в обратные кавычки, как в примере выше.
Обязательные настройки
Для многих интеграций перед первым использованием требуется флаг функции. Если `CREATE DATABASE` завершается ошибкой прав доступа, проверьте версию вашего сервиса.
Для подключений к каталогам у каждого типа каталога есть свой флаг. Общую информацию см. в [Подключение к каталогам](/ru/guides/use-cases/data-warehousing/getting-started/connecting-catalogs), а сведения о настройках — в [справочнике DataLakeCatalog](/ru/reference/engines/database-engines/datalake). Инструкции по настройке для конкретных каталогов приведены в [руководствах по каталогам](/ru/guides/use-cases/data-warehousing/reference).
Для записи в Iceberg требуется [allow\_insert\_into\_iceberg](/ru/reference/settings/session-settings/allow#allow_insert_into_iceberg) (25.7+, бета с 26.2). См. [Запись в озера данных](/ru/guides/use-cases/data-warehousing/getting-started/writing-data). Для Delta Lake требуется [allow\_delta\_lake\_writes](/ru/reference/settings/session-settings/allow#allow_delta_lake_writes) (25.9+). В [матрице поддержки](/ru/guides/use-cases/data-warehousing/support-matrix) указано, какие флаги применяются к каждому формату и операции.
Номера версий на этой странице соответствуют версиям релизов ClickHouse (Cloud и самоуправляемых установок). Перед включением какой-либо настройки или возможности проверьте версию своего сервиса.
Производительность запросов к Lake зависит от объёма метаданных и количества файлов [Parquet](/ru/reference/formats/Parquet/Parquet), которые ClickHouse читает из Объектного хранилища. Как и в случае с любой таблицей ClickHouse, производительность запросов повышается при фильтрации по столбцам партиции и выборе меньшего числа столбцов.
Рекомендации по написанию запросов
Фильтруйте по столбцам партиций в `WHERE`. Iceberg и Delta Lake хранят метаданные партиций, которые позволяют ClickHouse пропускать ненужные файлы на этапе планирования запроса. Если условие фильтрации относится к столбцу вне спецификации партиционирования, ClickHouse будет сканировать каждый подходящий файл.
Для таблиц Iceberg со [скрытым партиционированием](https://iceberg.apache.org/docs/latest/partitioning/) фильтруйте по **исходному столбцу** в схеме таблицы, а не по отдельному столбцу партиции или имени преобразованного поля. Если таблица партиционирована по `day(event_time)`, добавьте условие для `event_time`. ClickHouse выполнит отсечение партиций на основе этого фильтра, используя спецификацию партиционирования Iceberg. См. [Отсечение партиций](/ru/reference/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](/ru/reference/formats/Parquet/Parquet) из Объектного хранилища постолбцово, поэтому чем меньше столбцов выбирается, тем меньше данных передаётся и распаковывается.
Помещайте избирательные фильтры в `WHERE`. Начиная с ClickHouse 26.2+, [PREWHERE](/ru/concepts/features/performance/prewhere) также поддерживается при чтении таблиц Iceberg и других lake-таблиц: в этом случае фильтрация выполняется на уровне Parquet до чтения остальных столбцов. Однако отсечение партиций по-прежнему зависит от фильтрации исходных столбцов партиции, а не только от PREWHERE.
Для таблиц Iceberg с большим количеством [position or equality deletes](/ru/reference/engines/table-engines/integrations/iceberg#deleted-rows) при сканировании применяется фильтрация merge-on-read. Ожидайте, что на каждый файл потребуется больше работы, чем можно предположить только по отсечению на уровне манифеста.
В многоузловых развертываниях используйте [кластерные табличные функции](#parallel-cluster-reads), чтобы распределить чтение файлов между репликами.
Параллельное чтение в многоузловых кластерах
В ClickHouse Cloud и самоуправляемых многоузловых сервисах кластерные варианты lake-табличных функций распределяют чтение файлов [Parquet](/ru/reference/formats/Parquet/Parquet) между репликами. Узел-инициатор параллельно распределяет файлы между воркерами. Используйте кластерные варианты для батч-чтения и загрузок по расписанию при работе с большими таблицами. В одноузловых развертываниях достаточно стандартной табличной функции.
Передайте имя вашего кластера первым аргументом (`'default'` в ClickHouse Cloud). Кластерные варианты доступны для всех поддерживаемых форматов:
| Формат | Кластерные функции |
| - | - |
| Iceberg | [icebergS3Cluster()](/ru/reference/functions/table-functions/icebergCluster), [icebergAzureCluster()](/ru/reference/functions/table-functions/icebergCluster) |
| Delta Lake | [deltaLakeCluster()](/ru/reference/functions/table-functions/deltalakeCluster), [deltaLakeAzureCluster()](/ru/reference/functions/table-functions/deltalakeCluster) |
| Hudi | [hudiCluster()](/ru/reference/functions/table-functions/hudiCluster) |
| Paimon | [paimonS3Cluster()](/ru/reference/functions/table-functions/paimonCluster) |
Кластерное чтение можно сочетать с другими настройками производительности.
Кластерные функции и On-Demand Compute
Кластерные варианты функций, такие как [`icebergS3Cluster`](/ru/reference/functions/table-functions/icebergCluster) и [`deltaLakeCluster`](/ru/reference/functions/table-functions/deltalakeCluster), распределяют чтение файлов между узлами вашего существующего кластера. Сама кластерная функция не добавляет вычислительных ресурсов. On-Demand Compute — это возможность ClickHouse Cloud, которая временно выделяет подходящим запросам дополнительных воркеров из управляемого пула, используя ваш существующий сервис и конечную точку.
В период закрытой предварительной версии On-Demand Compute поддерживает только подходящие запросы `SELECT` к поддерживаемым данным Apache Iceberg и Delta Lake. Условия применимости и ограничения см. в [документации по On-Demand Compute](/ru/products/cloud/features/infrastructure/on-demand-compute).
Ограничение батч-чтений диапазоном снимков
Для повторяющихся батч-загрузок из таблиц в data lake ограничивайте каждый запуск диапазоном снимков, а не перечитывайте всю таблицу целиком. Без таких границ ClickHouse может при каждом запуске сканировать все версии и файлы, что увеличивает число чтений из Объектного хранилища и время выполнения запроса.
Сохраняйте идентификатор снимка из последней успешной загрузки и используйте его как нижнюю границу при следующем запуске.
* Для Iceberg читайте состояние на определённый момент времени с помощью [iceberg\_snapshot\_id](/ru/reference/settings/session-settings/iceberg#iceberg_snapshot_id) или [iceberg\_timestamp\_ms](/ru/reference/settings/session-settings/iceberg#iceberg_timestamp_ms) (25.4+). Для таблиц, в которые данные только добавляются, сочетайте настройки снимков с фильтрами по партициям в `WHERE`. Используйте [system.iceberg\_history](/ru/reference/system-tables/iceberg_history) (25.6+), чтобы находить ID снимков между запусками.
* Для Delta Lake читайте изменения между двумя версиями с помощью [delta\_lake\_snapshot\_start\_version](/ru/reference/settings/session-settings/delta-lake#delta_lake_snapshot_start_version) и [delta\_lake\_snapshot\_end\_version](/ru/reference/settings/session-settings/delta-lake#delta_lake_snapshot_end_version) (25.12+). Чтобы прочитать один снимок, используйте [delta\_lake\_snapshot\_version](/ru/reference/settings/session-settings/delta-lake#delta_lake_snapshot_version) (25.8+). Пример CDF см. в разделе [change data feed в Delta](#delta-incremental-sync).
Локальное кэширование файлов Parquet
Оба формата поддерживают [enable\_filesystem\_cache](/ru/reference/settings/session-settings/enable-filesystem#enable_filesystem_cache), чтобы сохранять часто используемые файлы [Parquet](/ru/reference/formats/Parquet/Parquet) на локальном диске между запросами. В самоуправляемых развертываниях настройте [диск файлового кэша](/ru/concepts/features/configuration/server-config/storing-data#using-local-cache) в конфигурации сервера, чтобы этому параметру было куда записывать данные. В ClickHouse Cloud кэширование настраивается автоматически. При бенчмаркинге установите `enable_filesystem_cache = 0`, чтобы попадания в кэш не скрывали изменения между запусками.
Apache Iceberg
Большинство оптимизаций чтения в Iceberg включено по умолчанию. Приведённые ниже настройки управляют отсечением партиций, кэшированием метаданных и числом обращений к каталогу.
Настройки чтения
| Настройка | С версии | По умолчанию | Примечания |
| - | - | - | - |
| [use\_iceberg\_partition\_pruning](/ru/reference/settings/session-settings/use-iceberg#use_iceberg_partition_pruning) | 25.1 | `1` с 25.6 | Пропускает файлы данных на основе метаданных партиций в манифестах |
| [use\_iceberg\_metadata\_files\_cache](/ru/reference/settings/session-settings/use-iceberg#use_iceberg_metadata_files_cache) | 25.4 | `1` | Кэширует в памяти списки манифестов и JSON-файлы метаданных |
| [iceberg\_metadata\_staleness\_ms](/ru/reference/settings/session-settings/iceberg-metadata#iceberg_metadata_staleness_ms) | 26.3 | `0` | Настройка запроса. Использует кэшированные метаданные, если они не старше этого окна, вместо обращения к каталогу при каждом запросе |
| [iceberg\_use\_version\_hint](/ru/reference/functions/table-functions/iceberg#writes-into-iceberg-table) | 25.6 | — | Читает `version-hint.text` для более быстрого определения метаданных при прямом доступе по пути |
Снизить задержку каталога
Для таблиц Iceberg, подключённых к каталогу, при каждом запросе приходится получать метаданные, если она не кэшируется. Используйте две настройки вместе (26.4+):
1. Установите [iceberg\_metadata\_async\_prefetch\_period\_ms](/ru/reference/engines/table-engines/integrations/iceberg#async-metadata-prefetch) при создании таблицы, чтобы предварительно подгружать метаданные в фоновом режиме.
2. Установите [iceberg\_metadata\_staleness\_ms](/ru/reference/settings/session-settings/iceberg-metadata#iceberg_metadata_staleness_ms) (26.3+) в запросах, чтобы допускать слегка устаревшие метаданные и тем самым избежать лишнего обращения к каталогу.
```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](/ru/reference/engines/table-engines/integrations/iceberg#metadata-file-resolution) (25.4+) или [iceberg\_metadata\_table\_uuid](/ru/reference/engines/table-engines/integrations/iceberg#metadata-file-resolution) при создании таблицы. См. [Определение файла метаданных](/ru/reference/engines/table-engines/integrations/iceberg#metadata-file-resolution).
Доступ к прошлым версиям
Чтобы прочитать исторический снимок, используйте [iceberg\_timestamp\_ms](/ru/reference/settings/session-settings/iceberg#iceberg_timestamp_ms) или [iceberg\_snapshot\_id](/ru/reference/settings/session-settings/iceberg#iceberg_snapshot_id) (оба параметра доступны в 25.4+). Не задавайте оба параметра в одном запросе. Перед выбором идентификатора просмотрите историю снимков в [system.iceberg\_history](/ru/reference/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](/ru/reference/settings/session-settings/allow#allow_insert_into_iceberg) (25.7+, бета с 26.2), можно управлять размером выходных файлов и количеством партиций при вставке:
| Настройка | С версии | Назначение |
| - | - | - |
| [iceberg\_insert\_max\_rows\_in\_data\_file](/ru/reference/settings/session-settings/iceberg-insert#iceberg_insert_max_rows_in_data_file) | 25.9 | Ограничение числа строк в выходном файле данных |
| [iceberg\_insert\_max\_bytes\_in\_data\_file](/ru/reference/settings/session-settings/iceberg-insert#iceberg_insert_max_bytes_in_data_file) | 25.9 | Ограничение размера выходного файла данных в байтах |
| [iceberg\_insert\_max\_partitions](/ru/reference/settings/session-settings/iceberg-insert#iceberg_insert_max_partitions) | 25.12 | Ограничение на число партиций, записываемых за одну вставку |
См. [Запись в озера данных](/ru/guides/use-cases/data-warehousing/getting-started/writing-data) и [справочник по движку Iceberg](/ru/reference/engines/table-engines/integrations/iceberg).
Delta Lake
Начиная с версии 25.6 ClickHouse читает Delta Lake из S3 и GCS с помощью Rust-ядра Delta Lake. В версии 26.8 и более поздних версиях параметр называется [`allow_delta_kernel_rs`](/ru/reference/settings/session-settings/allow#allow_delta_kernel_rs), а в версиях с 25.5 по 26.7 — `allow_experimental_delta_kernel_rs`. Для Azure Blob Storage используйте [deltaLakeAzure()](/ru/reference/functions/table-functions/deltalake) со старым механизмом чтения, поскольку там это ядро отключено. Без ядра недоступны отсечение партиций, change data feed и чтение версий снимков.
Delta Kernel
Параметр Delta kernel должен быть включен для отсечения партиций, change data feed и чтения версии снимка. Начиная с версии 25.5, он включен по умолчанию для S3 и GCS. При его явном включении используйте имя, соответствующее вашей версии ClickHouse.
Для версии 26.8 и более поздних:
```sql theme={null}
SET allow_delta_kernel_rs = 1;
```
Для версий с 25.5 по 26.7:
```sql theme={null}
SET allow_experimental_delta_kernel_rs = 1;
```
Настройки чтения
| Setting | Since | Default | Notes |
| - | - | - | - |
| [delta\_lake\_enable\_engine\_predicate](/ru/reference/settings/session-settings/delta-lake#delta_lake_enable_engine_predicate) | 25.8 | `1` | Передает фильтры в kernel для отсечения партиций. Требует [Delta Kernel](#delta-kernel) |
| [delta\_lake\_reload\_schema\_for\_consistency](/ru/reference/settings/session-settings/delta-lake#delta_lake_reload_schema_for_consistency) | 26.3 | `0` | Перезагружает схему перед каждым запросом, если при параллельной записи схема изменяется |
| [delta\_lake\_snapshot\_start\_version](/ru/reference/settings/session-settings/delta-lake#delta_lake_snapshot_start_version) / [delta\_lake\_snapshot\_end\_version](/ru/reference/settings/session-settings/delta-lake#delta_lake_snapshot_end_version) | 25.12 | `-1` | Читает изменения CDF между двумя версиями снимка. Требует, чтобы CDF был включен в upstream |
| [delta\_lake\_snapshot\_version](/ru/reference/settings/session-settings/delta-lake#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](/ru/reference/settings/session-settings/delta-lake#delta_lake_snapshot_start_version) и [delta\_lake\_snapshot\_end\_version](/ru/reference/settings/session-settings/delta-lake#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](/ru/reference/settings/session-settings/allow#allow_delta_lake_writes) (25.9+), можно управлять размером выходного файла данных при вставке:
| Настройка | С версии | Назначение |
| - | - | - |
| [delta\_lake\_insert\_max\_rows\_in\_data\_file](/ru/reference/settings/session-settings/delta-lake#delta_lake_insert_max_rows_in_data_file) | 25.9 | Ограничение на число строк в выходном файле данных |
| [delta\_lake\_insert\_max\_bytes\_in\_data\_file](/ru/reference/settings/session-settings/delta-lake#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](/ru/reference/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](/ru/reference/settings/session-settings/show#show_remote_databases_in_system_tables) (25.8+). По умолчанию таблицы каталога скрыты при системной интроспекции. В версиях до 26.6 используйте его прежнее название: `show_data_lake_catalogs_in_system_tables`.
Посмотреть, какие файлы читаются
Iceberg и Delta Lake предоставляют [виртуальные столбцы](/ru/reference/functions/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`](/ru/reference/system-tables/query_log) до и после добавления фильтров или изменения настроек. `ProfileEvents`, такие как `ReadBufferFromS3Bytes` и `CachedReadBufferReadFromCacheBytes`, показывают, какой объём данных поступил из Объектного хранилища, а какой — из локального кэша. Полное пошаговое руководство по `query_log` и `EXPLAIN` см. в разделе [Диагностика медленных запросов](/ru/guides/clickhouse/performance-and-monitoring/diagnose-slow-queries).
Отключайте [enable\_filesystem\_cache](/ru/reference/settings/session-settings/enable-filesystem#enable_filesystem_cache) при проведении бенчмаркинга, чтобы попадания в кэш не скрывали различия между запусками.
ClickHouse предоставляет три системные таблицы для отладки на уровне метаданных. Включайте логирование только на время выполнения запроса. Они не предназначены для постоянного мониторинга.
| System table | Формат | С версии | Включается с помощью | Используется для |
| - | - | - | - | - |
| [system.iceberg\_metadata\_log](/ru/reference/system-tables/iceberg_metadata_log) | Iceberg | 25.9 | [iceberg\_metadata\_log\_level](/ru/reference/settings/session-settings/iceberg-metadata#iceberg_metadata_log_level) в запросе | Отслеживания чтения файлов метаданных и решений по отсечению партиций |
| [system.iceberg\_history](/ru/reference/system-tables/iceberg_history) | Iceberg | 25.6 | Автоматически заполняется для таблиц Iceberg в ClickHouse | Анализа истории снимков перед запросами доступа к прошлым версиям |
| [system.delta\_lake\_metadata\_log](/ru/reference/system-tables/delta_metadata_log) | Delta Lake | 25.10 | [delta\_lake\_log\_metadata](/ru/reference/settings/session-settings/delta-lake#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 отключают кэширование метаданных для списков манифестов и файлов, что замедляет последующие запросы к той же таблице. Используйте высокий уровень детализации только во время активного расследования. При проблемах с предикатами Delta Lake включите [delta\_lake\_throw\_on\_engine\_predicate\_error](/ru/reference/settings/session-settings/delta-lake#delta_lake_throw_on_engine_predicate_error) (25.8+), чтобы сразу завершать запрос с ошибкой, если ядро не может передать фильтр на уровень движка.
См. справочные страницы [iceberg\_metadata\_log](/ru/reference/system-tables/iceberg_metadata_log) и [delta\_lake\_metadata\_log](/ru/reference/system-tables/delta_metadata_log): там описаны столбцы и параметры детализации.
Следующие шаги
* [Начало работы](/ru/guides/use-cases/data-warehousing/getting-started/overview) — Полное руководство: от прямого выполнения запросов до обратной записи данных
* [Прямое выполнение запросов](/ru/guides/use-cases/data-warehousing/getting-started/querying-directly) — Табличные функции, движки и кластерные варианты для всех четырёх форматов
* [Подключение к каталогам](/ru/guides/use-cases/data-warehousing/getting-started/connecting-catalogs) — Настройка `DataLakeCatalog` с Unity Catalog
* [Запись в озёра данных](/ru/guides/use-cases/data-warehousing/getting-started/writing-data) — Обратная запись данных в Iceberg и Delta Lake
* [Матрица поддержки](/ru/guides/use-cases/data-warehousing/support-matrix) — Сравнение возможностей форматов, каталогов и бэкендов хранилищ