跳到主要内容
跳到主要内容

system.iceberg_metadata_log

system.iceberg_metadata_log 表记录了 ClickHouse 读取 Iceberg 表时的元数据访问和解析事件。它提供了每个已处理元数据文件或条目的详细信息，有助于调试、审计，以及理解 Iceberg 表结构的演变。

目的​

此表会记录从 Iceberg 表中读取的每个元数据文件及条目，包括根元数据文件、manifest 列表以及 manifest 条目。它帮助用户跟踪 ClickHouse 如何解析 Iceberg 表元数据，并诊断与模式演进、文件解析或查询计划相关的问题。

注意

此表主要用于调试。

列​

名称类型描述
event_dateDate日志记录的日期。
event_timeDateTime事件的时间戳。
query_idString触发元数据读取的查询 ID。
content_typeEnum8元数据内容的类型（见下文）。
table_pathStringIceberg 表的路径。
file_pathString根元数据 JSON 文件、Avro 清单列表或清单文件的路径。
contentStringJSON 格式的内容（来自 .json 的原始元数据、Avro 元数据或 Avro 条目）。
row_in_fileNullable(UInt64)文件中的行号（如适用）。对于 ManifestListEntry 和 ManifestFileEntry 类型的内容，该列存在。

content_type 值​

  • None: 无内容。
  • Metadata: 根元数据文件。
  • ManifestListMetadata: Manifest 列表的元数据。
  • ManifestListEntry: Manifest 列表条目。
  • ManifestFileMetadata: Manifest 文件的元数据。
  • ManifestFileEntry: Manifest 文件条目。
在 ClickHouse Cloud 中进行查询

该系统表中的数据保存在 ClickHouse Cloud 中每个节点的本地。因此，如需获得所有数据的完整视图，需要使用 clusterAllReplicas 函数。更多详情请参阅此处。

控制日志详细程度​

可以通过 iceberg_metadata_log_level 设置来控制要记录哪些元数据事件。

要记录当前查询中使用的所有元数据：

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}';

若要仅记录当前查询使用的根元数据 JSON 文件：

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}';

有关更多信息，请参阅 iceberg_metadata_log_level 设置的说明。

注意事项​

  • 仅在需要对 Iceberg 表进行深入排查时才在查询级别使用 iceberg_metadata_log_level。否则，可能会在日志表中填充过多元数据，从而导致性能下降。
  • 该表可能包含重复条目，因为它主要用于调试，并不保证每个实体的唯一性。
  • 如果使用的 content_type 比 ManifestListMetadata 更为详尽，则会对 manifest 列表禁用 Iceberg 元数据缓存。
  • 同样地，如果使用的 content_type 比 ManifestFileMetadata 更为详尽，则会对 manifest 文件禁用 Iceberg 元数据缓存。

另请参阅​