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 示例。

访问控制要求

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

权限

对象

备注

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 权限。请注意，如果某个角色获授某个架构的任意权限，该角色便能够解析该架构。例如，若某角色被授予 CREATE 权限，则可以在该架构上创建对象，而无需 同时 被授予该架构的 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
语言: 中文