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。

访问控制要求

用于执行此 SQL 命令的 角色 必须至少具有以下 权限：

权限

对象

备注

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 每次操作最多可处理 1,000 个 Delta 提交文件。

    备注

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

  • 关于元数据：

    注意

    客户应确保在使用 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。

语言: 中文