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

语法¶

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

必填参数¶

table_name

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

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

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

METADATA_FILE_PATH = 'metadata_file_path'

指定要用于列定义的 Iceberg 元数据文件的相对路径。

例如，如果 s3://mybucket_us_east_1/metadata/v1.metadata.json 是元数据文件的完整路径，并且外部卷存储位置为 s3://mybucket_us_east_1/，则指定 metadata/v1.metadata.json 为 METADATA_FILE_PATH 的值。

在 Snowflake 版本 7.34 之前，此参数称为 METADATA_FILE_NAME。

可选参数¶

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 命令的 角色 必须至少具有以下 权限：

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

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

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

使用说明¶

• 运行此命令的注意事项：

  • 如果您使用双引号标识符创建了外部卷或目录集成，则必须 :emph:` 完全 ` 按照在 CREATE ICEBERG TABLE 语句中创建的标识符（包括双引号）来指定标识符。未包含引号可能会导致 Object does not exist 错误（或类似类型的错误）。

    若要查看示例，请参阅 ` 示例 `_ （本主题内容）部分。

  • 在 Snowflake 版本 7.34 及更高版本中，您 :emph:` 无需 ` 指定 BASE_LOCATION 即可使用对象存储中的 Iceberg 文件创建表。

    在 Snowflake 版本 7.34 之前，需要一个名为 BASE_LOCATION 的参数（在以前的版本中也称为 FILE_PATH）才能使用对象存储中的 Iceberg 文件创建表。该参数指定了 EXTERNAL_VOLUME 位置的相对路径。

    您可以继续执行使用旧语法的脚本或语句。在这样做时，请注意以下几点：

    • 表的 Parquet 数据文件和 Iceberg 表元数据文件必须位于 BASE_LOCATION 内。

    • 要刷新表格，必须指定与 BASE_LOCATION 相对 的路径。例如，如果元数据文件的完整路径是 s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json，请将 metadata/v1.metadata.json 指定为 metadata-file-relative-path。

      有关更多信息，请参阅 ALTER ICEBERG TABLE ... REFRESH。

• 创建表的注意事项：

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

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

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

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

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

  • 与 保留关键字 类似，ANSI 保留函数名称（CURRENT_DATE、CURRENT_TIMESTAMP 等）不能用作列名。

  • 重新创建表（使用可选 OR REPLACE 关键字）会删除其历史记录，这会使表上的任何流都过时。过时的流是不可读的。

• 关于元数据：

  注意

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

示例¶

CREATE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME='my_external_volume'
  CATALOG='my_catalog_integration'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"external_volume_1"'
  CATALOG = '"catalog_integration_1"'
  METADATA_FILE_PATH='path/to/metadata/v1.metadata.json';