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 | tableColumnAction }

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> SET
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ CATALOG_SYNC = '<snowflake_open_catalog_integration_name>']
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

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

ALTER ICEBERG TABLE [ IF EXISTS ] dataGovnPolicyTagAction

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> searchOptimizationAction

Copy

其中：

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

Copy

tableColumnAction ::=
  {
     ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
        [ inlineConstraint ]
        [ COLLATE '<collation_specification>' ]

   | RENAME COLUMN <col_name> TO <new_col_name>

   | ALTER | MODIFY [ ( ]
                          , [ COLUMN ] <col1_name> { [ SET ] NOT NULL | DROP NOT NULL }
                          , [ COLUMN ] <col1_name> [ [ SET DATA ] TYPE ] <type>
                          , [ COLUMN ] <col1_name> COMMENT '<string>'
                          , [ COLUMN ] <col1_name> UNSET COMMENT
                        [ , [ COLUMN ] <col2_name> ... ]
                        [ , ... ]
                    [ ) ]

   | DROP [ COLUMN ] [ IF EXISTS ] <col1_name> [, <col2_name> ... ]
  }

  inlineConstraint ::=
    [ NOT NULL ]
    [ CONSTRAINT <constraint_name> ]
    { UNIQUE | PRIMARY KEY | { [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ] } }
    [ <constraint_properties> ]

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>
        [ ENTITY KEY ( <col_name> [, ... ] ) ]
        [ FORCE ]
    | UNSET AGGREGATION POLICY
  }
  |
  {
      SET JOIN POLICY <policy_name>
        [ FORCE ]
    | UNSET JOIN POLICY
  }
  |
  ADD [ COLUMN ] [ IF NOT EXISTS ] <col_name> <col_type>
    [ [ WITH ] MASKING POLICY <policy_name>
          [ USING ( <col1_name> , <cond_col_1> , ... ) ] ]
    [ [ WITH ] PROJECTION POLICY <policy_name> ]
    [ [ WITH ] TAG ( <tag_name> = '<tag_value>'
          [ , <tag_name> = '<tag_value>' , ... ] ) ]
  |
  {
    { 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

searchOptimizationAction ::=
  {
     ADD SEARCH OPTIMIZATION [
       ON <search_method_with_target> [ , <search_method_with_target> ... ]
     ]

   | DROP SEARCH OPTIMIZATION [
       ON { <search_method_with_target> | <column_name> | <expression_id> }
          [ , ... ]
     ]
  }

Copy

有关详细信息，请参阅搜索优化操作 (searchOptimizationAction)。

参数¶

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 管理的 Iceberg 表与 Open Catalog 同步的详细信息，请参阅将 Snowflake 管理的表与 Snowflake Open Catalog 同步。

有关此参数的详细信息，请参阅 CATALOG_SYNC。

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 目录以获取元数据更新。

对于基于 Delta 的表，Snowflake 会轮询外部云存储以获取更新。

如果没有为目录集成上的 REFRESH_INTERVAL_SECONDS 参数指定值，则 Snowflake 将使用 30 秒作为默认刷新间隔。

默认：FALSE

CONTACT ( purpose = contact [ , purpose = contact ... ] ): 预览版功能 – 开放

适用于所有账户。

将现有对象与一个或多个联系人关联起来。

UNSET

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

REPLACE_INVALID_CHARACTERS

CATALOG_SYNC

CONTACT purpose

群集操作 (`clusteringAction`)¶

备注

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

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

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

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

SUSPEND | RESUME RECLUSTER

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

DROP CLUSTERING KEY

删除表的群集密钥。

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

表列操作 (`tableColumnAction`)¶

ADD [ COLUMN ] [ IF NOT EXISTS ] col_name col_data_type . [ inlineConstraint ] [ COLLATE 'collation_specification' ] [ , ... ]

添加新列。您可以指定内联约束条件或排序规则规范。

有关表列操作的更多详细信息，请参阅：

您可以在同一个命令中对多列执行 ADD COLUMN 操作。

如果不确定该列是否已存在，可以在添加该列时指定 IF NOT EXISTS。如果该列已存在，则 ADD COLUMN 对现有列没有影响，并且不会导致错误。

备注

如果您还为新列指定了以下内容，则不能指定 IF NOT EXISTS：

AUTOINCREMENT 或 IDENTITY
UNIQUE、PRIMARY KEY 或 FOREIGN KEY

RENAME COLUMN col_name to new_col_name

将指定列重命名为表中其他列当前未使用的新名称。

不能重命名属于群集密钥的列。

重命名对象（表、列等）时，必须使用新名称更新引用该对象的其他对象。

DROP COLUMN [ IF EXISTS ] col_name [ CASCADE | RESTRICT ]

从表中移除指定列。

如果不确定该列是否已存在，可以在删除该列时指定 IF EXISTS。如果该列不存在，则 DROP COLUMN 不起作用，也不会导致错误。

删除列是一种只适用于元数据的操作。它不会立即重写微分区，因此不会立即释放列所使用的空间。通常情况下，下一次重新写入微分区时，单个微分区中的空间将被释放，这通常是由于 DML （INSERT、 UPDATE、 DELETE）或重聚类而完成写入时发生的情况。

数据治理策略和标签操作 (`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
从表中分离聚合策略。

SET JOIN POLICY policy_name

[ FORCE ]
为表分配联接策略。

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

UNSET JOIN POLICY
从表中分离联接策略。

{ ALTER | MODIFY } [ COLUMN ] ...

USING ( col_name , cond_col_1 ... )

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

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

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

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

FORCE

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

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

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

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

搜索优化操作 (`searchOptimizationAction`)¶

ADD SEARCH OPTIMIZATION

为整个表添加搜索优化，如果指定了可选 ON 子句，则为特定列添加。

备注

搜索优化的维护成本可能很高，尤其是在表中的数据频繁更改的情况下。有关更多信息，请参阅搜索优化成本估算和管理。

ON search_method_with_target [, search_method_with_target ... ]

指定要为特定列（而不是整个表）配置搜索优化。

对于 search_method_with_target，请使用具有以下语法的表达式：

<search_method>( <target> [ , <target> , ... ] [ , ANALYZER => '<analyzer_name>' ] )

Copy

其中：

search_method 指定下列方法之一，用于优化特定类型的谓词的查询：

搜索方式	描述
`FULL_TEXT`	使用 VARCHAR (text) 类型的谓词。
`EQUALITY`	等式和 IN 谓词。
`SUBSTRING`	匹配子字符串和正则表达式的谓词（例如 [ NOT ] LIKE、[ NOT ] ILIKE、[ NOT ] RLIKE 和 REGEXP_LIKE）。

target 指定列或星号 (*)。

根据 search_method 的值，可以指定以下类型之一的列或：

搜索方式

支持的目标

FULL_TEXT

VARCHAR (text) 数据类型的列。

EQUALITY

数字、字符串和二进制数据类型的列。

SUBSTRING

VARCHAR (text) 数据类型的列。

要将表中所有适用的列指定为目标，请使用星号 (*)。

请注意，不能为给定的搜索方法同时指定星号和特定列名。但是，您可以在不同的搜索方法中指定星号。

例如，您可以指定以下表达式：
```
-- Allowed
ON SUBSTRING(*)
ON EQUALITY(*), SUBSTRING(*)
```
Copy
不能指定以下表达式：
```
-- Not allowed
ON EQUALITY(*, c1)
ON EQUALITY(c1, *)
ON EQUALITY(v1:path, *)
ON EQUALITY(c1), EQUALITY(*)
```
Copy

搜索方式	支持的目标
`FULL_TEXT`	VARCHAR (text) 数据类型的列。
`EQUALITY`	数字、字符串和二进制数据类型的列。
`SUBSTRING`	VARCHAR (text) 数据类型的列。

如果 search_method 是 FULL_TEXT，则 ANALYZER => 'analyzer_name' 指定文本分析器的名称。

有关搜索优化分析器的更多信息，请参阅 ALTER TABLE。

若要在目标上指定多个搜索方法，请使用逗号分隔每个后续方法和目标：

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1), EQUALITY(c2, c3);

Copy

如果运行 ALTER ICEBERG TABLE ... ADD SEARCH OPTIMIZATION ON ... 命令，则每个后续命令都会添加到表的现有配置中。例如，假设您运行以下命令：

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2);
ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c3, c4);

Copy

这会将 c1、c2、c3 和 c4 列的相等谓词添加到表的配置中。这相当于运行以下命令：

ALTER ICEBERG TABLE t1 ADD SEARCH OPTIMIZATION ON EQUALITY(c1, c2, c3, c4);

Copy

有关示例，请参阅为特定列启用搜索优化。

DROP SEARCH OPTIMIZATION

移除整个表的搜索优化，或者如果指定了可选 ON 子句，则从特定列中移除。

备注

如果表具有搜索优化属性，则删除该表并取消删除它将保留搜索优化属性。
从表中移除搜索优化属性然后重新添加它时，会产生与首次添加搜索优化属性时相同的成本。

ON search_method_with_target | column_name | expression_id [ , ... ]

指定要为特定列（而不是删除整个表的搜索优化）删除搜索优化配置。

若要标识要删除的列配置，请指定以下配置之一：

对于 search_method_with_target，指定一种方法来优化一个或多个特定列的查询。使用前面描述的语法。
对于 column_name，指定为搜索优化配置的列的名称。指定列名称删除该列的所有表达式。
对于 expression_id，指定 DESCRIBE SEARCH OPTIMIZATION 命令的输出中列出的表达式 ID。

若要指定其中的多个项，请在项之间使用逗号分隔。

可以指定具有目标、列名和表达式 IDs 的搜索方法的任意组合。

有关示例，请参阅删除特定列的搜索优化。

访问控制要求¶

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

权限	对象	备注
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 表使用数据指标函数。有关更多信息，请参阅使用数据指标函数执行数据质量检查。
有关在 Iceberg Tables 中使用搜索优化的更多信息，包括限制，请参阅搜索优化文档中的支持 Apache 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 my_iceberg_table SET AUTO_REFRESH = TRUE;

Copy

以下示例为 Iceberg 表添加和删除搜索优化：

ALTER ICEBERG TABLE my_iceberg_table ADD SEARCH OPTIMIZATION ON SUBSTRING(C6);

ALTER ICEBERG TABLE my_iceberg_table DROP SEARCH OPTIMIZATION ON EQUALITY(C7, C8);

Copy

ALTER ICEBERG TABLE¶

语法¶

参数¶

群集操作 (clusteringAction)¶

表列操作 (tableColumnAction)¶

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

搜索优化操作 (searchOptimizationAction)¶

访问控制要求¶

使用说明¶

示例¶

群集操作 (`clusteringAction`)¶

表列操作 (`tableColumnAction`)¶

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

搜索优化操作 (`searchOptimizationAction`)¶