ALTER ICEBERG TABLE ... REFRESH

刷新使用外部 Iceberg 目录的 Apache Iceberg™ 表 的元数据。刷新 Iceberg 表会将表元数据与最新的表变化同步。

本主题将 Iceberg 表简称为“表”（指定 Iceberg 表 的位置除外）以避免混淆。

另请参阅：

CREATE ICEBERG TABLE、DROP ICEBERG TABLE、SHOW ICEBERG TABLES、DESCRIBE ICEBERG TABLE

语法

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<metadata_file_relative_path>' ]
Copy

参数

table_name

要刷新的表的标识符。

如果标识符包含空格或特殊字符，则整个字符串必须放在双引号内。放在双引号内的标识符也区分大小写。

有关更多信息，请参阅 标识符要求。

'metadata_file_relative_path'

为从对象存储中的 Iceberg 文件创建的表指定元数据文件路径。路径必须与表关联的外部卷的 活动存储位置 相关。

下表显示了要根据示例存储位置指定的值：

表外部卷的活动存储位置

s3://mybucket_us_east_1

元数据文件的完整路径

s3://mybucket_us_east_1/metadata/v1.metadata.json

要指定为 :samp:`'{metadata_file_relative_path}'` 的值

:file:`metadata/v1.metadata.json`（不带前导正斜杠）

备注

  • 如果表使用 AWS Glue 作为目录，或者是从 Delta 表文件创建，则不要指定元数据文件路径。

  • 省略元数据文件路径中的前导正斜杠 (/)。

  • 在 Snowflake 版本 7.34 之前，需要一个名为 BASE_LOCATION 的参数（在以前的版本中也称为 FILE_PATH）才能使用对象存储中的 Iceberg 文件创建表。该参数指定了 EXTERNAL_VOLUME 位置的相对路径。

    要刷新使用旧语法创建的表，请指定相对于 BASE_LOCATION 的路径。例如，如果元数据文件的完整路径是 s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json，请将 metadata/v1.metadata.json 指定为 metadata-file-relative-path。

访问控制要求

用于执行此操作的 角色 必须至少具有以下 权限：

权限

对象

备注

OWNERSHIP

Iceberg 表

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

USAGE

外部卷

如果使用 系统提供的凭据，则不需要。

USAGE

目录集成

要对架构中的任何对象执行操作，需要对父数据库和架构具有 USAGE 权限。

有关创建具有指定权限集的自定义角色的说明，请参阅 创建自定义角色。

有关对 安全对象 执行 SQL 操作的相应角色和权限授予的一般信息，请参阅 访问控制概述。

使用说明

  • 只有表所有者（即对表具有 OWNERSHIP 权限的角色）或更高级别才能执行此命令。

  • 启用 自动刷新 后，您无法使用此命令手动刷新表元数据。要手动刷新表元数据，请先 关闭自动刷新。

  • 不支持在事务（隐式或显式）中使用 ALTER ICEBERG TABLE ... REFRESH 命令。

  • 每次您使用 CREATE/ALTER ...REFRESH。如果您的表有超过 1000 个提交文件，您可以进行额外的手动刷新。每次刷新过程都从上一次停止的地方继续进行。

    备注

    Snowflake 在创建 Iceberg 表时使用 Delta 检查点文件。1,000 个提交文件限制只适用于最近一次检查点之后的提交。

    刷新现有表时，Snowflake 会处理 Delta 提交文件，但不会处理检查点文件。如果表维护移除了源 Delta 表的陈旧日志和数据文件，则 Snowflake 中基于 Delta 的 Iceberg 表的刷新频率应高于 Delta 日志和数据文件的保留期。

  • 关于元数据：

    注意

    客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

示例

刷新表格

此示例在以下情况下手动刷新表的元数据：

  • 该表将 AWS Glue 用于 Iceberg 目录。

  • 该表基于对象存储中的 Delta 表文件。

对于上述情况，您不必在刷新命令中指定元数据文件路径。

ALTER ICEBERG TABLE myIcebergTable REFRESH;
Copy

刷新从对象存储中 Iceberg 文件创建的表

此示例根据新元数据文件中的更改手动刷新表元数据。在此示例中，元数据文件的完整路径为 <external-volume-storage-base-url>/path/to/metadata/v2.metadata.json。

指定元数据文件时，不必在元数据文件路径中包含前导正斜杠 (/)。

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'path/to/metadata/v2.metadata.json';
Copy

备注

在 Snowflake 版本 7.34 之前，需要一个名为 BASE_LOCATION 的参数（在以前的版本中也称为 FILE_PATH）才能使用对象存储中的 Iceberg 文件创建表。该参数指定了 EXTERNAL_VOLUME 位置的相对路径。

要刷新使用旧语法创建的表，请指定相对于 BASE_LOCATION 的路径。例如，如果元数据文件的完整路径是 s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json，请将 metadata/v1.metadata.json 指定为 metadata-file-relative-path。

语言: 中文