CREATE CATALOG INTEGRATION(Snowflake Open Catalog)¶

계정에서 Snowflake Open Catalog 와 통합되는 Apache Iceberg™ 테이블 에 대한 새로운 카탈로그 통합 을 생성하거나 기존 카탈로그 통합을 대체합니다.

이 명령을 사용하여 Apache Polaris™ 에서 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>' ]

Copy

CATALOG_API_TYPE: PRIVATE¶

Snowflake Open Catalog에서 인바운드 네트워크 트래픽에 비공개 연결 을 사용하는 경우 이 카탈로그 통합을 사용하여 비공개 IP 주소를 통해 Open Catalog 에 Snowflake를 연결합니다.

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>' ]

Copy

필수 매개 변수¶

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.com/polaris/api/catalog: CATALOG_API_TYPE = PUBLIC 인 경우. 예제 값:

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

https://<계정_로케이터>.<클라우드_리전_id>.<클라우드>.snowflakecomputing.com/polaris/api/catalog

참고

Snowflake 조직 이름(< orgname >)을 찾으려면 계정의 조직 및 계정 이름 찾기 단계를 따르십시오.

<my-snowflake-open-catalog-account-name 을 찾으려면 Snowflake Open Catalog 설명서에서 Snowflake Open Catalog 계정의 계정 이름 찾기 섹션을 참조하십시오.

<account_locator>, <cloud_region_id>, <cloud> 를 찾으려면 형식 2: 리전의 계정 로케이터 섹션을 참조하십시오.

https://<open_catalog_privatelink_account_url>/polaris/api/catalog: CATALOG_API_TYPE = PRIVATE 인 경우.

참고

<open_catalog_privatelink_account_url> 에는 다음 값 중 하나를 입력합니다.

PrivateLink 계정 URL

Regionless PrivateLink 계정 URL

이러한 값을 얻으려면 비공개 연결에 대한 Open Catalog 계정 설정을 검색합니다. 자세한 내용은 Open Catalog 계정이 호스팅되는 클라우드 플랫폼에 대한 지침을 참조하십시오.

AWS

Azure

CATALOG_API_TYPE = { PRIVATE | PUBLIC }
카탈로그 API 유형을 지정합니다. Snowflake와 Open Catalog 간의 연결이 공용 인터넷을 통해 라우팅되어야 하는 경우 이 매개 변수는 선택 사항입니다.

PRIVATE: Snowflake Open Catalog에서 인바운드 네트워크 트래픽에 대해 비공개 연결 을 사용하는 경우 비공개 IP 주소를 통해 Open Catalog 에 Snowflake를 연결합니다.

PUBLIC: 공용 인터넷을 통해 Snowflake를 Open Catalog에 연결합니다.

기본값: PUBLIC

CATALOG_NAME = 'open_catalog_name'
Open Catalog 에서 사용할 카탈로그의 이름을 지정합니다.

ACCESS_DELEGATION_MODE = { VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS }
외부 클라우드 저장소에 있는 Iceberg 테이블 파일에 액세스할 때 사용할 액세스 위임 모드를 지정합니다.

VENDED_CREDENTIALS 은 Snowflake가 제공된 자격 증명을 사용하도록 지정합니다.

EXTERNAL_VOLUME_CREDENTIALS 은 Snowflake가 외부 볼륨을 사용하도록 지정합니다.

기본값: EXTERNAL_VOLUME_CREDENTIALS

REST_AUTHENTICATION = ( ... )

Snowflake가 Open Catalog 에 연결하는 데 사용하는 인증 세부 정보를 지정합니다.

TYPE = OAUTH: OAuth를 사용할 인증 유형으로 지정합니다.
OAUTH_TOKEN_URI = token_server_uri: 서드 파티 ID 공급자를 위한 선택적 URL입니다. 서드 파티 공급자 ID 공급자를 구성하려면 Snowflake Open Catalog 설명서의 `외부 OAuth<https://other-docs.snowflake.com/en/opencatalog/oauth-ext-overview>`_ 섹션을 참조하세요. OAuth ID 공급자가 지정되지 않은 경우 Snowflake는 이를 원격 카탈로그 공급자로 가정합니다.

중요

비공개 연결(CATALOG_API_TYPE=PRIVATE)을 통해 외부 OAuth를 사용하는 경우 Snowflake는 공개 인터넷을 통해 외부 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 테이블은 테이블 정의의 카탈로그에 액세스할 수 없습니다.

선택적 매개 변수¶

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 을 지정하면 Snowflake는 이 테이블을 다음과 같은 정규화된 이름(catalog1.db1.public.table1)으로 Open Catalog 와 동기화합니다.

REFRESH_INTERVAL_SECONDS = value

Snowflake가 자동 새로 고침 의 메타데이터 업데이트를 위해 외부 Iceberg 카탈로그를 폴링하는 시도 사이에 대기하는 시간(초)을 지정합니다.

Delta 기반 테이블의 경우, Snowflake가 외부 클라우드 저장소에서 새 메타데이터를 폴링하기 위해 시도할 때까지 기다리는 시간(초)을 지정합니다.

값: 30~86400(포함)

기본값: 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';
```
Copy
메타데이터 관련:

주의

고객은 Snowflake 서비스를 사용할 때 개인 데이터(사용자 오브젝트 제외), 민감한 데이터, 수출 통제 대상 데이터 또는 기타 규제 데이터가 메타데이터로 입력되지 않도록 해야 합니다. 자세한 내용은 Snowflake의 메타데이터 필드 섹션을 참조하십시오.

OR REPLACE 및 IF NOT EXISTS 절은 상호 배타적입니다. 두 절을 같은 문에 함께 사용할 수 없습니다.
CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.

카탈로그 통합 생성과 관련된 문제를 해결하려면 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.com/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;

Copy

다음 예제는 Open Catalog 에 대한 카탈로그 통합을 생성하여 외부 카탈로그인 Open Catalog 의 customers 카탈로그에 Snowflake 관리 테이블을 동기화하는 예제입니다. 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.com/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;

Copy