自动刷新 Apache Iceberg™ 表¶
为新的或现有的外部管理 Apache Iceberg™ 表 配置自动元数据刷新。通过自动刷新,Snowflake 以连续和无服务器形式轮询您的外部 Iceberg 目录,以将元数据与最新的远程变更同步。
使用以下外部目录选项的表支持自动刷新:
AWS Glue
符合 Apache Iceberg REST OpenAPI 规范的 REST 目录
Snowflake Open Catalog
设置目录集成的刷新间隔¶
运行 CREATE CATALOG INTEGRATION 命令时,可以为 REFRESH_INTERVAL_SECONDS
参数指定值。否则,默认刷新间隔为 30 秒。Snowflake 只在目录集成定义了 Iceberg 表的情况下轮询外部目录。
以下示例为 AWS Glue 创建目录集成,并指定 60 秒的刷新间隔:
CREATE CATALOG INTEGRATION auto_refresh_catalog_integration
CATALOG_SOURCE = GLUE
CATALOG_NAMESPACE = 'my_catalog_namespace'
TABLE_FORMAT = ICEBERG
GLUE_AWS_ROLE_ARN = 'arn:aws:iam::123456789123:role/my-catalog-role'
GLUE_CATALOG_ID = '123456789123'
ENABLED = TRUE
REFRESH_INTERVAL_SECONDS = 60;
要更新目录集成的刷新间隔,请使用 ALTER CATALOG INTEGRATION 命令。
例如:
ALTER CATALOG INTEGRATION auto_refresh_catalog_integration SET REFRESH_INTERVAL_SECONDS = 120;
创建一个自动刷新的 Iceberg 表¶
使用 CREATE ICEBERG TABLE 命令创建 Iceberg 表。要指定表应使用自动元数据刷新,请设置 AUTO_REFRESH = TRUE
。
下面的示例创建一个使用 AWS Glue 作为目录的 Iceberg 表,指定前面创建的目录集成 (auto_refresh_catalog_integration
) 和来自 AWS Glue 的 CATALOG_TABLE_NAME。
CREATE OR REPLACE ICEBERG TABLE auto_refresh_iceberg_table
CATALOG_TABLE_NAME = 'myGlueTable'
CATALOG = 'auto_refresh_catalog_integration'
AUTO_REFRESH = TRUE;
启用或关闭自动刷新¶
备注
如果表使用 Snowflake 8.22 版之前创建的目录集成,则必须先使用 ALTER CATALOG INTEGRATION 命令设置
REFRESH_INTERVAL_SECONDS
参数,然后再对表启用自动刷新。频繁地打开和关闭 Iceberg 表的自动刷新会降低表的元数据刷新速度。
使用 ALTER ICEBERG TABLE 命令启用或关闭现有 Iceberg 表的自动刷新。
例如:
ALTER ICEBERG TABLE my_iceberg_table SET AUTO_REFRESH = FALSE;
检查自动刷新状态¶
要检索表的自动刷新状态,请调用 SYSTEM$AUTO_REFRESH_STATUS 函数。
SELECT SYSTEM$AUTO_REFRESH_STATUS('my_iceberg_table');
该函数返回 Snowflake 用于自动刷新表的管道的详细信息,例如快照队列的执行状态和大小。RUNNING
的执行状态指示自动刷新正在按预期运行。有关更多信息,请参阅 SYSTEM$AUTO_REFRESH_STATUS。
错误恢复¶
当自动刷新过程中发生错误时,Snowflake会将执行状态更新为以下值之一:
STALLED
表示Snowflake正在尝试从错误中恢复。如果恢复成功,自动刷新进程将继续按预期运行,执行状态将转换回正常的RUNNING
状态。STOPPED
表示自动刷新进程遇到了不可恢复的错误,并且表的自动刷新已停止。例如,当 Snowflake 无法在目标快照和当前快照之间建立直接沿袭时,可能会发生不可恢复的错误。
要从
STOPPED
状态恢复,请执行以下操作:执行手动元数据刷新。有关说明,请参阅 刷新表元数据。
使用 ALTER ICEBERGTABLE 重新启用自动刷新...SET AUTO_REFRESH 语句重命名数据库角色。
通过调用
RUNNING
函数验证自动刷新是否处于 SYSTEM$AUTO_REFRESH_STATUS 状态。您还可以多次调用该函数,以确认排队快照的数量 (pendingSnapshotCount
) 逐渐减少。
计费¶
Snowflake 使用 Snowpipe 自动刷新 Iceberg 表,因此自动刷新的费用 与Snowpipe 费用出现在您账单上的同一行项目中。此功能不收取 Snowpipe 文件费用。
您可以通过检查账户使用情况 PIPE_USAGE_HISTORY 视图 来估计所产生的费用。自动刷新管道列在 NULL 管道名称下。
有关 Iceberg 表收费的更多信息,请参阅 Iceberg 表计费。
注意事项和限制¶
当您使用利用自动刷新的 Iceberg 表时,请考虑以下事项:
启用自动刷新后,您无法手动刷新表元数据。要执行手动刷新,请先 关闭自动刷新。
对于在 Snowflake 8.22 版之前创建的目录集成,必须先手动设置
REFRESH_INTERVAL_SECONDS
参数,然后才能对依赖于该目录集成的表启用自动刷新。有关说明,请参阅 ALTER CATALOG INTEGRATION ...。确保新表快照是当前表快照的直接子级。否则,自动刷新将进入
STOPPED
状态。要在发生这种情况时恢复自动刷新,请参阅 错误恢复。如果您的表为空,请在启用自动刷新 之前 执行手动刷新,以避免未定义的行为。
当您将 目录集成用于对象存储 时,不支持自动刷新。
目前不支持没有序列号列的 Iceberg 版本 1 清单。