ALTER ICEBERG TABLE ...ALTER COLUMN ...SET DATA TYPE¶

备注

使用外部目录的 Iceberg 表不支持该语法变体。

修改（演化）Snowflake 管理的 Apache Iceberg™ 表中的结构化类型列。

使用此命令，可以修改 Iceberg 表列中的结构类型。您可以重新命名结构化 OBJECT 中的键，也可以执行以下更改的组合：

在结构化类型中演变字段的类型。
对结构化 OBJECT 中的键重新排序。
将键添加到结构化 OBJECT。
从结构化 OBJECT 中删除键。

不能将键的重命名与任何其他修改相结合。

为简洁起见，除非需要区分 Iceberg 表和常规的 Snowflake 表，本主题将 Iceberg 表简称为“表”。

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

语法¶

修改结构类型列

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> ALTER COLUMN <structured_column>
  SET DATA TYPE <new_structured_type>

Copy

重新命名结构化 OBJECT 中的键

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> ALTER COLUMN <structured_column>
  SET DATA TYPE <new_structured_type>
  RENAME FIELDS

Copy

参数¶

table_name

要修改的表的标识符。

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

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

ALTER COLUMN structured_column

指定要修改的结构化类型列。

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

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

SET DATA TYPE new_structured_type

列使用的新结构类型的完整规范。例如，要指定由 NUMBER 元素组成的结构化 ARRAY，请使用 ARRAY(NUMBER)。

有关更多信息，请参阅指定结构化类型和本页的示例。

RENAME FIELDS

指定命令对结构化 OBJECT 中的一个或多个键重命名。新旧键只能在名称上有所不同，且必须具有完全相同的层次结构和数据类型。重新命名键不会更改字段 IDs。

重命名键不能与 Iceberg 表中结构类型的任何其他修改结合使用。

请参阅 RENAME FIELDS 示例。

访问控制要求¶

用于执行此 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 权限。

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

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

使用说明¶

此命令不支持以下操作：
- 将结构化类型演变为非结构化类型（或反之操作）。
- 在结构化 ARRAY 元素或结构化 MAP 的键值对上设置空约束。
- 使用 RENAME FIELDS 重命名属于表中群集密钥的键。
- 改变结构化 OBJECT 的 NULL 约束。
对于使用数据访问策略的表，请确保列的新数据类型与数据访问策略的实参类型兼容。否则，查询该表可能会失败。例如，如果在结构化 OBJECT 列中添加键，则必须更改策略或创建新策略并将其应用到表中。
关于元数据：

注意

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

示例¶

不断演变的类型¶

您可以在结构化类型中演变字段的类型。演变该类型意味着将其扩展为更大的、相关的 Iceberg 数据类型。

根据 Apache Iceberg 规范 (https://iceberg.apache.org/spec/#schema-evolution)，Snowflake 支持以下类型演化：

将 int 类型的字段改为 long 类型。
将 float 类型的字段改为 double 类型。
将 decimal(p,s) 类型的字段改为 decimal(p',s) 类型，其中 p 小于 p'。

要演化字段类型，请使用指定结构化类型的 Snowflake 语法。您可以在规范中使用 Iceberg 数据类型。例如，以下语句将结构化 ARRAY 列中的元素类型更改为（Iceberg）类型 long。

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN col1
  SET DATA TYPE ARRAY(long);

Copy

有关 Iceberg 数据类型如何映射到 Snowflake 数据类型的信息，请参阅 Apache Iceberg™ 表的数据类型。

重新排列键的顺序¶

要重新排列结构化 OBJECT 中键的顺序，请在 ALTER ICEBERG TABLE 语句中指定新的顺序。重新排列键的顺序不会影响 OBJECT 中的数据。

例如，请考虑以下 CREATE ICEBERG TABLE 语句。表中有一列 (column_1)，类型为 OBJECT，其中包含按指定顺序排列的两个键：

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_a int,
      key_b int
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

下面的命令更改了键的顺序，使得 key_b 在 key_a 之前：

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    key_b int,
    key_a int
  );

Copy

添加键¶

您可以向结构化 OBJECT 中添加键。新键的值可以使用任何 Iceberg 表支持的数据类型。

备注

添加键时不能设置空约束，因为 Snowflake 会将表中所有现有行的键值设置为 NULL。

例如，请考虑以下 CREATE ICEBERG TABLE 语句。表有一列 (column_1)，类型为 OBJECT，有一个键 (key_1)：

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_1 int
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

以下命令将名为 key_2 的键添加到 column_1 中：

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    key_1 int,
    key_2 int
  );

Copy

删除键¶

备注

不支持删除其值为属于群集密钥的结构化数据类型的键。

要从结构化 OBJECT 中删除键，请使用 ALTER ICEBERG TABLE...ALTER COLUMN 命令来重新定义 OBJECT。

删除键会移除表中所有行的键及其值。

例如，请考虑以下 CREATE ICEBERG TABLE 语句。表有一列 (column_1)，类型为 OBJECT，有两个键：

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_1 int,
      key_2 ARRAY(string)
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

以下命令从 OBJECT 规范中省略了名为 key_2 的键，从而将其删除：

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    key_1 int
  );

Copy

对键重命名¶

要更改结构化 OBJECT 中的键名称，请使用 RENAME FIELDS 关键字。

例如，请考虑以下 CREATE ICEBERG TABLE 语句：

CREATE ICEBERG TABLE my_iceberg_table (
  column_1 OBJECT(
      key_1 int,
      key_2 int
    )
  )
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = '';

Copy

以下命令使用 RENAME FIELDS 对 column_1 中的键重命名：

ALTER ICEBERG TABLE my_iceberg_table ALTER COLUMN column_1
  SET DATA TYPE OBJECT(
    k_1 int,
    k_2 int
  )
  RENAME FIELDS;

Copy