CREATE CATALOG INTEGRATION

CREATE CATALOG INTEGRATION (Apache Iceberg™ REST)

오픈 소스 Apache Iceberg™ REST OpenAPI 사양을 준수하는 원격 카탈로그에서 관리되는 Apache Iceberg™ 테이블용 카탈로그 통합(catalog integration)을 계정에 새로 만들거나 기존 카탈로그 통합을 교체하는 명령이에요.

출처: 문서

본문

참고

Snowflake Open Catalog용 통합을 만들려면 CREATE CATALOG INTEGRATION (Snowflake Open Catalog)을 대신 참고하세요.

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

구문 (Syntax)

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>' ]
  [ CATALOG_NAME = '<catalog_name>' ]
  [ CATALOG_API_TYPE = { PUBLIC | PRIVATE | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY
                         | AWS_GLUE | AWS_PRIVATE_GLUE
                         | AWS_S3TABLES | AWS_PRIVATE_S3TABLES } ]
  [ ACCESS_DELEGATION_MODE = { VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS } ]

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

Bearer token

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>' ]
  [ SIGV4_EXTERNAL_ID = '<external_id>' ]

파라미터 (Parameters)

*name*

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

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

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

CATALOG_SOURCE = ICEBERG_REST

카탈로그 소스가 Apache Iceberg REST 사양을 준수하는 REST 카탈로그임을 지정해요.

TABLE_FORMAT = ICEBERG

카탈로그가 제공하는 테이블 형식으로 ICEBERG를 지정해요.

CATALOG_NAMESPACE = '*namespace*'

외부 카탈로그의 네임스페이스를 선택적으로 지정해요. Snowflake는 이 통합과 연결하는 모든 Iceberg 테이블에 이 네임스페이스를 사용해요.

지정하면 CREATE ICEBERG TABLE (Iceberg REST catalog)의 CATALOG_NAMESPACE 파라미터를 사용해 테이블 수준에서 이 값을 덮어쓸 수 있어요. 지정하지 않으면 CREATE ICEBERG TABLE (Iceberg REST catalog)의 CATALOG_NAMESPACE 파라미터를 사용해 테이블 수준에서 설정해야 해요.

ENABLED = { TRUE | FALSE }

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

  • TRUE는 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들 수 있게 해요.

  • FALSE는 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들지 못하게 해요.

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

기본값은 TRUE예요.

REFRESH_INTERVAL_SECONDS = value

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

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

값: 30~86400(포함)

기본값: 30초

COMMENT = '*string_literal*'

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

기본값: 값 없음

REST 구성 파라미터 (restConfigParams)

CATALOG_URI = '*rest_api_endpoint_url*'

카탈로그 REST API의 엔드포인트 URL이에요. AWS Glue REST의 경우 AWS Glue Iceberg REST 카탈로그의 서비스 엔드포인트를 지정해요.

PREFIX

모든 API 경로에 추가할 접두사를 선택적으로 지정해요.

CATALOG_API_TYPE = { PUBLIC | PRIVATE | AWS_API_GATEWAY | AWS_PRIVATE_API_GATEWAY | AWS_GLUE | AWS_PRIVATE_GLUE | AWS_S3TABLES | AWS_PRIVATE_S3TABLES }

카탈로그 API의 연결 유형을 지정해요. SigV4 인증에는 필수이며, 그 외에는 선택사항이에요.

  • PUBLIC은 Amazon API Gateway로 관리되지 않고 공개적으로 접근 가능한 API를 지정해요. 비-SigV4 API에 사용해요.

  • PRIVATE는 Databricks Unity Catalog나 일반 Iceberg REST 카탈로그 같은 카탈로그가 프라이빗 엔드포인트를 통해 접근 가능함을 지정해요. 자세한 내용은 Configure an Apache Iceberg™ REST catalog integration with outbound private connectivity를 참고하세요.

  • AWS_API_GATEWAY는 Amazon API Gateway로 관리되는 공용 API를 지정해요.

  • AWS_PRIVATE_API_GATEWAY는 Amazon API Gateway로 관리되는 프라이빗 API를 지정해요.

  • AWS_GLUE는 AWS Glue REST 카탈로그가 공개적으로 접근 가능함을 지정해요. 이 옵션에서는 CATALOG_NAME 값도 반드시 지정해야 해요.

  • AWS_PRIVATE_GLUE는 AWS Glue REST 카탈로그가 프라이빗 엔드포인트를 통해 접근 가능함을 지정해요. 이 옵션에서는 CATALOG_NAME 값도 반드시 지정해야 해요. 자세한 내용은 Configure an Apache Iceberg™ REST catalog integration with outbound private connectivity를 참고하세요.

  • AWS_S3TABLES는 Amazon S3 Tables Iceberg REST 엔드포인트가 공개적으로 접근 가능함을 지정해요. 이 옵션에서는 CATALOG_NAME(S3 Tables 버킷 ARN) 값도 반드시 지정하고 ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS로 설정해야 해요. 자세한 내용은 Configure a catalog integration for Amazon S3 Tables를 참고하세요.

  • AWS_PRIVATE_S3TABLES는 Amazon S3 Tables Iceberg REST 엔드포인트가 프라이빗 엔드포인트를 통해 접근 가능함을 지정해요. 이 옵션에서는 CATALOG_NAME(S3 Tables 버킷 ARN) 값도 반드시 지정하고 ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS로 설정해야 해요. 자세한 내용은 Configure a catalog integration for Amazon S3 Tables를 참고하세요.

기본값: PUBLIC

CATALOG_NAME

원격 카탈로그 서비스에 요청할 카탈로그 또는 식별자를 지정해요.

CATALOG_API_TYPE = AWS_GLUE를 사용할 때는 이 파라미터에 AWS 계정의 ID를 지정해요.

CATALOG_API_TYPE = AWS_S3TABLES 또는 CATALOG_API_TYPE = AWS_PRIVATE_S3TABLES를 사용할 때는 S3 Tables 버킷의 ARN을 지정해요(예: arn:aws:s3tables:us-west-2:123456789012:bucket/my_table_bucket).

이 파라미터는 일부 타사 카탈로그 서비스에서 필수예요. 카탈로그 이름을 지정해야 하는지 카탈로그 제공자에게 확인하세요.

참고

Snowflake 9.6 버전 이전에는 이 파라미터를 WAREHOUSE라고 불렀어요. Snowflake는 여전히 WAREHOUSE를 인식하지만 CATALOG_NAME을 사용하는 것을 권장해요.

ACCESS_DELEGATION_MODE = { VENDED_CREDENTIALS | EXTERNAL_VOLUME_CREDENTIALS }

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

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

  • EXTERNAL_VOLUME_CREDENTIALS는 Snowflake가 외부 볼륨을 사용해야 함을 지정해요.

기본값: EXTERNAL_VOLUME_CREDENTIALS

REST 인증 파라미터 (restAuthenticationParams)

OAuth

TYPE = OAUTH

Snowflake가 Iceberg REST 카탈로그에 연결할 때 사용할 인증 유형으로 OAuth를 지정해요.

OAUTH_TOKEN_URI = *token_server_uri*

타사 ID 제공자의 선택적 URL이에요. 지정하지 않으면 Snowflake는 원격 카탈로그 제공자가 OAuth ID 제공자라고 가정해요.

OAUTH_CLIENT_ID = *oauth_client_id*

OAuth2 클라이언트 ID예요.

OAUTH_CLIENT_SECRET = *oauth_client_secret*

OAuth2 클라이언트 시크릿이에요.

OAUTH_ALLOWED_SCOPES = ( '*scope_1*', '*scope_2*' )

OAuth 토큰의 범위예요. Iceberg REST API 사양에는 범위가 하나만 포함되지만 카탈로그는 구현에서 여러 범위를 지원할 수 있어요.

Bearer token

TYPE = BEARER

Snowflake가 Iceberg REST 카탈로그에 연결할 때 사용할 인증 유형으로 bearer token을 지정해요.

BEARER_TOKEN = *bearer_token*

ID 제공자의 bearer token이에요. 개인 액세스 토큰(PAT)을 지정할 수도 있어요.

SigV4

TYPE = SIGV4

Snowflake가 Iceberg REST 카탈로그에 연결할 때 사용할 인증 유형으로 Signature Version 4를 지정해요.

SIGV4_IAM_ROLE = '*iam_role_arn*'

API Gateway의 REST API에 접근할 권한이 있는 IAM 역할의 Amazon Resource Name(ARN)을 지정해요.

SIGV4_SIGNING_REGION = '*region*'

API Gateway에서 API와 연결된 AWS 리전을 선택적으로 지정해요. 이 파라미터를 지정하지 않으면 Snowflake는 Snowflake 계정이 배포된 리전을 사용해요.

SIGV4_EXTERNAL_ID = '*external_id*'

Snowflake가 AWS와 신뢰 관계를 구축하는 데 사용하는 외부 ID를 선택적으로 지정해요. 이 카탈로그 통합용으로 구성한 IAM 역할의 신뢰 정책에 같은 외부 ID를 지정해야 해요.

이 파라미터에 값을 지정하지 않으면 Snowflake는 카탈로그 통합을 만들(또는 교체) 때 고유한 외부 ID를 자동 생성해요.

외부 ID에 대한 자세한 내용은 How to use an external ID when granting access to your AWS resources to a third party를 참고하세요.

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

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

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

사용 참고사항 (Usage notes)

  • 카탈로그 통합은 외부 Iceberg 카탈로그에 읽기 전용 접근을 제공해요.

  • 기존 카탈로그 통합은 수정할 수 없어요. 대신 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)

OAuth를 사용해 Tabular에 연결하는 REST 카탈로그 통합을 만드는 예제예요. CATALOG_NAMESPACE 파라미터로 기본 네임스페이스를 설정해요.

테이블 수준에서 기본 네임스페이스를 덮어쓰려면 CREATE ICEBERG TABLE의 CATALOG_NAMESPACE 파라미터를 사용해요.

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'
    CATALOG_NAME = '<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;

SigV4 인증으로 AWS Glue REST용 카탈로그 통합을 만드는 예제예요:

CREATE CATALOG INTEGRATION glue_rest_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  CATALOG_NAMESPACE = 'rest_catalog_integration'
  REST_CONFIG = (
    CATALOG_URI = 'https://glue.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_GLUE
    CATALOG_NAME = '123456789012'
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;

SigV4 인증과 catalog-vended 자격 증명으로 Amazon S3 Tables Iceberg REST 엔드포인트용 카탈로그 통합을 만드는 예제예요. CATALOG_NAME은 S3 Tables 버킷의 ARN이고 ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS가 필수예요:

CREATE CATALOG INTEGRATION s3tables_catalog_int
  CATALOG_SOURCE = ICEBERG_REST
  TABLE_FORMAT = ICEBERG
  REST_CONFIG = (
    CATALOG_URI = 'https://s3tables.us-west-2.amazonaws.com/iceberg'
    CATALOG_API_TYPE = AWS_S3TABLES
    CATALOG_NAME = 'arn:aws:s3tables:us-west-2:123456789012:bucket/my_table_bucket'
    ACCESS_DELEGATION_MODE = VENDED_CREDENTIALS
  )
  REST_AUTHENTICATION = (
    TYPE = SIGV4
    SIGV4_IAM_ROLE = 'arn:aws:iam::123456789012:role/my-role'
    SIGV4_SIGNING_REGION = 'us-west-2'
  )
  ENABLED = TRUE;

아웃바운드 프라이빗 연결에 AWS_PRIVATE_S3TABLES를 사용하려면 Configure a catalog integration for Amazon S3 Tables를 참고하세요.

다른 인증 옵션을 다루는 예제는 Configure a catalog integration for Apache Iceberg™ REST catalogs를 참고하세요.

더 알아보기 (Learn more)

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