使用 Iceberg Catalog 进行时间旅行
本文介绍 StarRocks 针对 Iceberg catalog 的时间旅行 (Time Travel) 功能。该功能自 v3.4.0 版本起支持。
概述
每个 Iceberg 表都维护一个元数据快照日志，该日志表示应用于表的更改。数据库可以通过访问这些历史快照对 Iceberg 表执行时间旅行查询。 Iceberg 支持分支和标记快照，以进行复杂的快照生命周期管理，允许每个分支或标记基于自定义保留策略维护其自己的生命周期。有关 Iceberg 的分支和标记功能的更多信息，请参见 官方文档。
通过集成 Iceberg 的快照分支和标记功能，StarRocks 支持在 Iceberg catalogs 中创建和管理分支及标记，以及对表执行时间旅行查询。
管理分支、标记和快照
创建分支
语法
ALTER TABLE [catalog.][database.]table_name
CREATE [OR REPLACE] BRANCH [IF NOT EXISTS] <branch_name>
[AS OF VERSION <snapshot_id>]
[RETAIN <int> { DAYS | HOURS | MINUTES }]
[WITH SNAPSHOT RETENTION
{ minSnapshotsToKeep | maxSnapshotAge | minSnapshotsToKeep maxSnapshotAge }]
minSnapshotsToKeep ::= <int> SNAPSHOTS
maxSnapshotAge ::= <int> { DAYS | HOURS | MINUTES }
参数
branch_name：要创建的分支的名称。AS OF VERSION：在其上创建分支的快照（版本）的 ID。RETAIN：保留分支的时间。格式：<int> <unit>。支持的单位：DAYS、HOURS和MINUTES。示例：7 DAYS、12 HOURS或30 MINUTES。WITH SNAPSHOT RETENTION：要保留的最小快照数和/或要保留快照的最长时间。
示例
基于表 iceberg.sales.order 的版本（快照 ID）12345 创建一个分支 test-branch，将该分支保留 7 天，并在该分支上至少保留 2 个快照。
ALTER TABLE iceberg.sales.order CREATE BRANCH `test-branch`
AS OF VERSION 12345
RETAIN 7 DAYS
WITH SNAPSHOT RETENTION 2 SNAPSHOTS;
基于表 iceberg.sales.order 的版本（快照 ID）12345 创建一个分支 test-branch2，将该分支保留 7 天，并将该分支上的快照最多保留 2 天。
ALTER TABLE iceberg.sales.order CREATE BRANCH `test-branch2`
AS OF VERSION 12345
RETAIN 7 DAYS
WITH SNAPSHOT RETENTION 2 DAYS;
基于表 iceberg.sales.order 的版本（快照 ID）12345 创建一个分支 test-branch3，将该分支保留 7 天，并在该分支上至少保留 2 个快照，每个快照最多保留 2 天。
ALTER TABLE iceberg.sales.order CREATE BRANCH `test-branch3`
AS OF VERSION 12345
RETAIN 7 DAYS
WITH SNAPSHOT RETENTION 2 SNAPSHOTS 2 DAYS;
将数据加载到表的特定分支中
语法
INSERT INTO [catalog.][database.]table_name
[FOR] VERSION AS OF <branch_name>
<query_statement>
参数
branch_name：要加载数据的表分支的名称。query_statement：查询语句，其结果将加载到目标表中。 它可以是 StarRocks 支持的任何 SQL 语句。
示例
将查询结果加载到表 iceberg.sales.order 的分支 test-branch 中。
INSERT INTO iceberg.sales.order
FOR VERSION AS OF `test-branch`
SELECT c1, k1 FROM tbl;
创建标记
语法
ALTER TABLE [catalog.][database.]table_name
CREATE [OR REPLACE] TAG [IF NOT EXISTS] <tag_name>
[AS OF VERSION <snapshot_id>]
[RETAIN <int> { DAYS | HOURS | MINUTES }]
参数
tag_name：要创建的标记的名称。AS OF VERSION：在其上创建标记的快照（版本）的 ID。RETAIN：保留标记的时间。格式：<int> <unit>。支持的单位：DAYS、HOURS和MINUTES。示例：7 DAYS、12 HOURS或30 MINUTES。
示例
基于表 iceberg.sales.order 的版本（快照 ID）12345 创建一个标记 test-tag，并将该标记保留 7 天。
ALTER TABLE iceberg.sales.order CREATE TAG `test-tag`
AS OF VERSION 12345
RETAIN 7 DAYS;
将分支快进到另一个分支
语法
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');
选择快照
您可以选择一个特定的快照并将其应用于表的当前状态。 此操作将基于现有快照创建一个新快照，并且原始快照不会受到影响。
语法
ALTER TABLE [catalog.][database.]table_name
EXECUTE cherrypick_snapshot(<snapshot_id>)
参数
snapshot_id：要选择的快照的 ID。
示例
ALTER TABLE iceberg.sales.order
EXECUTE cherrypick_snapshot(54321);
过期快照
您可以使早于特定时间点的快照过期。此操作将删除已过期快照的数据文件。
语法
ALTER TABLE [catalog.][database.]table_name
EXECUTE expire_snapshot('<datetime>')
示例
ALTER TABLE iceberg.sales.order
EXECUTE expire_snapshot('2023-12-17 00:14:38')
删除分支或标记
语法
ALTER TABLE [catalog.][database.]table_name
DROP { BRANCH <branch_name> | TAG <tag_name> }
示例
ALTER TABLE iceberg.sales.order
DROP BRANCH `test-branch`;
ALTER TABLE iceberg.sales.order
DROP TAG `test-tag`;
使用时间旅行查询
时间旅行到特定分支或标记
语法
[FOR] VERSION AS OF '<branch_or_tag>'
参数
tag_or_branch：要时间旅行到的分支或标记的名称。 如果指定了分支名称，则查询将时间旅行到分支的头部快照。 如果指定了标记名称，则查询将时间旅行到标记引用的快照。
示例
-- Time Travel to the head snapshot of a branch.
SELECT * FROM iceberg.sales.order VERSION AS OF 'test-branch';
-- Time Travel to the snapshot that the tag referenced.
SELECT * FROM iceberg.sales.order VERSION AS OF 'test-tag';
时间旅行到特定快照
语法
[FOR] VERSION AS OF '<snapshot_id>'
参数
snapshot_id：要时间旅行到的快照的 ID。
示例
SELECT * FROM iceberg.sales.order VERSION AS OF 12345;
时间旅行到特定的日期时间或日期
语法
[FOR] TIMESTAMP AS OF { '<datetime>' | '<date>' | date_and_time_function }
参数
date_and_time_function：StarRocks 支持的任何日期和时间函数。
示例
SELECT * FROM iceberg.sales.order TIMESTAMP AS OF '1986-10-26 01:21:00';
SELECT * FROM iceberg.sales.order TIMESTAMP AS OF '1986-10-26';
SELECT * FROM iceberg.sales.order TIMESTAMP AS OF now();