CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)¶

在账户中为托管在符合开源 Apache Iceberg™ REST OpenAPI 规范 (https://github.com/apache/iceberg/blob/main/open-api/rest-catalog-open-api.yaml) 的远程目录中的 Apache Iceberg™ 表创建一个新的目录集成或者替换现有的目录集成。

备注

要为 Snowflake Open Catalog 创建集成，请改为参阅 CREATE CATALOG INTEGRATION (Snowflake Open Catalog)。

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

语法¶

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ] <name>
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = '<namespace>'
  REST_CONFIG = (
    restConfigParams
  )
  REST_AUTHENTICATION = (
    restAuthenticationParams
  )
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

Copy

其中：

restConfigParams ::=

  CATALOG_URI = '<rest_api_endpoint_url>'
  [ PREFIX = '<prefix>' ]
  [ WAREHOUSE = '<warehouse_name>' ]
  [ CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY } ]

Copy

restAuthenticationParams 如下，具体取决于您的身份验证方法：

OAuth

restAuthenticationParams (for OAuth) ::=

  TYPE = OAUTH
  [ OAUTH_TOKEN_URI = 'https://<token_server_uri>' ]
  OAUTH_CLIENT_ID = '<oauth_client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
  OAUTH_ALLOWED_SCOPES = ('<scope_1>', '<scope_2>')

Copy

持有者令牌

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'

Copy

SigV4

restAuthenticationParams (for SigV4) ::=

  TYPE = SIGV4
  SIGV4_IAM_ROLE = '<iam_role_arn>'
  [ SIGV4_SIGNING_REGION = '<region>' ]
  [ SIGV4_EXTERNAL_ID = '<external_id>' ]

Copy

参数¶

name

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

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

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

CATALOG_SOURCE = ICEBERG_REST

指定目录源是符合 Apache Iceberg REST 规范的 REST 目录。

TABLE_FORMAT = ICEBERG

将 ICEBERG 指定为目录提供的表格式。

CATALOG_NAMESPACE = 'namespace'

指定外部目录中的命名空间。Snowflake 为您与此目录集成关联的所有 Iceberg 表使用此命名空间。

您可以替换此值，方法是使用 CREATE ICEBERG TABLE（Iceberg REST 目录）的 CATALOG_NAMESPACE 参数在表级别指定命名空间。

ENABLED = { TRUE | FALSE }

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

TRUE 允许用户创建引用此集成的新 Iceberg 表。

FALSE 阻止用户创建引用此集成的新 Iceberg 表。

REFRESH_INTERVAL_SECONDS = value

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

值：30 到 86,400（含）

默认值：30 秒

COMMENT = 'string_literal'

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

默认：无值

REST 配置参数 (restConfigParams)¶

CATALOG_URI = 'rest_api_endpoint_url'

目录 URL REST 的端点 API。

PREFIX

（可选）指定要附加到所有 API 路由的前缀。

WAREHOUSE

指定要从您的远程目录服务请求的仓库位置（目录）或标识符。部分第三方目录服务需要此参数。请与目录提供商联系，以确定是否必须指定仓库。

CATALOG_API_TYPE = { PUBLIC | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY }

指定目录 API 的连接类型。此参数为 SigV4 身份验证所必需；否则为可选参数。

PUBLIC 指定可公开访问且未使用 Amazon API Gateway 管理的 API，用于非 SigV4 APIs。
AWS_API_GATEWAY 指定使用 Amazon API Gateway 管理的公共 API。
AWS_PRIVATE_API_GATEWAY 指定使用 Amazon API Gateway 管理的私有 API。

默认：PUBLIC

REST 身份验证参数 (restAuthenticationParams)¶

OAuth

TYPE = OAUTH
将 OAuth 指定为 Snowflake 用于连接到 Iceberg REST 目录的身份验证类型。

OAUTH_TOKEN_URI = token_server_uri
您的第三方身份提供商的可选 URL。如未指定，Snowflake 将假定远程目录提供商为 OAuth 身份提供商。

OAUTH_CLIENT_ID = oauth_client_id
您的 OAuth2 客户端 ID。

OAUTH_CLIENT_SECRET = oauth_client_secret
您的 OAuth2 客户端密钥。

OAUTH_ALLOWED_SCOPES = ( 'scope_1', 'scope_2' )
OAuth 令牌的范围。Iceberg REST API 规范只包含一个范围，但目录在其实现中可支持多个范围。

持有者令牌

TYPE = BEARER
将持有者令牌指定为 Snowflake 用于连接到 Iceberg REST 目录的身份验证类型。

BEARER_TOKEN = bearer_token
您的身份提供商的持有者令牌。您也可以指定个人访问令牌 (PAT)。

SigV4

TYPE = SIGV4
将 Signature Version 4 指定为 Snowflake 用于连接到 Iceberg REST 目录的身份验证类型。

SIGV4_IAM_ROLE = 'iam_role_arn'
在 API Gateway 中为具有 REST API 访问权限的 IAM 角色指定 Amazon 资源名称 (ARN)。

SIGV4_SIGNING_REGION = 'region'
（可选）在 API 网关中指定与您的 API 关联的 AWS 区域。如果不指定此参数，Snowflake 将使用您的 Snowflake 账户所部署到的区域。

SIGV4_EXTERNAL_ID = 'external_id'

（可选）指定 Snowflake 与 AWS 建立信任关系所使用的外部 ID。您必须在为此目录集成配置的 IAM 角色的信任策略中指定相同的外部 ID。

如果您未为此参数指定值，Snowflake 会在您创建（或替换）目录集成时自动生成唯一的外部 ID。

有关外部 IDs 的更多信息，请参阅向第三方授予 AWS 资源访问权限时如何使用外部 ID (https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-user_externalid.html)。

访问控制要求¶

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

权限	对象	备注
CREATE INTEGRATION	账户	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

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

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

使用说明¶

目录集成提供对外部 Iceberg 目录的只读访问能力。
您无法修改现有目录集成；请改用 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> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

以下示例创建了一个使用 OAuth 连接到 Tabular 的 REST 目录集成。它使用 CATALOG_NAMESPACE 参数设置默认命名空间。

若要在表级别替换默认命名空间，请为 CREATE ICEBERG TABLE 使用 CATALOG_NAMESPACE 参数。

CREATE OR REPLACE CATALOG INTEGRATION tabular_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'default'
  REST_CONFIG = (
    CATALOG_URI = 'https://api.tabular.io/ws'
    WAREHOUSE = '<tabular_warehouse_name>'
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_TOKEN_URI = 'https://api.tabular.io/ws/v1/oauth/tokens'
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
    OAUTH_ALLOWED_SCOPES = ('catalog')
  )
  ENABLED = TRUE;

Copy

有关涵盖其他身份验证选项的示例，请参阅为|iceberg-tm| REST 目录配置目录集成。