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 } ]
  [ AUTO_REFRESH = { 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

AUTO_REFRESH = { TRUE | FALSE }

指定在使用 自动刷新 时，Snowflake 是否应自动轮询与表关联的外部 Iceberg 目录以获取元数据更新。如果没有为目录集成上的 REFRESH_INTERVAL_SECONDS 参数指定值，则 Snowflake 将使用 30 秒作为默认刷新间隔。

默认：FALSE

COMMENT = 'string_literal'

指定表的注释。

默认：无值

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

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

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

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

访问控制要求

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

权限

对象

备注

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 及更早版本生成的数据兼容。

    • Snowflake 支持 Delta 阅读器版本 2，可以读取引擎使用 Delta Lake 版本 2.2.0 编写的所有表格。

    • 从带有分区列的 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 数据类型。

    • 您可以为 TIMESTAMP 使用 Parquet 物理类型 int96，但 Snowflake 不支持为 TIMESTAMP_NTZ 使用 int96。

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

    • 每次您使用 CREATE/ALTER ...REFRESH 刷新表时，Snowflake 最多处理 1000 个 Delta 提交文件。如果您的表有超过 1000 个提交文件，您可以进行额外的手动刷新。每次刷新过程都从上一次停止的地方继续进行。

      备注

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

      刷新现有表时，Snowflake 会处理 Delta 提交文件，但不会处理检查点文件。如果表维护移除了源 Delta 表的陈旧日志和数据文件，则 Snowflake 中基于 Delta 的 Iceberg 表的刷新频率应高于 Delta 日志和数据文件的保留期。

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

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

  • 创建表的注意事项：

    • 架构不能包含同名的表和/或视图。创建表时：

      • 如果架构中已存在同名视图，则会返回错误，并且不会创建表。

      • 如果架构中已存在同名的表，则会返回错误，并且不会创建表，除非命令中包含可选的 OR REPLACE 关键字。

    • CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

      这意味着与 CREATE OR REPLACE ICEBERG TABLE 操作并行的任何查询都使用旧的或新的表版本。

    • OR REPLACE 和 IF NOT EXISTS 子句互斥。它们不能同时用于同一条语句中。

    • 与 保留关键字 类似，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 日志解释该架构。

语言: 中文