CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶

为账户中的与 Snowflake Open Catalog 集成的 Apache Iceberg™ tables 创建新的目录集成或替换现有的目录集成。

您也可以使用此命令在 Apache Polaris™ (https://polaris.apache.org/) 中为 Iceberg 表创建目录集成。

另请参阅：: ALTER CATALOG INTEGRATION、DROP CATALOG INTEGRATION、SHOW CATALOG INTEGRATIONS、DESCRIBE CATALOG INTEGRATION

语法¶

CATALOG_API_TYPE：PUBLIC¶

使用此目录集成通过公共互联网将 Snowflake 连接到 Open Catalog。CATALOG_API_TYPE 参数的默认值为 PUBLIC，因此您不必指定此参数。

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  [ CATALOG_NAMESPACE = '<open_catalog_namespace>' ]
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    [ CATALOG_API_TYPE = PUBLIC ]
    CATALOG_NAME = '<open_catalog_catalog_name>'
    [ ACCESS_DELEGATION_MODE = { VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS } ]
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    [ OAUTH_TOKEN_URI = 'https://<token_server_uri>' ]
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

CATALOG_API_TYPE：PRIVATE¶

如果您在 Snowflake Open Catalog 中对入站网络流量使用专用连接，请使用此目录集成通过专用 IP 地址将 Snowflake 连接到 Open Catalog。

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ]
  <name>
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  [ CATALOG_NAMESPACE = '<open_catalog_namespace>' ]
  REST_CONFIG = (
    CATALOG_URI = '<open_catalog_account_url>'
    CATALOG_API_TYPE = PRIVATE
    CATALOG_NAME = '<open_catalog_catalog_name>'
    [ ACCESS_DELEGATION_MODE = { VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS } ]
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_secret>'
    OAUTH_ALLOWED_SCOPES = ('<scope 1>', '<scope 2>')
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

必填参数¶

name

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

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

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

CATALOG_SOURCE = POLARIS

指定 Snowflake Open Catalog 作为目录源。

TABLE_FORMAT = ICEBERG

指定 Apache Iceberg™ 作为目录提供的表格式。

REST_CONFIG = ( ... )

指定有关 Open Catalog 账户和目录名称的信息。

CATALOG_URI = 'https://open_catalog_account_url'
Open Catalog 账户 URL。支持的值为：

https://<open_catalog_account_identifier>.snowflakecomputing.cn/polaris/api/catalog：当 CATALOG_API_TYPE = PUBLIC 时。示例值：

https://<orgname>-<my-snowflake-open-catalog-account-name>.snowflakecomputing.cn/polaris/api/catalog

https://<account_locator>.<cloud_region_id>.<cloud>.snowflakecomputing.cn/polaris/api/catalog

备注

要找到您的 Snowflake 组织名称 (<orgname>)，请按照查找账户的组织和账户名称中的步骤进行操作。

在 Snowflake Open Catalog 文档中查找 <my-snowflake-open-catalog-account-name, see Find the account name for a Snowflake Open Catalog account。

要找到 <account_locator>, <cloud_region_id>, and <cloud>，请参阅格式 2：区域中的账户定位器。

https://<open_catalog_privatelink_account_url>/polaris/api/catalog：当 CATALOG_API_TYPE = PRIVATE 时。

备注

对于 <open_catalog_privatelink_account_url>，输入以下值之一：

PrivateLink 账户 URL

无区域 PrivateLink 账户 URL

要获取这些值，请检索您的 Open Catalog 账户设置以实现专用连接。有关详细信息，请参阅托管您的 Open Catalog 账户的云平台的说明：

AWS

Azure

CATALOG_API_TYPE = { PRIVATE | PUBLIC }
指定目录 API 类型。如果您在 Snowflake 和 Open Catalog 之间的连接应通过公共互联网路由，则此参数是可选的。

PRIVATE：如果您在 Snowflake Open Catalog 中对入站网络流量使用专用连接，请通过专用 IP 地址将 Snowflake 连接到 Open Catalog。

PUBLIC：通过公共互联网将 Snowflake 连接到 Open Catalog。

默认：PUBLIC

CATALOG_NAME = 'open_catalog_name'
指定要在 Open Catalog 中使用的目录的名称。

ACCESS_DELEGATION_MODE = { VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS }
Specifies the access delegation mode to use for accessing Iceberg table files in your external cloud storage.

VENDED_CREDENTIALS specifies that Snowflake should use vended credentials.

EXTERNAL_VOLUME_CREDENTIALS specifies that Snowflake should use an external volume.

Default: EXTERNAL_VOLUME_CREDENTIALS

REST_AUTHENTICATION = ( ... )

指定 Snowflake 用于连接到 Open Catalog 的身份验证详细信息。

TYPE = OAUTH: 指定 OAuth 作为要使用的身份验证类型。
OAUTH_TOKEN_URI = token_server_uri: 您的第三方身份提供商的可选 URL。要配置第三方身份提供商，请参阅 Snowflake Open Catalog 文档中的外部 OAuth。如未指定 OAuth 身份提供商，Snowflake 将默认其为远程目录提供商。

重要

如果您使用的是具有专用连接 (CATALOG_API_TYPE=PRIVATE) 的 External OAuth，Snowflake 将通过公共互联网路由 External OAuth 的令牌请求。
OAUTH_CLIENT_ID = 'oauth_client_id': 与您的 Open Catalog 服务连接相关的 OAuth2 凭证的客户端 ID。
OAUTH_CLIENT_SECRET = 'oauth_secret': 与您的 Open Catalog 服务连接相关的 OAuth2 凭证的密钥。
OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2'): OAuth 令牌的一个或多个范围。

ENABLED = {TRUE | FALSE}

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

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

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

The value is case-insensitive.

The default is TRUE.

可选参数¶

CATALOG_NAMESPACE = 'open_catalog_namespace'

如果您要创建目录集成以使用 Snowflake 在 Snowflake Open Catalog 中查询表，可以选择指定 Open Catalog 中的命名空间。Snowflake 为您与此目录集成关联的所有 Iceberg 表使用此命名空间。

如果指定，则可以在创建表时在表级别替换此值。如未指定，则在创建表时必须在表级别设置命名空间。
如果要创建目录集成以将 Snowflake 管理的表与 Snowflake Open Catalog 同步，则此参数对与 Open Catalog 同步表的方式没有影响。Snowflake 使用预定义规则将表同步到您在目录集成中指定的 Open Catalog 中的外部目录。

例如，如果您在 Snowflake 中注册了一个 db1.public.table1 Iceberg 表，并且在目录集成中指定了 catalog1，则该表将与 Open Catalog 同步，并使用以下完全限定名称：catalog1.db1.public.table1。

REFRESH_INTERVAL_SECONDS = value

指定 Snowflake 在尝试轮询外部 Iceberg 目录期间等待的秒数，该轮询旨在获取用于自动刷新的元数据更新。

对于基于 Delta 的表，指定 Snowflake 在两次尝试轮询外部云存储以获取新的元数据之间等待的秒数。

值：30 到 86,400（含）

默认值：30 秒

COMMENT = 'string_literal'

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

默认：无值

访问控制要求¶

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


权限	对象	备注
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 语句。
如果一个或多个 Apache Iceberg™ 表与目录集成关联，您无法删除或替换目录集成。

要查看依赖于目录集成的表，您可以使用 SHOW ICEBERG TABLES 命令和使用对 catalog_name 列进行筛选的管道运算符 (->>) 的查询。

备注

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

例如：
```
SHOW ICEBERG TABLES
  ->> SELECT *
        FROM $1
        WHERE "catalog_name" = 'my_catalog_integration_1';
```
关于元数据：

注意

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

OR REPLACE 和 IF NOT EXISTS 子句互斥。它们不能同时用于同一条语句中。
CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

To troubleshoot issues with creating a catalog integration, see 您无法为 Open Catalog 创建目录集成.

示例¶

以下示例为 Open Catalog 内部目录中的特定命名空间的 Open Catalog 创建了目录集成，以在 Snowflake 中查询在此命名空间下分组的表。有关 Open Catalog 中内部目录的更多信息，请参阅 Open Catalog 文档中的目录类型。

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'my_catalog_namespace'
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.cn/polaris/api/catalog'
    CATALOG_NAME = 'my_catalog_name'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:ALL')
  )
  ENABLED = TRUE;

以下示例为 Open Catalog 创建了一个目录集成，用于将 Snowflake 管理的表同步到 Open Catalog 中的 customers 目录，即外部目录。有关 Open Catalog 中外部目录的更多信息，请参阅 Open Catalog 文档中的目录类型。

CREATE OR REPLACE CATALOG INTEGRATION open_catalog_int2
  CATALOG_SOURCE = POLARIS
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://my_org_name-my_snowflake_open_catalog_account_name.snowflakecomputing.cn/polaris/api/catalog'
    CATALOG_NAME = 'customers'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = 'my_client_id'
    OAUTH_CLIENT_SECRET = 'my_client_secret'
    OAUTH_ALLOWED_SCOPES = ('PRINCIPAL_ROLE:my-principal-role', 'PRINCIPAL_ROLE:my-principal-role2', 'PRINCIPAL_ROLE:my-principal-role3')
  )
  ENABLED = TRUE;