CREATE CATALOG INTEGRATION(Apache Iceberg™ REST)¶

구문¶

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

여기서

restConfigParams ::=

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

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

전달자 토큰

restAuthenticationParams (for Bearer token) ::=

  TYPE = BEARER
  BEARER_TOKEN = '<bearer_token>'

SigV4

restAuthenticationParams (for SigV4) ::=

  TYPE = SIGV4
  SIGV4_IAM_ROLE = '<iam_role_arn>'
  SIGV4_SIGNING_REGION = '<region>'

매개 변수¶

name

카탈로그 통합에 대한 식별자(이름)를 지정하는 문자열로, 계정에서 고유해야 합니다.

또한, 식별자는 알파벳 문자로 시작해야 하며 전체 식별자 문자열을 큰따옴표(예: "My object")로 묶지 않는 한 공백이나 특수 문자를 포함할 수 없습니다. 큰따옴표로 묶인 식별자도 대/소문자를 구분합니다.

자세한 내용은 식별자 요구 사항 섹션을 참조하십시오.

CATALOG_SOURCE = ICEBERG_REST

카탈로그 원본이 Apache Iceberg REST 사양을 준수하는 REST 카탈로그임을 지정합니다.

TABLE_FORMAT = ICEBERG

ICEBERG를 카탈로그에서 제공하는 테이블 형식으로 지정합니다.

CATALOG_NAMESPACE = 'namespace'

외부 카탈로그의 네임스페이스를 지정합니다. Snowflake는 이 카탈로그 통합과 연결한 모든 Iceberg 테이블에 이 네임스페이스를 사용합니다.

테이블을 생성할 때 테이블 수준에서 네임스페이스를 지정하여 이 값을 재정의할 수 있습니다.

ENABLED = { TRUE | FALSE }

Iceberg 테이블에 카탈로그 통합을 사용할 수 있는지 여부를 지정합니다.

• TRUE 로 지정하면 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들 수 있습니다.

• FALSE 로 지정하면 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들지 못하게 됩니다.

REFRESH_INTERVAL_SECONDS = value

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

값: 30~86400(포함)

기본값: 30초

미리 보기 기능

모든 계정에서 사용 가능합니다.

COMMENT = 'string_literal'

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

기본값: 값 없음

REST 인증 매개 변수(restAuthenticationParams)¶

액세스 제어 요구 사항¶

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

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

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

사용법 노트¶

• 카탈로그 통합은 외부 Iceberg 카탈로그에 대한 읽기 전용 액세스 권한을 제공합니다.

• 기존 카탈로그 통합은 수정할 수 없으며, 대신 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의 메타데이터 필드 섹션을 참조하십시오.

• CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.

예¶

다음 예에서는 OAuth를 사용하여 Tabular에 연결하는 REST 카탈로그 통합을 만듭니다.

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;