CREATE ICEBERG TABLE（使用 AWS Glue 作为 Iceberg 目录）¶

语法¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { 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"）。放在双引号内的标识符也区分大小写。

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

CATALOG_TABLE_NAME = 'catalog_table_name'

指定 AWS Glue Data Catalog 可识别的表名称。有关在创建 Iceberg 表时使用 CATALOG_TABLE_NAME 的示例，请参阅 `示例`_（本主题内容）。

创建表后，该参数无法更改。

可选参数¶

EXTERNAL_VOLUME = 'external_volume_name'

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

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

CATALOG = 'catalog_integration_name'

指定此表的目录集成的标识符（名称）。您必须指定已为 AWS Glue 配置的目录集成。有关信息，请参阅 为 AWS Glue 配置目录集成。

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

CATALOG_NAMESPACE = 'catalog_namespace'

可选地指定命名空间（例如，my_glue_database）用于 AWS Glue Data Catalog 源。通过在目录集成中然后在表级别指定命名空间，您可以使用单个目录集成为 AWS Glue 创建跨不同数据库的 Iceberg 表。如果您没有在表中指定命名空间，则该表使用与目录集成关联的默认目录命名空间。

如果在目录集成中未指定默认命名空间，则必须为 AWS Glue Data Catalog 指定命名空间，以设置表的目录命名空间。

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

备注

不支持将 AUTO_REFRESH 与 INFER_SCHEMA 一起使用。

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 错误（或类似类型的错误）。

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

• 创建表的注意事项：

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

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

    • 如果架构中已存在同名的表，则会返回错误，并且不会创建表，除非命令中包含可选的 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 glue_iceberg_table
  EXTERNAL_VOLUME='glue_catalog_volume'
  CATALOG='glue_catalog_integration'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2'
  AUTO_REFRESH = TRUE;

CREATE OR REPLACE ICEBERG TABLE itable_with_quoted_catalog
  EXTERNAL_VOLUME = '"glue_volume_1"'
  CATALOG = '"glue_catalog_integration_1"'
  CATALOG_TABLE_NAME='my_glue_catalog_table'
  CATALOG_NAMESPACE='icebergcatalogdb2'
  AUTO_REFRESH = TRUE;