ALTER ICEBERG TABLE¶

修改现有 Apache Iceberg™ 表的属性，例如群集选项和标签。

您还可以使用 ALTER ICEBERG TABLE 语句来刷新表、转换表或更改结构化类型列。这些操作的语法差别很大。要查看刷新或转换 Iceberg 表的相关语法、参数描述、使用说明和示例，请参阅以下页面：

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

另请参阅：: CREATE ICEBERG TABLE、DROP ICEBERG TABLE、SHOW ICEBERG TABLES、DESCRIBE ICEBERG TABLE

语法¶

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> UNSET REPLACE_INVALID_CHARACTERS

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

Copy

其中：

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }

Copy

dataGovnPolicyTagAction ::=
  {
      SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
    | UNSET TAG <tag_name> [ , <tag_name> ... ]
  }
  |
  {
      ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ROW ACCESS POLICY <policy_name>
    | DROP ROW ACCESS POLICY <policy_name> ,
        ADD ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , ... ] )
    | DROP ALL ROW ACCESS POLICIES
  }
  |
  {
      SET AGGREGATION POLICY <policy_name> [ FORCE ]
      | UNSET AGGREGATION POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] [ FORCE ]
      | UNSET MASKING POLICY
  }
  |
  {
    { ALTER | MODIFY } [ COLUMN ] <col1_name>
        SET PROJECTION POLICY <policy_name>
          [ FORCE ]
      | UNSET PROJECTION POLICY
  }
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> SET TAG
      <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
      , [ COLUMN ] <col2_name> SET TAG
          <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]
  |
  { ALTER | MODIFY } [ COLUMN ] <col1_name> UNSET TAG <tag_name> [ , <tag_name> ... ]
                  , [ COLUMN ] <col2_name> UNSET TAG <tag_name> [ , <tag_name> ... ]

Copy

参数¶

table_name

要修改的表的标识符。

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

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

SET ...

指定要为外部表设置的一个或多个属性/参数（用空格、逗号或换行符分隔）：

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

指定在查询结果中是否使用 Unicode 替换字符 (�) 替换无效的 UTF-8 字符。您只能为使用外部 Tables 目录的表设置此参数。

TRUE 会将无效的 UTF-8 字符替换为 Unicode 替换字符。
FALSE 保留无效的 UTF-8 字符不变。如果在 Parquet 数据文件中遇到无效的 UTF-8 字符，Snowflake 会返回用户错误消息。

如果未指定，则 Iceberg 表将默认使用架构、数据库或账户的参数值。架构优先于数据库，数据库优先于账户。

默认：FALSE

CATALOG_SYNC = 'snowflake_open_catalog_integration_name': 指定为 Snowflake Open Catalog 配置的目录集成的名称。Snowflake 会将表与 Snowflake Open Catalog 账户中的外部目录同步。有关更多信息，请参阅将 Snowflake 管理的表与 Snowflake Open Catalog 同步。

DATA_RETENTION_TIME_IN_DAYS = integer

指定由 Snowflake 管理的表的保留期，以便可以对表中的历史数据执行 Time Travel 操作（SELECT、CLONE、UNDROP）。有关更多信息，请参阅了解和使用 Time Travel。

有关此对象级参数的详细说明以及有关对象参数的详细信息，请参阅参数。

值：

Standard Edition：0 或 1

Enterprise Edition：0 至 90 用于永久表

默认：

Standard Edition：1

Enterprise Edition（或更高版本）：1 （除非在架构、数据库或账户级别指定了不同的默认值）

备注

0 值实际上会为表禁用 Time Travel。

AUTO_REFRESH = { TRUE | FALSE }

指定在使用自动刷新时，Snowflake 是否应自动轮询与表关联的外部 Iceberg 目录以获取元数据更新。如果没有为目录集成上的 REFRESH_INTERVAL_SECONDS 参数指定值，则 Snowflake 将使用 30 秒作为默认刷新间隔。

默认：FALSE

UNSET

目前，您只能使用此命令取消设置以下参数：

REPLACE_INVALID_CHARACTERS

群集操作 (`clusteringAction`)¶

备注

只有使用 Snowflake 作为 Iceberg 目录的表才支持群集。

CLUSTER BY ( expr [ , expr , ... ] )

指定（或修改）一个或多个表列或列表达式作为表的群集密钥。这些是自动聚类维护群集的列/表达式。

要了解有关群集的更多信息，请参阅群集密钥和聚类表。

SUSPEND | RESUME RECLUSTER

启用或禁用表的自动聚类。

DROP CLUSTERING KEY

删除表的群集密钥。

有关群集密钥和重聚类的更多信息，请参阅了解 Snowflake 表结构。

数据治理策略和标签操作 (`dataGovnPolicyTagAction`)¶

TAG tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ]

指定标签名称和标签字符串值。

标签值始终为字符串，标签值的最大字符数为 256。

有关在语句中指定标签的信息，请参阅对象和列的标签配额。

policy_name: 策略的标识符；对于架构必须是唯一的。

以下子句适用于支持行访问策略的所有表类型，包括但不限于表、视图和事件表。简而言之，这些子句仅指“表”。

ADD ROW ACCESS POLICY policy_name ON (col_name [ , ... ])
向表中添加行访问策略。

必须至少指定一个列名称。可以使用逗号分隔每个列名称来指定其他列。使用此表达式可以向事件表和外部表添加行访问策略。

DROP ROW ACCESS POLICY policy_name
从表中删除行访问策略。

使用此子句将策略从表中删除。

DROP ROW ACCESS POLICY policy_name, ADD ROW ACCESS POLICY policy_name ON ( col_name [ , ... ] )
在单个 SQL 语句中，删除在表上设置的行访问策略，并向同一个表添加行访问策略。

DROP ALL ROW ACCESS POLICIES
从表中删除所有行访问策略关联。

在从事件表中删除策略之前，从架构中删除行访问策略时，此表达式非常有用。使用此表达式从表中删除行访问策略关联。

SET AGGREGATION POLICY policy_name

[ ENTITY KEY (col_name [ , ... ]) ] [ FORCE ]
为该表分配聚合策略。

使用可选的 ENTITY KEY 参数来定义表中哪些列可以唯一地标识实体。有关更多信息，请参阅通过聚合策略实施实体级隐私。

使用可选 FORCE 参数以原子方式将现有聚合策略替换为新的聚合策略。

UNSET AGGREGATION POLICY
从表中分离聚合策略。

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

指定要传递到条件掩码策略 SQL 表达式的实参。

列表中的第一列指定用于掩码处理或标记数据的策略条件的列，并且必须与设置掩码策略的列匹配。

附加列指定要评估的列，以确定在对第一列进行查询时是否对查询结果的每行中的数据进行掩码处理或标记化。

如果省略 USING 子句，Snowflake 会将条件掩码策略视为正常的掩码策略。

FORCE

在单个语句中将当前为列设置的掩码或投影策略替换为其他策略。

请注意，将 FORCE 关键字与掩码策略配合使用要求 ALTER TABLE 语句中策略的 :doc:` 数据类型 </sql-reference-data-types>`（即 STRING）与当前在该列上设置的掩码策略的数据类型（即 STRING）相匹配。

如果当前没有为该列设置掩码策略，则指定此关键字无效。

有关详细信息，请参阅：替换列上的掩码策略或替换投影策略。

访问控制要求¶

用于执行此 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 权限的角色）或更高级别才能执行此命令。
只有使用 Snowflake 作为 Iceberg 目录的表才支持群集。要向 Iceberg 表添加群集，您还必须对包含该表的架构和数据库拥有 USAGE 或 OWNERSHIP 权限。
您可以通过执行 ALTER TABLE 命令来对 Iceberg 表使用数据指标函数。有关更多信息，请参阅使用数据指标函数。
关于元数据：

注意

客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。
要对更改 CATALOG_SYNC 参数相关问题进行故障排除，请参阅您无法在指定 CATALOG_SYNC 参数时更改 Iceberg 表

示例¶

以下示例在 Iceberg 表上设置了一个值为 customer 的标签 (my_tag)。

ALTER ICEBERG TABLE my_iceberg_table SET TAG my_tag = 'customer';

Copy

ALTER ICEBERG TABLE¶

语法¶

参数¶

群集操作 (clusteringAction)¶

数据治理策略和标签操作 (dataGovnPolicyTagAction)¶

访问控制要求¶

使用说明¶

示例¶

群集操作 (`clusteringAction`)¶

数据治理策略和标签操作 (`dataGovnPolicyTagAction`)¶