CREATE CATALOG INTEGRATION

CREATE CATALOG INTEGRATION (Object storage)

다음 소스용 카탈로그 통합(catalog integration)을 계정에 새로 만들거나 기존 카탈로그 통합을 교체하는 명령이에요:

  • Apache Iceberg™ 메타데이터 파일

  • Delta Lake 메타데이터 파일

출처: 문서

본문

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

구문 (Syntax)

CREATE [ OR REPLACE ] CATALOG INTEGRATION [IF NOT EXISTS]
  <name>
  CATALOG_SOURCE = OBJECT_STORE
  TABLE_FORMAT = { ICEBERG | DELTA }
  ENABLED = { TRUE | FALSE }
  [ REFRESH_INTERVAL_SECONDS = <value> ]
  [ COMMENT = '<string_literal>' ]

필수 파라미터 (Required parameters)

*name*

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

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

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

CATALOG_SOURCE = OBJECT_STORE

소스로 객체 스토리지의 외부 Iceberg 메타데이터 파일 또는 Delta 파일을 지정해요.

TABLE_FORMAT = { ICEBERG | DELTA }

테이블 형식을 지정해요.

  • ICEBERG: Glue Iceberg 테이블 또는 외부 클라우드 스토리지 위치의 메타데이터에서 가져온 Iceberg 테이블을 지정해요.

  • DELTA: 객체 스토리지의 Delta Lake 데이터를 지정해요(CREATE ICEBERG TABLE (Delta files in object storage), Delta Direct).

ENABLED = { TRUE | FALSE }

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

  • TRUE는 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들 수 있게 해요. 이 통합을 참조하는 기존 Iceberg 테이블은 정상적으로 작동해요.

  • FALSE는 사용자가 이 통합을 참조하는 새 Iceberg 테이블을 만들지 못하게 해요. 이 통합을 참조하는 기존 Iceberg 테이블은 테이블 정의의 카탈로그에 접근할 수 없어요.

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

기본값은 TRUE예요.

선택 파라미터 (Optional parameters)

REFRESH_INTERVAL_SECONDS = value

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

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

값: 30~86400(포함)

기본값: 30초

참고

이 유형의 카탈로그 통합에서는 REFRESH_INTERVAL_SECONDS 파라미터가 TABLE_FORMAT = DELTA일 때만 지원돼요.

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

  • Apache Iceberg™ 테이블 자동 새로고침은 이 유형의 카탈로그 통합에서 TABLE_FORMAT = DELTA일 때만 지원돼요.

  • 메타데이터에 관해: 고객은 Snowflake 서비스를 사용할 때 메타데이터로 개인 데이터(User 객체 외), 민감 데이터, 수출 통제 데이터 또는 기타 규제 데이터를 입력하지 않도록 해야 해요. 자세한 내용은 Metadata fields in Snowflake를 참고하세요.

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

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

예제 (Examples)

외부 클라우드 스토리지의 Iceberg 메타데이터를 사용하는 통합을 만드는 예제예요. OBJECT_STORE는 외부 볼륨(external volume)과 연결하는 객체 스토리지에 해당해요.

CREATE CATALOG INTEGRATION myCatalogInt
  CATALOG_SOURCE = OBJECT_STORE
  TABLE_FORMAT = ICEBERG
  ENABLED = TRUE;

더 알아보기 (Learn more)

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