文档首页/ 智能数据湖 AIDataLake/ Aura语法参考/ SQL语法参考/ 函数和操作符/ Iceberg表服务函数

更新时间：2026-07-09 GMT+08:00

Iceberg表服务函数

iceberg_expire_snapshots

描述：Iceberg每个commit都会生成一个新快照，同时保留旧数据和元数据，以便进行快照隔离和time travel。expire snapshots可以用来清理不再需要的旧快照以及仅被不需要快照包含的数据文件，以提高查询、成本效率。

注意事项：

要明确旧快照的清理、保留策略。执行旧快照清理后，被删除的旧快照数据将无法再通过常规查询访问，如果有正在运行的查询依赖于即将过期的快照数据，可能会导致查询失败或结果不准确。
执行expire snapshots，retain_last、older_than、snapshot_ids可能会出现条件互相冲突的场景，iceberg不是严格按照传入条件处理的，会尽可能多地保留snapshots。

语法：

     iceberg_expire_snapshots('schema.table','older_than')
iceberg_expire_snapshots('schema.table','older_than', retain_last, 'snapshot_ids')

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要操作的表
older_than	timestamp	5天前	是	超过该时限的快照将被删除注意：需要输入确定具体时区，避免误解。可以在输入时指定，或者通过set timezone=xxx指定。
retain_last	int	1	否	保留多少个snapshots。
snapshot_ids	string	无	否	以分号（;）分隔, 可以传入多个snapshot_id。

返回值：

名称	说明
deleted_data_files_count	被删除的数据文件数量。
deleted_position_delete_files_count	被删除的position delete文件数量。
deleted_equality_delete_files_count	被删除的equality delete文件数量。
deleted_manifest_files_count	被删除的清单文件数量。
deleted_manifest_lists_count	被删除的快照文件数量。
deleted_statistics_files_count	被删除的统计文件数量。

iceberg_rewrite_manifests

描述：Iceberg表跟踪每个数据文件，数据文件越多，存储在快照文件中的元数据就越多，rewrite manifests可以重写表的清单，优化扫描规划。

注意事项：该操作会生成新的清单文件，可能影响正在进行的查询和写入操作，导致元数据冲突，应避免与其他操作并发执行。

语法：

     iceberg_rewrite_manifests(table)
iceberg_rewrite_manifests(table, options)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要操作的表。
options	array	无	否	操作功能选项。格式样例： '{spec_id=2}'

options支持如下选项：

名称	类型	说明
spec_id	int32	仅重写指定spec_id的manifest文件。有效值可查询iceberg_partition_specs获得。

返回值：

名称	说明
rewritten_manifests_count	被重写的清单文件数量。
added_manifests_count	新增的清单文件数量。

iceberg_remove_orphanfiles

描述：对于未被任何Iceberg元数据文件引用的文件，我们称之为孤立文件，这类文件可能由失败的事务、并发操作未能成功提交、旧快照清理失败、元数据清理失败等原因造成，通常可以删除。

注意事项：确保无并发写操作，删除过程中，如果有运行中的写入任务，可能会误删正在生成的文件（未提交的临时文件）。

语法：

     iceberg_remove_orphanfiles('schema.table')
iceberg_remove_orphanfiles('schema.table', 'older_than', 'location')

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要操作的表
older_than	timestamp	三天前	否	早于older_than的孤立文件将被删除。
location	string	表根目录	否	location下的孤立文件将被删除。

返回值：

名称	说明
orphan_file_location	被认定为孤立文件的文件路径。

iceberg_add_files

描述：将目标文件夹下的所有文件添加到iceberg表中。

该语法会递归扫描目标文件夹下的所有文件，并添加到iceberg表中。

所有文件必须满足：

必须为parquet文件格式。
parquet文件中的列名、列类型、列个数（包括分区列）必须与目标表一致。
单个parquet文件中的所有数据必须隶属于同一个分区。

语法：

     iceberg_add_files(table,foldername,iscopy)

入参说明：

table：regclass类型，表名。
foldername：text类型，文件夹路径列表，支持多个路径，以逗号分隔。
iscopy：bool类型，是否拷贝。

返回值：bool，是否执行成功。

iceberg_show_snapshots

描述：查询指定ICEBERG表的快照信息。

语法：

     iceberg_show_snapshots(table)

入参说明：table：regclass类型，表名。

返回值：

sequence_number：int64类型，快照序号。
snapshot_id：int64类型，快照ID。
create_time：timestamptz类型，快照创建时间。
parent_id：int64类型，快照的父亲节点，如果为0，表示无父亲节点。
operation：text类型，本次快照的操作类型。
manifestlist：text类型，快照对应的manifest list路径。
summary：text类型，快照统计信息。

iceberg_manifests

描述：查询指定ICEBERG表的所有清单文件。

语法：

     iceberg_manifests(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
content	int32类型，manifest中文件内容类型；0表示数据文件（DATA），1表示删除文件（DELETES）。
path	text类型，manifest文件在存储系统中的完整路径。
length	int64类型，manifest文件的字节大小。
partition_spec_id	int32类型，该manifest所使用的分区规范ID。
added_snapshot_id	int64类型，创建此manifest的快照ID。
added_data_files_count	int32类型，此manifest中新增的数据文件数量。
existing_data_files_count	int32类型，此manifest中已存在的数据文件数量。
deleted_data_files_count	int32类型，此manifest中被标记为删除的数据文件数量。
added_delete_files_count	int32类型，此manifest中新增的删除文件数量。
existing_delete_files_count	int32类型，此manifest中已存在的删除文件数量。
deleted_delete_files_count	int32类型，此manifest中被标记为删除的删除文件数量。
partition_summaries	text类型，以JSON数组形式存储的分区统计摘要，每个元素对应一个分区字段，包含contains_null（是否含null）、contains_nan（是否含NaN，仅浮点类型）、lower_bound和upper_bound（该分区字段在此manifest中的值域范围）。

iceberg_manifest_entries

描述：查询指定ICEBERG表的所有manifest条目（entries）信息，每个条目反映一个数据文件在特定快照中的状态。

语法：

     iceberg_manifest_entries(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
status	int32类型，文件状态；0表示已存在（EXISTING），1表示新增（ADDED），2表示已删除（DELETED）。
snapshot_id	int64类型，该条目所属的快照ID。
sequence_number	int64类型，文件序列号，用于确定写入顺序。
file_sequence_number	int64类型，标识该文件在单个快照内的添加顺序。
data_file	text类型，包含该数据文件的完整元数据（如路径、格式、分区、大小、记录数及列级统计信息等）。
readable_metrics	text类型，以可读形式呈现从data_file中提取的列级扩展统计信息（如最小值、最大值、空值计数等），便于人工检查和调试。

iceberg_partitions

描述：查询指定ICEBERG表的分区统计信息，汇总每个分区中所有数据文件的聚合指标。

语法：

     iceberg_partitions(table, small_file_threshold)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。
small_file_threshold	int32	128（MB）	否	小文件的阈值。

返回值：

名称	说明
partition	text类型，分区字段的具体值（结构与表的分区schema一致）。
spec_id	int32类型，该分区所使用的分区规范ID。
record_count	int64类型，该分区内所有活跃数据文件包含的总记录数。
file_count	int32类型，该分区内活跃数据文件的总数。
total_data_file_size_in_bytes	int64类型，该分区内所有活跃数据文件的总大小（字节）。
position_delete_record_count	int64类型，该分区内由位置删除文件（positional delete files）标记的删除记录总数。
position_delete_file_count	int32类型，该分区内位置删除文件的数量。
equality_delete_record_count	int64类型，该分区内由等值删除文件（equality delete files）标记的删除记录总数。
equality_delete_file_count	int32类型，该分区内等值删除文件的数量。
last_updated_at	timestamptz类型，该分区最近一次被更新的时间（对应快照的创建时间）。
updated_snapshot_id	int64类型，最近一次更新该分区的快照ID。
small_file_count	int64类型，小文件的数量。

iceberg_partition_specs

描述：查询指定ICEBERG表的所有历史版本的分区键定义集合。

语法：

     iceberg_partition_specs(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
spec_id	int32类型，分区键定义的版本号ID。
field_id	int32类型，分区键的ID。
name	text类型，分区键的名字。
transform	text类型，分区键的表达式的文本描述。
source_id	int32类型，分区键的表达式所引用的表列ID。该值对应iceberg_schemas中的field_id字段。

iceberg_schemas

描述：查询指定ICEBERG表的所有历史版本的表定义集合。

语法：

     iceberg_schemas(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
schema_id	int32类型，表定义的版本号ID。
field_id	int32类型，列ID。
name	text类型，列的名字。
type	text类型，列的类型。

iceberg_history

描述：查询指定ICEBERG表的历史版本信息。

语法：

     iceberg_history(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
made_current_at	timestamptz类型，快照创建时间。
snapshot_id	int64类型，快照ID。
parent_id	int64类型，该快照的父快照id。
is_current_ancestor	bool类型，snapshot_id是否是当前表最新快照的祖先快照。

iceberg_metadata_log_entries

描述：查询指定ICEBERG表的metadata文件信息。

语法：

     iceberg_metadata_log_entries(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
timestamp	timestamptz类型，metadata.json文件的生成时间。
file	string类型，metadata.json文件的路径。
latest_snapshot_id	int64类型，metadata.json文件创建时，对应的最新快照。
latest_schema_id	int64类型，metadata.json文件创建时，表的最新表结构（Schema）id。
latest_sequence_number	int64类型，metadata.json文件创建时，表的最新sequence_number。

iceberg_files

描述：查询指定ICEBERG表的所有数据文件和删除文件信息。

语法：

     iceberg_files(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
content	int32类型，文件类型。
file_path	string类型，文件路径。
file_format	string类型，文件存储格式。
spec_id	int64类型，文件所属spec_id。
record_count	int64类型，文件内的数据行数。
file_size_in_bytes	int64类型，文件大小。
column_sizes	string类型，各列的存储大小。
value_counts	string类型，各列的非空值数量。
null_value_counts	string类型，各列的空值数量。
nan_value_counts	string类型，各列的非数值数量。
lower_bounds	string类型，各列值的下界。
upper_bounds	string类型，各列值的上界。

iceberg_position_delete_files

描述：查询指定ICEBERG表的位置删除文件信息。

语法：

     iceberg_position_delete_files(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
file_path	string类型，与删除文件关联的数据文件路径。
pos	int64类型，对应文件的行号。
partition	string类型，分区名。
spec_id	int64类型，分区spec_id。
delete_file_path	string类型，删除文件的路径。

iceberg_refs

描述：查询指定ICEBERG表的所有branch/tag。

语法：

     iceberg_refs(table)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	要查询的表。

返回值：

名称	说明
name	string类型，名称。
type	string类型，branch或tag。
snapshot_id	int64类型，对应的snapshot id。
max_reference_age_in_ms	int64类型，保留时间，单位ms。
min_snapshots_to_keep	int64类型，保留快照的最小数量。
max_snapshot_age_in_ms	int64类型，快照的最大保留时间，单位ms。

iceberg_register_table

描述：将已存在的metadata.json文件注册到当前Catalog中。

语法：

     select * from iceberg_register_table(table, file_path)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	注册后的表名。
file_path	string	无	是	metadata.json对应的路径。

返回值：

名称	说明
snapshot_id	int64类型，新注册表的Snapshot ID。
record_count	int64类型，新注册表的总行数。
total_data_files_count	int64类型，新注册表的数据文件数量。

iceberg_rollback_to_snapshot

描述：回滚表主分支到指定快照。

语法：

     select * from iceberg_rollback_to_snapshot(table, snapshot_id)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	表名称。
snapshot_id	int64	无	是	指定要回滚到的快照ID。

返回值：

名称	说明
previous_snapshot_id	int64类型，回滚前表的Snapshot ID。
current_snapshot_id	int64类型，回滚后表的Snapshot ID。

iceberg_rollback_to_timestamp

描述：回滚表主分支到指定时间戳。

语法：

     select * from iceberg_rollback_to_timestamp(table, timestamp)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	表名称。
timestamp	timestamptz	无	是	指定要回滚到的时间戳。

返回值：

名称	说明
previous_snapshot_id	int64类型，回滚前表的Snapshot ID。
current_snapshot_id	int64类型，回滚后表的Snapshot ID。

iceberg_set_current_snapshot

描述：设置主分支的当前快照。

语法：

     select * from iceberg_set_current_snapshot(table, snapshot_id)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	表名。
snapshot_id	int64	无	是	目标快照ID。

返回值：

名称	说明
previous_snapshot_id	int64类型，设置快照前表的Snapshot ID。
current_snapshot_id	int64类型，设置快照后表的Snapshot ID。

iceberg_cherrypick_snapshot

描述：提取快照到主分支并创建新快照，且提取的快照不能是主分支的祖先节点。

语法：

     select * from iceberg_cherrypick_snapshot(table, snapshot_id)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	表名称。
snapshot_id	int64	无	是	要提取的快照ID。

返回值：

名称	说明
previous_snapshot_id	int64类型，提取快照前表的Snapshot ID。
current_snapshot_id	int64类型，提取快照后表的Snapshot ID。

iceberg_fast_forward

描述：快进分支，即将一个分支的当前快照快进到另一个分支的最新快照。

语法：

     select * from iceberg_fast_forward(table, from_branch, to_branch)

入参说明：

名称	类型	默认值	是否必填	说明
table	string	无	是	表名称。
from_branch	string	无	是	当前分支。
to_branch	string	无	是	目标分支。

返回值：

名称	说明
branch_updated	string类型，更新的分支名称。
previous_ref	int64类型，快照快进前表的Snapshot ID。
updated_ref	int64类型，快照快进后表的Snapshot ID。

父主题： 函数和操作符

上一篇：统计信息函数

下一篇：大模型推理函数

意见反馈

文档内容是否对您有帮助？

有帮助没帮助

提供反馈

提交成功！非常感谢您的反馈，我们会继续努力做到更好！您可在我的云声建议查看反馈及问题处理状态。

系统繁忙，请稍后重试

如您有其它疑问，您也可以通过华为云社区问答频道来与我们联系探讨

云宝助手提问云社区提问

Iceberg表服务函数

iceberg_expire_snapshots

iceberg_rewrite_manifests

iceberg_remove_orphanfiles

iceberg_add_files

iceberg_show_snapshots

iceberg_manifests

iceberg_manifest_entries

iceberg_partitions

iceberg_partition_specs

iceberg_schemas

iceberg_history

iceberg_metadata_log_entries

iceberg_files

iceberg_position_delete_files

iceberg_refs

iceberg_register_table

iceberg_rollback_to_snapshot

iceberg_rollback_to_timestamp

iceberg_set_current_snapshot

iceberg_cherrypick_snapshot

iceberg_fast_forward

相关文档

意见反馈

文档内容是否对您有帮助？