CREATE ICEBERG TABLE（对象存储中的 Delta 文件）¶

在对象存储（外部云存储）中使用 Delta 表文件，在当前/指定架构中创建或替换 Apache Iceberg™ 表。这种类型的 Iceberg 表需要目录集成。

本主题将 Iceberg 表简称为“表”（指定 Iceberg 表 的位置除外）以避免混淆。

备注

在创建表之前，必须创建存储 Iceberg 元数据和数据文件的外部卷。有关说明，请参阅配置外部卷。

您还需要为表配置目录集成。有关更多信息，请参阅为对象存储中的文件配置目录集成。

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

语法¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  BASE_LOCATION = '<relative_path_from_external_volume>'
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Copy

必填参数¶

table_name

指定表的标识符（名称）；在创建表的架构中必须是唯一的。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

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

BASE_LOCATION = 'relative_path_from_external_volume'

指定从表的 EXTERNAL_VOLUME 位置到 Snowflake 可以访问 Delta 表文件的目录的相对路径。

基础位置必须指向目录，不能指向单个文件。其中必须包含 Delta 事务日志子文件夹（例如 my/base/location/_delta_log/）。

可选参数¶

EXTERNAL_VOLUME = 'external_volume_name'

指定外部卷的标识符（名称），Iceberg 表会以 Parquet 格式将自身的元数据文件和数据存储在里面。Iceberg 元数据和清单文件存储表架构、分区、快照和其他元数据。

如果未指定此参数，则 Iceberg 表将默认使用架构、数据库或账户的外部卷。架构优先于数据库，数据库优先于账户。

CATALOG = 'catalog_integration_name'

指定此表的目录集成的标识符（名称）。

如果未指定，则默认将 Iceberg 表视为架构、数据库或账户的目录集成。架构优先于数据库，数据库优先于账户。

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

指定在查询结果中是否使用 Unicode 替换字符 (�) 替换无效的 UTF-8 字符。您只能为使用外部 Tables 目录的表设置此参数。

TRUE 会将无效的 UTF-8 字符替换为 Unicode 替换字符。
FALSE 保留无效的 UTF-8 字符不变。如果在 Parquet 数据文件中遇到无效的 UTF-8 字符，Snowflake 会返回用户错误消息。

如果未指定，则 Iceberg 表将默认使用架构、数据库或账户的参数值。架构优先于数据库，数据库优先于账户。

默认：FALSE

COMMENT = 'string_literal'

指定表的注释。

默认：无值

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

指定标签名称和标签字符串值。

标签值始终为字符串，标签值的最大字符数为 256。

有关在语句中指定标签的信息，请参阅对象和列的标签配额。

访问控制要求¶

用于执行此 SQL 命令的角色必须至少具有以下权限：

权限	对象	备注
CREATE ICEBERG TABLE	架构
CREATE EXTERNAL VOLUME	账户	需要创建新的外部卷。
USAGE	外部卷	需要引用现有的外部卷。
CREATE INTEGRATION	账户	需要创建新的目录集成。
USAGE	目录集成	需要引用现有目录集成。

请注意，对架构中的对象进行操作还需要对父数据库和架构具有 USAGE 权限。

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

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

使用说明¶

运行此命令的注意事项：
- 如果您使用双引号标识符创建了外部卷或目录集成，则必须 :emph:` 完全 ` 按照在 CREATE ICEBERG TABLE 语句中创建的标识符（包括双引号）来指定标识符。未包含引号可能会导致 Object does not exist 错误（或类似类型的错误）。
从 Delta 表文件创建的 Iceberg 表的注意事项：
- 您可以使用 Time Travel 查询从 Delta 表文件创建的 Iceberg 表。表版本对应于各个 Delta 日志提交文件。
- Iceberg 表与 Delta Lake 版本 3.1 及更早版本生成的数据兼容。
- 从带有分区列的 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、协议演进。
创建表的注意事项：
- 架构不能包含同名的表和/或视图。创建表时：
  如果架构中已存在同名视图，则会返回错误，并且不会创建表。
  
  如果架构中已存在同名的表，则会返回错误，并且不会创建表，除非命令中包含可选的 OR REPLACE 关键字。
- CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。
  
  这意味着与 CREATE OR REPLACE ICEBERG TABLE 操作并行的任何查询都使用旧的或新的表版本。
- 与保留关键字类似，ANSI 保留函数名称（CURRENT_DATE、CURRENT_TIMESTAMP 等）不能用作列名。
- 重新创建表（使用可选 OR REPLACE 关键字）会删除其历史记录，这会使表上的任何流都过时。过时的流是不可读的。
关于元数据：

注意

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

示例¶

以下示例命令根据对象存储中的 Delta 表文件创建 Iceberg 表。

该示例指定与 Delta 表文件的云位置关联的外部卷、为 Delta <label-tables_iceberg_create_cat_int_delta> 配置的目录集成`以及所需 :code:`BASE_LOCATION 参数的值。

CREATE ICEBERG TABLE my_delta_iceberg_table
  CATALOG = delta_catalog_integration
  EXTERNAL_VOLUME = delta_external_volume
  BASE_LOCATION = 'relative/path/from/ext/vol/';

Copy

如果 Delta 表使用分区架构，Snowflake 会自动通过 Delta 日志解释该架构。