CREATE CATALOG INTEGRATION

备注

仅当您想要使用外部目录创建 Iceberg 表，或者从对象存储中的源文件创建 Iceberg 表时，才需要目录集成。您不需要目录集成来创建使用 Snowflake 作为 Iceberg 目录的 Iceberg 表。要将 Snowflake 用作目录，请在 CREATE ICEBERG TABLE（使用 Snowflake 作为 Iceberg 目录） 命令中将 CATALOG 参数设置为 'SNOWFLAKE'。

为账户中的 Iceberg 表 创建新的 目录集成 或替换现有的目录集成。

另请参阅：

DROP CATALOG INTEGRATION、SHOW CATALOG INTEGRATIONS、DESCRIBE CATALOG INTEGRATION

语法

CREATE [ OR REPLACE ] CATALOG INTEGRATION [IF NOT EXISTS]
  <name>
  CATALOG_SOURCE = { GLUE | OBJECT_STORE }
  TABLE_FORMAT = { ICEBERG }
  [ catalogParams ]
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '{string_literal}' ]
Copy

其中：

catalogParams (for AWS Glue)::=
  GLUE_AWS_ROLE_ARN = '<arn-for-AWS-role-to-assume>'
  GLUE_CATALOG_ID = '<glue-catalog-id>'
  [ GLUE_REGION = '<AWS-region-of-the-glue-catalog>' ]
  CATALOG_NAMESPACE = '<catalog-namespace>'
Copy

必填参数

name

用于指定目录集成的标识符（名称）的字符串；在账户中必须唯一。

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

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

CATALOG_SOURCE = { GLUE | OBJECT_STORE }

指定目录源的类型。

AWS Glue

GLUE：在 Snowflake 和 AWS Glue 之间创建集成。

对象存储中的 Iceberg 元数据

OBJECT_STORE：在与 :doc:` 外部卷 <create-external-volume>` 关联的外部云存储位置中，为 Iceberg 元数据文件创建集成。

TABLE_FORMAT = { ICEBERG }

指定目录提供的表格式。

ICEBERG：在外部云存储位置中，通过元数据指定 Glue Iceberg 表或 Iceberg 表。

ENABLED = { TRUE | FALSE }

指定目录集成是否可用于 Iceberg 表。

  • TRUE 允许用户创建引用此集成的新 Iceberg 表。引用此集成的现有 Iceberg 表通常能正常运行。

  • FALSE 阻止用户创建引用此集成的新 Iceberg 表。引用此集成的现有 Iceberg 表无法访问表定义中的目录。

目录参数 (catalogParams)

AWS Glue

重要

为 AWS Glue 创建目录集成时，您必须完成其他步骤，才能在 Snowflake 和 Glue Data Catalog 之间建立信任关系。有关详细信息，请参阅 为 AWS Glue 配置目录集成。

GLUE_AWS_ROLE_ARN = 'arn-for-AWS-role-to-assume'

指定要承担的 AWS Identity and Access Management (IAM) 角色的 Amazon Resource Name (ARN)。

GLUE_CATALOG_ID = 'glue-catalog-id'

指定 AWS 账户的 ID。

[ GLUE_REGION = 'AWS-region-of-the-glue-catalog' ]

指定 AWS Glue Data Catalog 的 AWS 区域。如果 Snowflake 账户未托管在 AWS 上，则必须为此参数指定一个值。否则，默认区域是账户的 Snowflake 部署区域。

CATALOG_NAMESPACE = 'catalog-namespace'

指定 AWS Glue Data Catalog 命名空间（例如，my_glue_database）。这是与此目录集成关联的所有 Iceberg 表的默认命名空间。您可以在创建表时在表级别指定命名空间，从而替换此值。

可选参数

COMMENT = 'string_literal'

字符串（字面量），用于指定集成注释。

默认：无值

访问控制要求

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

权限

对象

备注

CREATE INTEGRATION

账户

Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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

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

使用说明

  • 您无法修改现有目录集成;请改用 CREATE OR REPLACE CATALOG INTEGRATION 语句。

  • 如果一个或多个 Iceberg 表与目录集成关联，您无法删除或替换目录集成。

    要查看依赖于目录集成的表，您可以使用 SHOW ICEBERG TABLES 命令和使用 RESULT_SCAN 对 catalog_name 列进行筛选的查询。

    备注

    列标识符 (catalog_name) 区分大小写。指定与 SHOW ICEBERG TABLES 输出中显示的完全相同的列标识符。

    例如：

    SHOW ICEBERG TABLES;

SELECT * FROM TABLE(
  RESULT_SCAN(
      LAST_QUERY_ID()
    )
  )
  WHERE "catalog_name" = 'my_catalog_integration_1';
    Copy

  • 关于元数据：

    注意

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

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

示例

AWS Glue

以下示例创建了一个使用 AWS Glue 目录源的目录集成。为 Glue 创建目录集成时，您必须完成其他步骤，才能在 Snowflake 和 Glue Data Catalog 之间建立信任关系。有关详细信息，请参阅 为 AWS Glue 配置目录集成。

CREATE CATALOG INTEGRATION glueCatalogInt
  CATALOG_SOURCE=GLUE
  CATALOG_NAMESPACE='<catalog-namespace>'
  TABLE_FORMAT=ICEBERG
  GLUE_AWS_ROLE_ARN='<arn-for-aws-role-to-assume>'
  GLUE_CATALOG_ID='<catalog-id>'
  GLUE_REGION='<optional-aws-region-of-the-glue-catalog>'
  ENABLED=TRUE;
Copy

对象存储中的 Iceberg 元数据

以下示例创建一个集成，在外部云存储中使用 Iceberg 元数据。OBJECT_STORE 对应与 :doc:` 外部卷 <create-external-volume>` 关联的对象存储。

CREATE CATALOG INTEGRATION myCatalogInt
  CATALOG_SOURCE=OBJECT_STORE
  TABLE_FORMAT=ICEBERG
  ENABLED=TRUE;
Copy
语言: 中文