CREATE CATALOG INTEGRATION(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 = PUBLIC ]
    CATALOG_NAME = '<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>' ]

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>'
  )
  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.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 에서 사용할 카탈로그의 이름을 지정합니다.

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 테이블은 테이블 정의의 카탈로그에 액세스할 수 없습니다.

선택적 매개 변수¶

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'

통합에 대한 설명을 지정하는 문자열(리터럴)입니다.

기본값: 값 없음

액세스 제어 요구 사항¶

이 작업을 실행하는 데 사용되는 역할 에는 최소한 다음 권한 이 있어야 합니다.

지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.

보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.

사용법 노트¶

• 기존 카탈로그 통합은 수정할 수 없으며, 대신 CREATE OR REPLACE CATALOG INTEGRATION 문을 사용하십시오.

• 하나 이상의 Apache Iceberg™ 테이블이 카탈로그 통합에 연결되어 있는 경우 카탈로그 통합을 삭제하거나 교체할 수 없습니다.

  카탈로그 통합에 종속된 테이블을 보려면 SHOW ICEBERG TABLES 명령과 catalog_name 열을 필터링하는 RESULT_SCAN 을 사용한 쿼리를 사용할 수 있습니다.

  참고

  열 식별자(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의 메타데이터 필드 섹션을 참조하십시오.

• 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;

다음 예제는 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:ALL')
  )
  ENABLED = TRUE;