CREATE CATALOG INTEGRATION

CREATE CATALOG INTEGRATION (Snowflake Open Catalog)

Snowflake Open Catalog와 통합하는 Apache Iceberg™ 테이블용 카탈로그 통합(catalog integration)을 계정에 새로 만들거나 기존 카탈로그 통합을 교체하는 명령이에요.

Apache Polaris™의 Iceberg 테이블용 카탈로그 통합을 만들 때도 이 명령을 사용할 수 있어요.

출처: 문서

본문

관련 명령: ALTER CATALOG INTEGRATION, DROP CATALOG INTEGRATION, SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION

구문 (Syntax)

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의 인바운드 네트워크 트래픽용 프라이빗 연결(private connectivity)을 사용한다면, 이 카탈로그 통합으로 프라이빗 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>' ]

필수 파라미터 (Required parameters)

*name*

카탈로그 통합의 식별자(이름)를 지정하는 문자열이에요. 계정 내에서 고유해야 해요.

식별자는 영문자로 시작해야 하고, 전체 식별자 문자열을 큰따옴표로 감싸지 않는 한 공백이나 특수 문자를 포함할 수 없어요(예: "My object"). 큰따옴표로 감싼 식별자는 대소문자를 구분해요.

자세한 내용은 Identifier requirements를 참고하세요.

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://<account_locator>.<cloud_region_id>.<cloud>.snowflakecomputing.com/polaris/api/catalog

  참고

  • Snowflake 조직 이름(orgname)을 찾으려면 Finding the organization and account name for an account의 단계를 따라요.

  • <my-snowflake-open-catalog-account-name을 찾으려면 Snowflake Open Catalog 문서의 Find the account name for a Snowflake Open Catalog account를 참고하세요.

  • <account_locator>, <cloud_region_id>, <cloud>를 찾으려면 Format 2: Account locator in a region을 참고하세요.

• https://<open_catalog_privatelink_account_url>/polaris/api/catalog: CATALOG_API_TYPE = PRIVATE일 때.

  참고

  open_catalog_privatelink_account_url에는 다음 값 중 하나를 입력해요:

  • PrivateLink Account URL

  • Regionless PrivateLink Account 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 }

외부 클라우드 스토리지의 Iceberg 테이블 파일에 접근할 때 사용할 접근 위임 모드를 지정해요.

• VENDED_CREDENTIALS는 Snowflake가 vended 자격 증명을 사용해야 함을 지정해요.

• 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 문서의 External OAuth를 참고하세요. OAuth ID 제공자가 지정되지 않으면 Snowflake는 원격 카탈로그 제공자가 ID 제공자라고 가정해요.

중요

프라이빗 연결(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 테이블은 테이블 정의의 카탈로그에 접근할 수 없어요.

값은 대소문자를 구분하지 않아요.

기본값은 TRUE예요.

선택 파라미터 (Optional parameters)

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

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

Delta 기반 테이블의 경우 외부 클라우드 스토리지에서 새 메타데이터를 폴링하는 시도 사이에 Snowflake가 기다리는 시간(초)을 지정해요.

값: 30~86400(포함)

기본값: 30초

COMMENT = '*string_literal*'

통합에 대한 주석을 지정하는 문자열(리터럴)이에요.

기본값: 값 없음

접근 제어 요구사항 (Access control requirements)

이 작업을 실행하는 역할은 최소한 다음 권한을 가져야 해요:

Privilege	Object	Notes
CREATE INTEGRATION	Account	기본적으로 ACCOUNTADMIN 역할만 이 권한을 가져요. 필요에 따라 다른 역할에도 부여할 수 있어요.

사용 참고사항 (Usage notes)

• 기존 카탈로그 통합은 수정할 수 없어요. 대신 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 서비스를 사용할 때 메타데이터로 개인 데이터(User 객체 외), 민감 데이터, 수출 통제 데이터 또는 기타 규제 데이터를 입력하지 않도록 해야 해요. 자세한 내용은 Metadata fields in Snowflake를 참고하세요.

• OR REPLACE와 IF NOT EXISTS 절은 상호 배타적이에요. 같은 문에서 둘 다 사용할 수 없어요.

• CREATE OR REPLACE <object> 문은 원자적이에요. 즉 객체를 교체할 때 기존 객체가 삭제되고 새 객체가 단일 트랜잭션으로 만들어져요.

• 카탈로그 통합 만들기에 문제가 있으면 You can't create a catalog integration for Open Catalog를 참고하세요.

예제 (Examples)

Open Catalog의 내부 카탈로그에서 특정 네임스페이스용 카탈로그 통합을 만들어 Snowflake에서 이 네임스페이스 아래에 그룹화된 테이블을 쿼리하는 예제예요. Open Catalog의 내부 카탈로그에 대한 자세한 내용은 Open Catalog 문서의 Catalog types를 참고하세요.

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의 외부 카탈로그인 customers 카탈로그로 Snowflake 관리 테이블을 동기화하기 위한 카탈로그 통합을 만드는 예제예요. Open Catalog의 외부 카탈로그에 대한 자세한 내용은 Open Catalog 문서의 Catalog types를 참고하세요.

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;

더 알아보기 (Learn more)

ALTER CATALOG INTEGRATION, DROP CATALOG INTEGRATION, SHOW CATALOG INTEGRATIONS, DESCRIBE CATALOG INTEGRATION