大网数据广告活动
数据库部署与 SQL 参考

StarRocks 中文参考:Iceberg Procedures

· 52CE 我爱测

StarRocks Iceberg Catalog 支持多种用于管理 Iceberg 表的存储过程,包括快照管理、分支管理、数据维护、元数据管理和表管理。

Iceberg Procedures

StarRocks Iceberg Catalog 支持多种用于管理 Iceberg 表的存储过程,包括快照管理、分支管理、数据维护、元数据管理和表管理。

您必须具有相应的权限才能执行存储过程。有关权限的更多信息,请参见 Privileges 。

快照管理

回滚到快照

将表回滚到特定快照。此操作将表的当前快照设置为指定的快照 ID。

rollback_to_snapshot 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE rollback_to_snapshot(<snapshot_id>)

Parameters

snapshot_id: 您想要回滚到的快照 ID。

示例

将表回滚到 ID 为 98765 的快照:

ALTER TABLE iceberg.sales.order
EXECUTE rollback_to_snapshot(98765);

回滚到时间点

将表回滚到指定时间点之前提交的最新快照。时间点按当前会话的时区解析。

rollback_to_timestamp 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE rollback_to_timestamp(<timestamp>)

Parameters

timestamp: 将表回滚到该时间点之前提交的最新快照。格式:'YYYY-MM-DD HH:MM:SS'。如果该时间点之前没有提交过快照,则返回错误。

示例

将表回滚到 2025-01-01 00:00:00 之前的状态:

ALTER TABLE iceberg.sales.order
EXECUTE rollback_to_timestamp('2025-01-01 00:00:00');

设置当前快照

将表的当前快照设置为指定的快照 ID。与 rollback_to_snapshot 不同,该快照不需要是当前快照的祖先,因此可以用于将表重新前移到已被回滚掉的快照。

set_current_snapshot 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE set_current_snapshot(<snapshot_id>)

Parameters

snapshot_id: 要设置为表当前快照的快照 ID。

示例

ALTER TABLE iceberg.sales.order
EXECUTE set_current_snapshot(98765);

选择快照

选择特定的快照并将其应用到表的当前状态。此操作基于现有快照创建一个新快照,而原始快照保持不变。

cherrypick_snapshot 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE cherrypick_snapshot(<snapshot_id>)

Parameters

snapshot_id: 您要进行 cherry pick 的快照的 ID。

示例

ALTER TABLE iceberg.sales.order
EXECUTE cherrypick_snapshot(54321);

分支管理

将一个分支快速前移到另一个分支

将一个分支快速前移到另一个分支的最新快照。此操作会将源分支的快照更新为与目标分支的快照相匹配。

fast_forward 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE fast_forward('<from_branch>', '<to_branch>')

参数

  • from_branch: 您想要快进的分支。用引号将分支名称引起来。
  • to_branch: 您想要将 from_branch 快进到的分支。用引号将分支名称引起来。

示例

将 main 分支快进到 test-branch 分支:

ALTER TABLE iceberg.sales.order
EXECUTE fast_forward('main', 'test-branch');

数据维护

重写数据文件

重写数据文件以优化文件布局。此过程合并小文件,以提高查询性能并减少元数据开销。

rewrite_data_files 语法

ALTER TABLE [catalog.][database.]table_name 
EXECUTE rewrite_data_files
("key"=value [,"key"=value, ...]) 
[WHERE <predicate>]

Parameters

rewrite_data_files 属性

"key"=value 键值对,用于声明手动 Compaction 行为。请注意,您需要将 key 包含在双引号中。

min_file_size_bytes
  • 说明:小数据文件的上限。Compaction 期间,将合并大小小于此值的数据文件。
  • 单位:Byte
  • 类型:Int
  • 默认值:268,435,456 (256 MB)
batch_size
  • 说明:每个批次中可以处理的最大数据大小。
  • 单位:Byte
  • 类型:Int
  • 默认值:10,737,418,240 (10 GB)
rewrite_all
  • 说明:是否在 Compaction 期间重写所有数据文件,忽略使用特定要求筛选数据文件的参数。
  • 单位:-
  • 类型:Boolean
  • 默认值:false
batch_parallelism
  • 说明:Compaction 期间要处理的并行批次数。
  • 单位:-
  • 类型:Int
  • 默认值:1
delete_ratio_threshold
  • 说明:大于 min_file_size_bytes 的数据文件,如果其 Deletion Vector 或文件级 Position Delete 文件删除的行数占该文件行数的比例达到该值,也会被重写。取值范围:[0, 1]。Equality Delete 文件和分区级 Position Delete 文件不计入该比例。
  • 单位:-
  • 类型:Double
  • 默认值:0.3
delete_file_threshold
  • 说明:大于 min_file_size_bytes 的数据文件,如果作用于它的 Delete 文件数量不少于该值,也会被重写。必须为正整数。
  • 单位:-
  • 类型:Int
  • 默认值:无限制
WHERE clause
  • Description: 用于指定参与 Compaction 的分区所使用的过滤条件。

示例

以下示例对 Iceberg 表 t1 中的特定分区执行手动 Compaction。这些分区由子句 WHERE part_col = 'p1' 表示。在这些分区中,小于 134,217,728 字节(128 MB)的数据文件将在 Compaction 期间合并。

ALTER TABLE t1 EXECUTE rewrite_data_files("min_file_size_bytes"= 134217728) WHERE part_col = 'p1';

元数据管理

过期快照

过期早于特定时间戳的快照。此操作会删除过期快照的数据文件,从而帮助管理存储使用情况。

expire_snapshots 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE expire_snapshots(
    [ [older_than =] '<datetime>' ] [,  [retain_last =] <int> ]
)

Parameters

older_than
  • 描述:快照将被删除的时间戳。如果未指定,则默认删除早于 5 天(从当前时间开始计算)的文件。格式:'YYYY-MM-DD HH:MM:SS'。
  • 类型:DATETIME
  • 是否必须:否
retain_last
  • 描述:要保留的最新快照的最大数量。达到此阈值时,将删除较早的快照。如果未指定,则默认仅保留一个快照。
  • 类型:整数
  • 必填:否

示例

删除 '2023-12-17 00:14:38' 之前的快照,并保留两个快照:

-- With the parameter key specified:
ALTER TABLE iceberg.sales.order
EXECUTE expire_snapshots(older_than = '2023-12-17 00:14:38', retain_last = 2);

-- With the parameter key unspecified:
ALTER TABLE iceberg.sales.order
EXECUTE expire_snapshots('2023-12-17 00:14:38', 2);

删除孤立文件

从表中删除未被任何有效快照引用且早于指定时间戳的孤立文件。此操作有助于清理未使用的文件并回收存储空间。

remove_orphan_files 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE remove_orphan_files(
    [ [older_than =] '<datetime>' ] [,  [location =] '<string>' ]
)

Parameters

older_than
  • 说明:删除孤立文件的时间戳。如果未指定,则默认删除早于 7 天(从当前时间开始计算)的文件。格式:'YYYY-MM-DD HH:MM:SS'。该值距当前时间至少要有 iceberg_remove_orphan_files_min_retention_seconds(默认 24 小时)。更接近当前时间的值会被拒绝,因为删除这么新的文件可能删掉并发写入尚未提交的数据。
  • 类型:DATETIME
  • 是否必须:否
location
  • 描述:您要从中删除孤立文件的目录。它必须是表位置的子目录。如果未指定,则默认使用表位置。
  • 类型:STRING
  • 是否必须:否

示例

从表位置的子目录 sub_dir 中删除早于 '2024-01-01 00:00:00' 的孤立文件:

-- With the parameter key specified:
ALTER TABLE iceberg.sales.order
EXECUTE remove_orphan_files(older_than = '2024-01-01 00:00:00', location = 's3://iceberg-bucket/iceberg_db/iceberg_table/sub_dir');

-- With the parameter key unspecified:
ALTER TABLE iceberg.sales.order
EXECUTE remove_orphan_files('2024-01-01 00:00:00', 's3://bucket-test/iceberg_db/iceberg_table/sub_dir');

重写 Data Manifest

重写 Data Manifest 文件,并按分区合并,以避免过多小 Manifest 导致的性能下降。

此操作仅重写当前快照的 Data Manifest。

rewrite_manifests 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE rewrite_manifests()

示例

重写当前快照的 Data Manifest:

ALTER TABLE iceberg.sales.order
EXECUTE rewrite_manifests()

表管理

添加文件

从源表或特定位置向 Iceberg 表添加数据文件。此过程支持 Parquet 和 ORC 文件格式。

add_files 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE add_files(
    [source_table = '<source_table>' | location = '<location>', file_format = '<format>']
    [, recursive = <boolean>]
)

参数

必须提供 source_table 或 location,但不能同时提供两者。

source_table
  • 描述:从中添加文件的源表。格式:'catalog.database.table'。
  • 类型:String
  • 是否必须:否
location
  • 描述:从中添加文件的目录路径或文件路径。
  • 类型:String
  • 是否必需:否
file_format
  • 描述:数据文件的格式。支持 'parquet'、'orc' 格式。
  • 类型:String
  • 必填:否(当使用 location 时,该参数为必填。)
recursive
  • 描述:从某个位置添加文件时,是否递归扫描子目录。
  • 类型:Boolean
  • 默认值:true
  • 是否必须:否

示例

从源表添加文件:

ALTER TABLE iceberg.sales.order
EXECUTE add_files(source_table = 'hive_catalog.sales.source_order');

从特定位置添加 Parquet 格式的文件:

ALTER TABLE iceberg.sales.order
EXECUTE add_files(location = 's3://bucket/data/order/', file_format = 'parquet', recursive = true);

从单个文件添加文件:

ALTER TABLE iceberg.sales.order
EXECUTE add_files(location = 's3://bucket/data/order/data.parquet', file_format = 'parquet');

添加 Equality Delete 文件

将已有文件作为 Equality Delete 文件添加到 Iceberg 表。文件中的每一行会删除表中 Equality 列取值相同的行。这些文件在一个新快照中提交,因此会作用于表中已有的数据。此过程支持 Parquet 和 ORC 文件格式,要求 Iceberg 表的格式版本为 2 或更高。

文件发现方式与 add_files 相同。对于分区表,每个文件的分区取自其路径中的 <column>=<value> 目录,删除只作用于该分区的数据文件。如果文件路径中缺少任一分区列的目录,该文件会被拒绝。仅支持 Identity 分区转换。对于非分区表,删除作用于整张表。如果当前分区规范是分区的,而表中仍有按旧分区规范写入的数据文件,该过程会报错,因为删除不会作用于这些文件。如果会话变量 enable_read_iceberg_equality_delete_with_partition_evolution 被设置为 false(默认值:true),查询引擎不读取跨多个分区规范的 Equality Delete,因此当表中仍有按非当前分区规范写入的 Equality Delete 文件时,该过程同样会报错。如果文件中有任意一列带有 Iceberg 字段 ID,那么该文件的每个 Equality 列都必须带有与表一致的字段 ID,否则该文件会被拒绝。如果 Equality 列在文件中的类型无法无损地按表中该列的类型读取(例如表列为 INT,文件中为字符串列),该文件同样会被拒绝。不带字段 ID 的文件按列名与表匹配,因此添加文件后不要重命名其 Equality 列,否则删除将不再生效。此过程不支持 WHERE 子句。

add_equality_delete_files 语法

ALTER TABLE [catalog.][database.]table_name
EXECUTE add_equality_delete_files(
    location = '<location>',
    file_format = '<format>',
    equality_columns = '<column>[, <column> ...]'
    [, recursive = <boolean>]
)

参数

location
  • 描述:从中添加 Equality Delete 文件的目录路径或文件路径。
  • 类型:String
  • 是否必须:是
file_format
  • 描述:Equality Delete 文件的格式。支持 'parquet'、'orc' 格式。
  • 类型:String
  • 是否必须:是
equality_columns
  • 描述:删除时用于匹配的表列,多个列用逗号分隔。每一列都必须是类型为 INT、BIGINT、STRING 或 DATE 的顶层列,并且每个文件都必须包含所有这些列。
  • 类型:String
  • 是否必须:是
recursive
  • 描述:是否递归扫描 location 的子目录。
  • 类型:Boolean
  • 默认值:true
  • 是否必须:否

示例

删除 id 与 s3://bucket/deletes/order/ 下文件(例如 s3://bucket/deletes/order/dt=2024-01-01/delete.parquet)中某一行相同的行:

ALTER TABLE iceberg.sales.order
EXECUTE add_equality_delete_files(location = 's3://bucket/deletes/order/', file_format = 'parquet', equality_columns = 'id');

注册表

使用元数据文件注册 Iceberg 表。此过程允许您将现有的 Iceberg 表添加到 catalog 中,而无需迁移数据。

register_table 语法

CALL [catalog.]system.register_table(
    database_name = '<database_name>',
    table_name = '<table_name>',
    metadata_file = '<metadata_file_path>'
)

Parameters

database_name
  • 描述:要在其中注册表的数据库的名称。
  • 类型:String
  • 必需:是
table_name
  • 描述:要注册的表的名称。
  • 类型:String
  • 必填:是
metadata_file
  • 描述:Iceberg 表元数据文件的路径(例如,metadata.json)。
  • 类型:String
  • 必需:是

示例

使用元数据文件注册表:

CALL iceberg_catalog.system.register_table(
    database_name = 'sales',
    table_name = 'order',
    metadata_file = 's3://bucket/metadata/sales/order/metadata/00001-xxxxx-xxxxx-xxxxx.metadata.json'
);

或者使用当前的 catalog:

CALL system.register_table(
    database_name = 'sales',
    table_name = 'order',
    metadata_file = 's3://bucket/metadata/sales/order/metadata/00001-xxxxx-xxxxx-xxxxx.metadata.json'
);

本文来自 StarRocks 文档贡献者,按 Apache 2.0 整理版式与相对链接,保留正文与代码。图示请参阅原文。作者与贡献记录。

资料来源与适用范围

资料来源
StarRocks 文档贡献者
适用范围
main 文档快照(2026-11-16)
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-16
授权说明
Apache 2.0

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。