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>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

必填参数¶

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。

有关在语句中指定标签的信息，请参阅 Tag quotas。

WITH CONTACT ( purpose = contact [ , purpose = contact ...] )

将新对象与一个或多个 联系人 关联。

Specify the WITH CONTACT clause after all other clauses except the AS clause (if that clause is supported by this command).

访问控制要求¶

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

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

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

有关对 安全对象 执行 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 ... </sql-reference/sql/alter-iceberg-table-refresh>。

• 创建表的注意事项：

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

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

    • 如果架构中已存在同名的表，则会返回错误，并且不会创建表，除非命令中包含可选的 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 中的元数据字段。

示例¶

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';