system.delta_lake_metadata_log

The system.delta_lake_metadata_log table records metadata access and parsing events for Delta Lake tables read by ClickHouse. It provides detailed information about each metadata file, which is useful for debugging, auditing, and understanding Delta table structure evolution.

Purpose

This table logs every metadata file read from Delta Lake tables. It helps users trace how ClickHouse interprets Delta table metadata and diagnose issues related to schema evolution, snapshot resolution, or query planning.

Note

This table is primarily intended for debugging purposes.

Note

Columns

Name	Type	Description
event_date	Date	Date of the log file.
event_time	DateTime	Timestamp of the event.
query_id	String	Query ID that triggered the metadata read.
table_path	String	Path to the Delta Lake table.
file_path	String	Path to the root metadata JSON file.
content	String	Content in JSON format (raw metadata from .json).

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 for further details.

Controlling log verbosity

You can control which metadata events are logged using the delta_lake_log_metadata setting.

To log all metadata used in the current query:

SELECT * FROM my_delta_table SETTINGS delta_lake_log_metadata = 1;

SYSTEM FLUSH LOGS delta_lake_metadata_log;

SELECT *
FROM system.delta_lake_metadata_log
WHERE query_id = '{previous_query_id}';