Apache Iceberg™ 表¶

开始使用¶

要开始使用 Iceberg 表，请参阅 教程：创建第一个 Apache Iceberg™ 表。

工作原理¶

本部分提供有关在 Snowflake 中使用 Iceberg 表的特定信息。要详细了解 Iceberg 表格式规范，请参阅官方的 Apache Iceberg 文档 (https://iceberg.apache.org/docs/latest/) 和 Iceberg 表规范 (https://iceberg.apache.org/spec/)。

• 数据存储

• 目录

• 元数据和快照

• 跨云/跨区域支持

• 计费

目录选项¶

Snowflake 支持以下 Iceberg 目录选项：

• 使用 Snowflake 作为 Iceberg 目录

• 使用外部 Iceberg 目录

下表总结了这两种目录选择之间的差异。

使用 Snowflake 作为目录¶

使用 Snowflake 作为 Iceberg 目录（Snowflake 管理的 Iceberg 表）的 Iceberg 表提供完整的 Snowflake 平台支持，以及读写权限。表数据和元数据存储在 Snowflake 使用 外部卷 访问的外部云存储中。Snowflake 处理表的全部生命周期维护工作，例如压缩。

使用外部目录¶

使用外部目录的 Iceberg 表通过只读权限提供有限的 Snowflake 平台支持。对于此表类型，Snowflake 使用 目录集成 来检索有关 Iceberg 元数据和架构的信息。

您可以使用该选项为以下来源创建 Iceberg 表：

• AWS Glue Data Catalog

• 对象存储中的 Iceberg 元数据文件

• 对象存储中的 Delta 表文件

• Open Catalog

• 远程 Iceberg REST 目录

Snowflake 不承担表的任何生命周期管理工作。

表数据和元数据存储在 Snowflake 使用 外部卷 访问的外部云存储中。

下图显示了 Iceberg 表如何使用与外部 Iceberg 目录的目录集成。

注意事项和限制¶

以下注意事项和限制适用于 Iceberg 表，并且可能会发生变更：

云和区域

• Iceberg 表适用于所有 Snowflake 账户、所有云平台和除中国区域以外的所有区域。

• 使用外部目录时，支持跨云/跨区域表。有关更多信息，请参阅 跨云/跨区域支持。

Iceberg

• 支持 Apache Iceberg 规范的版本 1 和 2，但以下 功能 (https://iceberg.apache.org/spec/) 除外：

  • 行级删除（位置删除或等值删除）。不过，使用 Snowflake 作为目录的表支持 Snowflake DELETE 语句。

  • 使用 history.expire.min-snapshots-to-keep 表属性 (https://iceberg.apache.org/docs/1.2.1/configuration/#table-behavior-properties) 来指定要保留的默认最少快照数量。有关更多信息，请参阅 元数据和快照。

• 利用 bucket 转换函数进行的 Iceberg 分区会影响使用条件子句筛选结果的查询的性能。

• 对于不由 Snowflake 管理的 Iceberg 表，请注意以下几点：

  • 只要在快照过期之前定期刷新表，就支持恢复到在创建表后生成的任何快照。

  • 不支持转换带有非物化标识分区列的表。当表使用 Parquet 文件中不存在的源列定义身份转换时，将创建非物化身份分区列。

文件格式

• Iceberg 表支持 Apache Parquet 文件。

• 不支持使用无符号整型逻辑类型的 Parquet 文件。

外部卷

• 不得使用存储集成访问外部卷中的云存储位置。

• 必须为创建的每个外部卷配置单独的信任关系。

• 您可以使用 出站专用连接 访问由 Snowflake 管理的 Iceberg 表和使用目录集成进行对象存储的 Iceberg 表，但不能用于访问使用其他目录集成的 Iceberg 表。

元数据文件

• 元数据文件无法识别 Iceberg 表的最新快照。

• 无法使用 ALTER ICEBERG TABLE 命令修改数据文件或快照的位置。要修改这些设置中的任一个，必须使用 CREATE OR REPLACE ICEBERG TABLE 语法重新创建表。

• 使用外部目录的表：

  • 确保清单文件不包含重复内容。如果在 相同 的快照中存在重复文件，Snowflake 会返回一个包含重复文件路径的错误。

  • 如果 Parquet 元数据包含无效的 UTF-8 字符，则无法创建表。确保 Parquet 元数据符合 UTF-8 标准。

• Snowflake 可检测在 Snowflake 外生成的 Parquet 元数据中的损坏和不一致，并通过错误消息突显问题。

  即使表元数据不一致，也可以创建、刷新或查询外部管理（或转换）的表。写入 Iceberg 表数据时，确保表元数据统计信息（如 RowCount 或 NullCount）与数据内容相匹配。

• 对于使用 Snowflake 作为目录的表，Snowflake 会单独处理 DDL 语句，且生成元数据的方式可能与其他目录不同。有关更多信息，请参阅 DDL 语句。

群集

群集 支持取决于 Iceberg 表的类型。

表类型	备注
使用 Snowflake 作为 Iceberg 目录的表	使用 CREATE ICEBERG TABLE 或者 ALTER ICEBERG TABLE 命令设置群集密钥。要设置或管理群集密钥，请参阅 CREATE ICEBERG TABLE（使用 Snowflake 作为 Iceberg 目录） 和 ALTER ICEBERG TABLE。
使用外部目录的表	不支持群集。
转换的表	仅当转换表后创建了文件，或者之后使用 DML 语句修改了文件，Snowflake 才会群集文件。

Delta

• 从带有分区列的 Delta 表文件创建的 Iceberg 表不支持 Snowflake 流。不过，从 无 分区列的 Delta 文件创建的表支持仅插入流。

• 从 Delta 表文件创建的 Iceberg 表不支持动态表。

• Snowflake 不支持从 AWS Glue Data Catalog 中的 Delta 表定义创建 Iceberg 表。

• 不支持使用以下任何功能或数据类型的 Parquet 文件（Delta 表的数据文件）：

  • 字段 IDs。

  • INTERVAL 数据类型。

  • 精度高于 38 的 DECIMAL 数据类型。

  • LIST 或 MAP 类型的一级或两级表示。

  • 无符号整型 (INT(signed = false))。

  • FLOAT16 数据类型。

  有关 Delta 数据类型和 Iceberg 表的更多信息，请参阅 Delta 数据类型。

• CREATE 和 ALTER 期间的刷新操作 ...REFRESH 每次操作最多可处理 1,000 个 Delta 提交文件。

  备注

  Snowflake 在创建 Iceberg 表时使用 Delta 检查点文件。1,000 个提交文件限制只适用于最近一次检查点之后的提交。

• 不支持使用 SYSTEM$GET_ICEBERG_TABLE_INFORMATION 函数生成 Iceberg 元数据。

• 目前不支持以下 Delta Lake 功能：行跟踪、删除矢量文件、更改数据文件、更改元数据、DataChange、CDC、协议演进。

自动刷新

• 启用自动刷新后，您无法手动刷新表元数据。要执行手动刷新，请先 关闭自动刷新。

• 对于在 Snowflake 8.22 版之前创建的目录集成，必须先手动设置 REFRESH_INTERVAL_SECONDS 参数，然后才能对依赖于该目录集成的表启用自动刷新。有关说明，请参阅 ALTER CATALOG INTEGRATION ...。

• 确保新表快照是当前表快照的直接子级。否则，自动刷新将进入 STOPPED 状态。要在发生这种情况时恢复自动刷新，请参阅 错误恢复。

  • 如果您的表为空，请在启用自动刷新 之前 执行手动刷新，以避免未定义的行为。

• 当您将 目录集成用于对象存储 时，不支持自动刷新。

• 目前不支持没有序列号列的 Iceberg 版本 1 清单。

第三方客户端对 Iceberg 数据、元数据的访问

• 第三方客户端无法向使用 Snowflake 作为目录的 Iceberg 表追加、删除或者更新或插入数据。

兼容 S3 的存储

使用与 S3 兼容的存储的 Iceberg 表是 跨区域表，并且不支持以下操作：

• 将 Snowflake 作为 Iceberg 目录 或将表转换为使用 Snowflake 作为 Iceberg 目录。

• 使用 SYSTEM$GET_ICEBERG_TABLE_INFORMATION 函数获取有关最新刷新快照的信息。

不支持的功能

所有 Iceberg 表目前不支持以下 Snowflake 功能：

• 下列驱动程序：

  • .NET 驱动程序

  • Snowflake 的 PHP PDO 驱动程序

• 故障安全

• 混合表

• 启用 Cross-Cloud Auto-Fulfillment 的列表。

• Query Acceleration Service

• 复制 Iceberg 表、外部卷或目录集成。

• 搜索优化服务

• Snowflake 加密

• Snowflake Native App Framework

• Snowflake 架构演化

• 使用 :doc:/sql-reference/stored-procedures/associate_semantic_category_tags` 存储过程标记 </user-guide/object-tagging>`

• 临时表和瞬态表

使用外部目录 的 Iceberg 表不支持以下功能：

• 克隆

• 群集

• 标准和仅追加 流。支持仅插入流。