Apache Iceberg™ 表：对 Apache Iceberg™ v3 的支持（预览版）¶

数据类型¶

公共预览版支持以下 v3 数据类型：

• geography

• geometry

• nanosecond

• variant

有关更多信息，请参阅 Iceberg v3 数据类型。

默认值¶

请参阅 默认值。

删除向量¶

请参阅 删除向量。

行沿袭¶

请参阅 行沿袭。

使用说明¶

• 要修改账户级别的 ICEBERG_VERSION_DEFAULT 参数，您必须是账户管理员；也就是说，您必须是具有 ACCOUNTADMIN 角色的用户。

• 要修改数据库或架构级别的 ICEBERG_VERSION_DEFAULT 参数，用于执行此操作的角色必须具有相应数据库或架构的 OWNERSHIP 权限。

示例¶

指定在 my_db 数据库中创建新的 Iceberg 表应使用 v3：

ALTER DATABASE my_db SET ICEBERG_VERSION_DEFAULT=3;

使用 v3 创建一个新的外部管理的 Iceberg 表。命令中包含的列定义指示将在远程目录中创建新表或替换现有表。该表已成功创建，因为这是一个没有现有版本的新表。

CREATE OR REPLACE ICEBERG TABLE my_iceberg_v3_table (
    boolean_col boolean,
    int_col int,
    long_col long,
  )
  CATALOG='my_catalog_integration'
  ICEBERG_VERSION=3;

使用 v3，利用包含 Iceberg 元数据的现有表创建外部管理的 Iceberg 表。此示例缺少列定义或格式版本，表明该表已存在，并且将通过远程目录中的 Iceberg 元数据中推断其列规范和格式版本。此示例使用 目录分发的凭据，因此从 CREATE ICEBERG TABLE 语句中排除了 EXTERNAL_VOLUME 参数：

CREATE OR REPLACE ICEBERG TABLE my_iceberg_v3_table
  CATALOG = 'my_catalog_integration'
  CATALOG_TABLE_NAME = 'my_table'
  AUTO_REFRESH = TRUE;

不支持的 Snowflake 功能¶

此 Iceberg v3 预览版不支持以下 Snowflake 功能：

• 外部管理的 Iceberg 表上的仅追加流

• Snowflake 上的 dbt 项目

• 架构推理

• Snowpipe Streaming classic architecture

• SnowGov 区域

• 对于使用外部目录的表，您无法创建具有结构化类型列的 Iceberg v3 表，这些结构化类型包括 OBJECT、ARRAY 或 MAP。例如，您不能使用 CREATE ICEBERGTABLE … ASSELECT (CTAS) 创建具有结构化类型列的外部管理的 Iceberg v3 表。

  您可以使用结构化类型列创建 Snowflake 管理的 Iceberg v3 表。

• 将 Snowflake 管理的 Iceberg 表从 v2 就地升级到 v3，其中包括克隆 v2 表，然后将克隆升级到 v3

  重要

  如果使用 Apache Spark 将外部管理的 Iceberg 表从 v2 升级到 v3，则必须使用创建新快照的提交，例如 DML 操作。否则，如果在没有新快照的情况下更新表属性中的格式版本，则在创建新快照之前，Snowflake 对表的手动和自动刷新将失败。

  以下示例使用 Apache Spark 将外部管理的 Iceberg 表从 v2 升级到 v3：

  ALTER TABLE table_name SET TBLPROPERTIES('format-version'='3');
  

  Copy

支持的 Snowflake 功能¶

支持未在 :ref:`不支持的 Snowflake 功能 <label-tables_iceberg_v3_unsupported_features>`部分列出的功能。支持的功能包括以下列表中的功能：

不支持的 Iceberg v3 功能¶

不支持 Iceberg v3 规范中的以下功能：

• 嵌套变体

• 用于分区和排序的多实参转换

• 表加密密钥

• UNKNOWN 数据类型

创建 v3 Iceberg 表¶

以下示例创建一个 Snowflake 管理的 Apache Iceberg™ 表，该表符合 Apache Iceberg™ 规范 v3：

CREATE ICEBERG TABLE my_v3_iceberg_table (
  record VARIANT,
  event_timestamp TIMESTAMP_LTZ(6)
)
  CATALOG = 'SNOWFLAKE'
  EXTERNAL_VOLUME = 'my_external_volume'
  BASE_LOCATION = 'my_iceberg_table'
  ICEBERG_VERSION = 3;

以下示例创建一个 Apache Iceberg™ 表，该表使用远程 Iceberg REST 目录并符合 Apache Iceberg™ 规范 v3：

CREATE ICEBERG TABLE my_v3_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table'
  AUTO_REFRESH = TRUE;

以下示例在 目录链接数据库 中创建可写入的 Iceberg 表，该表包含列定义，并符合 Apache Iceberg™ 规范 v3：

USE DATABASE my_catalog_linked_db;

USE SCHEMA 'my_namespace';

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
)
  ICEBERG_VERSION = 3;

写入 v3 Iceberg 表¶

支持 DML 命令 INSERT、UPDATE、DELETE、MERGE、TRUNCATE TABLE 和 COPY INTO，以写入 Snowflake 管理的和 外部管理的 Iceberg v3 表：

以下示例将一行插入 Apache Iceberg™ 表中，该表符合 Apache Iceberg™ 表规范 v3：

INSERT INTO my_v3_iceberg_table (id, payload) VALUES (1, PARSE_JSON('{"name": "Alice", "age": 30}'));

以下示例将文件加载到 Apache Iceberg™ 表中，该表符合 Apache Iceberg™ 表规范 v3：

COPY INTO my_v3_iceberg_table
  FROM @my_json_stage
  FILE_FORMAT = 'my_json_format'
  MATCH_BY_COLUMN_NAME = CASE_SENSITIVE;

使用 Snowpipe 加载数据¶

以下示例从 Iceberg v3 表的文件加载数据，适用于 Snowflake 管理的表和外部管理的表：

CREATE PIPE mypipe
  AUTO_INGEST = TRUE
  INTEGRATION = 'MYINT'
  AS
  COPY INTO snowpipe_db.public.my_v3_iceberg_table
  FROM @snowpipe_db.public.mystage
  FILE_FORMAT = (TYPE = 'JSON');

创建 v3 动态 Iceberg 表¶

以下示例以动态表输出的形式写入 v3 Snowflake 管理的 Iceberg 表：

CREATE DYNAMIC ICEBERG TABLE my_dynamic_iceberg_v3_table (
    num_orders NUMBER(10,0),
    order_day
  )
  TARGET_LAG = '20 minutes'
  WAREHOUSE = my_warehouse
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'SNOWFLAKE'
  BASE_LOCATION = 'my_dynamic_iceberg_v3_table'
  ICEBERG_VERSION = 3
  AS
    SELECT
        COUNT(DISTINCT order_id)
        DATE_TRUNC('DAY', order_timestamp_ns) AS order_day
      FROM staging_v3_iceberg_table;

查询 v3 Iceberg 表¶

以下示例查询 Snowflake 管理或外部管理的 Iceberg v3 表：

SELECT * FROM MY_DB.MY_SCHEMA.MY_ICEBERG_V3_TABLE;

Copy