title_wip

[Edit this page](https://github.com/ClickHouse/ClickHouse/tree/master/docs/en/operations/system-tables/iceberg_metadata_log.md)

The `system.iceberg_metadata_log` table records metadata access and parsing events for Iceberg tables read by ClickHouse. It provides detailed information about each metadata file or entry processed, which is useful for debugging, auditing, and understanding Iceberg table structure evolution.

## Purpose[​](#purpose "Direct link to Purpose")

This table logs every metadata file and entry read from Iceberg tables, including root metadata files, manifest lists, and manifest entries. It helps users trace how ClickHouse interprets Iceberg table metadata and diagnose issues related to schema evolution, file resolution, or query planning.

Note

This table is primarily intended for debugging purposes.

## Columns[​](#columns "Direct link to Columns")

|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Name Type Description|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `event_date` [Date](/docs/sql-reference/data-types/date) Date of the log entry.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `event_time` [DateTime](/docs/sql-reference/data-types/datetime) Timestamp of the event.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `query_id` [String](/docs/sql-reference/data-types/string) Query ID that triggered the metadata read.|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `content_type` [Enum8](/docs/sql-reference/data-types/enum) Type of metadata content (see below).|  |  |  |  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `table_path` [String](/docs/sql-reference/data-types/string) Path to the Iceberg table.|  |  |  |  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `file_path` [String](/docs/sql-reference/data-types/string) Path to the root metadata JSON file, Avro manifest list, or manifest file.|  |  |  |  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | --- | --- | --- | | `content` [String](/docs/sql-reference/data-types/string) Content in JSON format (raw metadata from .json, Avro metadata, or Avro entry).|  |  |  |  |  |  | | --- | --- | --- | --- | --- | --- | | `row_in_file` [Nullable](/docs/sql-reference/data-types/nullable)([UInt64](/docs/sql-reference/data-types/int-uint)) Row number in the file, if applicable. Present for `ManifestListEntry` and `ManifestFileEntry` content types.| `pruning_status` [Nullable](/docs/sql-reference/data-types/nullable)([Enum8](/docs/sql-reference/data-types/enum)) Pruning status for the entry. 'NotPruned', 'PartitionPruned', 'MinMaxIndexPruned'. Pay attention that partition pruning is done before minmax pruning so 'PartitionPruned' means that the entry was pruned by partition filter and minmax pruning was not even attempted. Present for `ManifestFileEntry` content type. | | | | | | | | | | | | | | | | | | | | | | | | | | | | | |

## `content_type` values[​](#content-type-values "Direct link to content-type-values")

- `None`: No content.
- `Metadata`: Root metadata file.
- `ManifestListMetadata`: Manifest list metadata.
- `ManifestListEntry`: Entry in a manifest list.
- `ManifestFileMetadata`: Manifest file metadata.
- `ManifestFileEntry`: Entry in a manifest file.

Querying in ClickHouse Cloud

The data in this system table is held locally on each node in ClickHouse Cloud. Obtaining a complete view of all data, therefore, requires the `clusterAllReplicas` function. See [here](/docs/operations/system-tables/overview#system-tables-in-clickhouse-cloud) for further details.

## Controlling log verbosity[​](#controlling-log-verbosity "Direct link to Controlling log verbosity")

You can control which metadata events are logged using the [`iceberg_metadata_log_level`](/docs/operations/settings/settings#iceberg_metadata_log_level) setting.

To log all metadata used in the current query:

```
SELECT * FROM my_iceberg_table SETTINGS iceberg_metadata_log_level = 'manifest_file_entry';

SYSTEM FLUSH LOGS iceberg_metadata_log;

SELECT content_type, file_path, row_in_file
FROM system.iceberg_metadata_log
WHERE query_id = '{previous_query_id}';
```

To log only the root metadata JSON file used in the current query:

```
SELECT * FROM my_iceberg_table SETTINGS iceberg_metadata_log_level = 'metadata';

SYSTEM FLUSH LOGS iceberg_metadata_log;

SELECT content_type, file_path, row_in_file
FROM system.iceberg_metadata_log
WHERE query_id = '{previous_query_id}';
```

See more information in the description of the [`iceberg_metadata_log_level`](/docs/operations/settings/settings#iceberg_metadata_log_level) setting.

### Good To Know[​](#good-to-know "Direct link to Good To Know")

- Use `iceberg_metadata_log_level` at the query level only when you need to investigate your Iceberg table in detail. Otherwise, you may populate the log table with excessive metadata and experience performance degradation.
- The table contains duplicate entries, as it is intended primarily for debugging and does not guarantee uniqueness per entity. Separate rows store content and pruning status because they are collected at different moments in a program. Content is collected when the metadata is read, pruning status is collected when the metadata is checked for pruning. **Never rely on the table itself for deduplication.**
- If you use a `content_type` more verbose than `ManifestListMetadata`, the Iceberg metadata cache is disabled for manifest lists.
- Similarly, if you use a `content_type` more verbose than `ManifestFileMetadata`, the Iceberg metadata cache is disabled for manifest files.
- If the SELECT query was cancelled or failed, the log table may still contain entries for metadata processed before the failure but will not contain information about metadata entities that were not processed.

## See also[​](#see-also "Direct link to See also")

- [Iceberg Table Engine](/docs/engines/table-engines/integrations/iceberg)
- [Iceberg Table Function](/docs/sql-reference/table-functions/iceberg)
- [system.iceberg\_history](/docs/operations/system-tables/iceberg_history)

- [Purpose](#purpose)- [Columns](#columns)- [`content_type` values](#content-type-values)- [Controlling log verbosity](#controlling-log-verbosity)
        - [Good To Know](#good-to-know)- [See also](#see-also)

Was this page helpful?