CREATE CATALOG INTEGRATION (Snowflake Open Catalog)¶

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

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

语法¶

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>'
    WAREHOUSE = '<open_catalog_catalog_name>'
  )
  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>' ]

Copy

必填参数¶

name

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

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

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

CATALOG_SOURCE = POLARIS

指定 Snowflake Open Catalog 作为目录源。

TABLE_FORMAT = ICEBERG

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

CATALOG_NAMESPACE = 'open_catalog_namespace'

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

您可以在创建表时在表级别指定命名空间，从而替换此值。
如果要创建目录集成以将 Snowflake 管理的表与 Snowflake Open Catalog 同步，请指定 default。该值指定目录的默认命名空间。

当您将 Snowflake 管理的表与 Open Catalog 同步时，Snowflake 会使用两个父命名空间将表与和表的目录集成关联的目录同步。命名空间对应 Snowflake 中表的数据库和架构。例如，如果您在 Snowflake 中注册了一个 db1.public.table1 Iceberg 表，并且在目录集成中指定了 catalog1 表，该表将同步到 Open Catalog，并使用以下完全限定名称：catalog1.db1.public.table1。

REST_CONFIG = ( ... )

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

CATALOG_URI = 'https://open_catalog_account_url'

您的 Open Catalog 账户定位器 URL。

示例值：

https://<orgname>-<my-snowflake-open-catalog-account-name>.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。
https://<account_locator>.<cloud_region_id>.<cloud>.snowflakecomputing.cn/polaris/api/catalog
- 要找到 <account_locator>, <cloud_region_id>, and <cloud>，请参阅格式 2：区域中的账户定位器。

WAREHOUSE = 'open_catalog_name'

WAREHOUSE 参数指定在 Open Catalog 中使用的目录的名称。

REST_AUTHENTICATION = ( ... )

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

TYPE = OAUTH: 指定 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 令牌的范围。Iceberg REST API 规范中仅包含一个范围，但目录可以在实施中支持多个范围。

ENABLED = {TRUE | FALSE}

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

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

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

可选参数¶

REFRESH_INTERVAL_SECONDS = value

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

值：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 命令和使用 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> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。
要解决创建目录集成时出现的问题，请参阅您无法为 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'
    WAREHOUSE = '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;

Copy

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

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

Copy