CREATE CATALOG INTEGRATION

CREATE CATALOG INTEGRATION (Delta Sharing)

원격 Delta Sharing 서버에서 공유되는 Delta 테이블용 카탈로그 통합(catalog integration)을 계정에 새로 만들거나 기존 카탈로그 통합을 교체하는 명령이에요.

출처: 문서

본문

Delta Sharing 카탈로그 통합을 만든 뒤에는 카탈로그 연결 데이터베이스(catalog-linked database)와 함께 사용해 Snowflake에서 공유된 Delta 테이블을 읽을 수 있어요.

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

구문 (Syntax)

CREATE [ OR REPLACE ] CATALOG INTEGRATION [ IF NOT EXISTS ] <name>
  CATALOG_SOURCE = DELTA_SHARING
  TABLE_FORMAT = DELTA
  REST_CONFIG = (
    CATALOG_URI = '<delta_sharing_endpoint_url>'
    CATALOG_NAME = 'shares/<share_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    restAuthenticationParams
  )
  ENABLED = { TRUE | FALSE }
  [ COMMENT = '<string_literal>' ]

restAuthenticationParams는 인증 방법에 따라 달라져요:

Bearer token

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'

OIDC

restAuthenticationParams (for OIDC) ::=

  TYPE = OIDC
  OIDC_AUDIENCE = '<audience>'

OAuth

restAuthenticationParams (for OAuth) ::=

  TYPE = OAUTH
  OAUTH_CLIENT_ID = '<oauth_client_id>'
  OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
  OAUTH_TOKEN_URI = 'https://<token_server_uri>'

파라미터 (Parameters)

*name*

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

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

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

CATALOG_SOURCE = DELTA_SHARING

카탈로그 소스가 오픈 소스 Delta Sharing 프로토콜을 준수하는 서버임을 지정해요.

TABLE_FORMAT = DELTA

카탈로그가 제공하는 테이블 형식으로 DELTA를 지정해요. Delta Sharing 카탈로그 통합은 Delta 테이블만 지원해요.

ENABLED = { TRUE | FALSE }

카탈로그 통합을 사용할 수 있는지 여부를 지정해요.

  • TRUE는 사용자가 카탈로그 연결 데이터베이스와 함께 이 통합을 사용할 수 있게 해요.

  • FALSE는 사용자가 카탈로그 연결 데이터베이스와 함께 이 통합을 사용하지 못하게 해요.

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

기본값은 TRUE예요.

COMMENT = '*string_literal*'

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

기본값: 값 없음

REST 구성 파라미터 (restConfigParams)

CATALOG_URI = '*delta_sharing_endpoint_url*'

Delta Sharing 서버의 엔드포인트 URL이에요. Databricks Unity Catalog의 경우 Databricks가 생성하는 수신자 자격 증명 파일의 endpoint 값이에요.

예:

https://oregon.cloud.databricks.com/api/2.0/delta-sharing/metastores/46d301b9-1b7d-48ea-9d2a-48efb54bd280

CATALOG_NAME = 'shares/*share_name*'

사용할 Delta Sharing 공유(share)를 shares/<share_name> 형식으로 지정해요. 공유 이름은 Delta Sharing 서버가 수신자에게 노출하는 공유의 이름이에요.

예를 들어 공유 이름이 sales_share라면 CATALOG_NAME = 'shares/sales_share'로 지정해요.

ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS

카탈로그 통합이 클라우드 스토리지의 기본 테이블 데이터에 접근하기 위해 Delta Sharing 서버가 반환하는 vended 자격 증명을 사용함을 지정해요.

Delta Sharing에서는 vended 자격 증명이 유일하게 지원되는 접근 위임 모드예요.

REST 인증 파라미터 (restAuthenticationParams)

Delta Sharing 카탈로그 통합은 bearer-token, OIDC 페더레이션, OAuth 클라이언트 자격 증명 인증을 지원해요.

Bearer token

TYPE = BEARER

Snowflake가 Delta Sharing 서버에 연결할 때 사용할 인증 유형으로 bearer token을 지정해요.

BEARER_TOKEN = '*bearer_token*'

Delta Sharing 서버가 수신자에게 발급한 bearer token이에요. Databricks Unity Catalog의 경우 Databricks가 생성하는 수신자 자격 증명 파일의 bearerToken 값이에요.

OIDC

TYPE = OIDC

OpenID Connect 페더레이션을 인증 유형으로 지정해요. Snowflake가 워크로드 ID 공급자 역할을 하며 단기 유효 JWT 토큰을 Delta Sharing 서버에 제시해요.

OIDC 인증으로 카탈로그 통합을 만든 뒤에는 DESCRIBE CATALOG INTEGRATION을 실행해 WORKLOAD_IDENTITY_FEDERATION_ISSUER와 WORKLOAD_IDENTITY_FEDERATION_SUBJECT 값을 가져와요. 이 값들을 OIDC_AUDIENCE 값과 함께 Delta Sharing 제공자에게 제공하면 제공자가 OIDC 수신자 정책을 구성할 수 있어요.

OIDC_AUDIENCE = '*audience*'

Delta Sharing 서버의 OIDC 수신자 정책이 Snowflake가 제시하는 JWT 토큰에서 기대하는 audience 값이에요.

audience 값은 Delta Sharing 제공자가 OIDC 수신자 정책에서 구성하는 audience와 일치해야 해요.

OAuth

TYPE = OAUTH

인증 유형으로 OAuth 클라이언트 자격 증명을 지정해요. Snowflake가 클라이언트 ID와 시크릿을 구성된 토큰 엔드포인트와 교환해 액세스 토큰을 얻고, 그 토큰으로 Delta Sharing 서버에 인증해요.

OAUTH_CLIENT_ID = '*oauth_client_id*'

Delta Sharing 제공자의 ID 제공자가 발급한 OAuth2 클라이언트 ID예요.

OAUTH_CLIENT_SECRET = '*oauth_client_secret*'

Delta Sharing 제공자의 ID 제공자가 발급한 OAuth2 클라이언트 시크릿이에요.

OAUTH_TOKEN_URI = 'https://*token_server_uri*'

Delta Sharing 서버용 액세스 토큰을 발급하는 OAuth ID 제공자의 토큰 엔드포인트 URL이에요.

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

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

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

사용 참고사항 (Usage notes)

  • Delta Sharing 카탈로그 통합은 공유된 Delta 테이블에 읽기 전용 접근을 제공해요. Delta Sharing 카탈로그 통합을 사용하는 카탈로그 연결 데이터베이스는 쓰기 작업을 지원하지 않아요.

  • 기존 카탈로그 통합은 수정할 수 없어요. 대신 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> 문은 원자적이에요. 즉 객체를 교체할 때 기존 객체가 삭제되고 새 객체가 단일 트랜잭션으로 만들어져요.

예제 (Examples)

bearer-token 인증으로 Delta Sharing 카탈로그 통합을 만드는 예제예요:

CREATE OR REPLACE CATALOG INTEGRATION my_delta_sharing_int
  CATALOG_SOURCE = DELTA_SHARING
  TABLE_FORMAT = DELTA
  REST_CONFIG = (
    CATALOG_URI = '<endpoint_from_credential>'
    CATALOG_NAME = 'shares/<share_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = BEARER
    BEARER_TOKEN = '<bearer_token_from_credential>'
  )
  ENABLED = TRUE;

OIDC 페더레이션 인증으로 Delta Sharing 카탈로그 통합을 만드는 예제예요:

CREATE OR REPLACE CATALOG INTEGRATION my_delta_sharing_int_oidc
  CATALOG_SOURCE = DELTA_SHARING
  TABLE_FORMAT = DELTA
  REST_CONFIG = (
    CATALOG_URI = '<recipient_endpoint>'
    CATALOG_NAME = 'shares/<share_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = OIDC
    OIDC_AUDIENCE = '<audience>'
  )
  ENABLED = TRUE;

OAuth 클라이언트 자격 증명 인증으로 Delta Sharing 카탈로그 통합을 만드는 예제예요:

CREATE OR REPLACE CATALOG INTEGRATION my_delta_sharing_int_oauth
  CATALOG_SOURCE = DELTA_SHARING
  TABLE_FORMAT = DELTA
  REST_CONFIG = (
    CATALOG_URI = '<recipient_endpoint>'
    CATALOG_NAME = 'shares/<share_name>'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = OAUTH
    OAUTH_CLIENT_ID = '<oauth_client_id>'
    OAUTH_CLIENT_SECRET = '<oauth_client_secret>'
    OAUTH_TOKEN_URI = 'https://<token_server_uri>'
  )
  ENABLED = TRUE;

단계별 안내는 Configure a catalog integration for Delta Sharing를 참고하세요.

더 알아보기 (Learn more)

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