CREATE ICEBERG TABLE

CREATE ICEBERG TABLE (Iceberg files in object storage)

현재/지정한 스키마에 객체 저장소(외부 클라우드 저장소)의 Iceberg 파일을 사용하는 Apache Iceberg™ 테이블을 만들거나 교체하는 명령이에요. 이 유형의 Iceberg 테이블은 카탈로그 인티그레이션(catalog integration)이 필요해요.

출처: 문서

본문

테이블을 만들기 전에 Iceberg 메타데이터와 데이터 파일이 저장될 외부 볼륨을 만들어야 해요. 또한 테이블용 카탈로그 인티그레이션도 필요해요.

구문 (Syntax)

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  METADATA_FILE_PATH = '<metadata_file_path>'
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

필수 매개변수

  • <table_name>: 테이블의 식별자예요. 스키마 내에서 고유해야 해요.
  • METADATA_FILE_PATH = 'metadata_file_path': 컬럼 정의에 사용할 Iceberg 메타데이터 파일의 상대 경로를 지정해요. 예를 들어 전체 경로가 s3://mybucket_us_east_1/metadata/v1.metadata.json이고 외부 볼륨 저장소 위치가 s3://mybucket_us_east_1/이라면 metadata/v1.metadata.json을 지정해요.
    • 파일 경로에 선행 슬래시(/)를 포함하지 마세요.
    • Snowflake 7.34 이전에는 이 매개변수가 METADATA_FILE_NAME이라고 불렸어요.
    • 7.34 이상에서는 객체 저장소의 Iceberg 파일로부터 테이블을 만들 때 BASE_LOCATION을 지정하지 않아요.

선택 매개변수

  • EXTERNAL_VOLUME = 'external_volume_name': Iceberg 테이블이 메타데이터 파일과 데이터를 Parquet 형식으로 저장하는 외부 볼륨의 식별자를 지정해요. 지정하지 않으면 스키마, 데이터베이스, 계정 순으로 기본값을 사용해요.
  • CATALOG = 'catalog_integration_name': 이 테이블의 카탈로그 인티그레이션 이름을 지정해요. 지정하지 않으면 기본값을 사용해요.
  • REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }: 쿼리 결과에서 잘못된 UTF-8 문자를 유니코드 대체 문자(�)로 바꿀지 지정해요. 외부 Iceberg 카탈로그를 사용하는 테이블에만 설정할 수 있어요. 기본값: FALSE.
  • COMMENT = 'string_literal': 테이블에 대한 주석을 지정해요.
  • TAG ( tag_name = 'tag_value' [ , ... ] ), WITH CONTACT ( ... ) 도 지원돼요.

접근 제어 요구 사항

권한 객체 참고
CREATE ICEBERG TABLE 스키마
CREATE EXTERNAL VOLUME 계정 새 외부 볼륨 생성 시 필요.
USAGE 외부 볼륨 기존 외부 볼륨 참조 시 필요.
CREATE INTEGRATION 계정 새 카탈로그 인티그레이션 생성 시 필요.
USAGE 카탈로그 인티그레이션 기존 카탈로그 인티그레이션 참조 시 필요.

사용법 참고 사항

  • 외부 볼륨/카탈로그 인티그레이션을 큰따옴표로 감싼 식별자로 만들었다면 CREATE ICEBERG TABLE 문에서도 그대로 지정해야 해요. 포함하지 않으면 Object does not exist 오류가 발생할 수 있어요.
  • 구버전 구문(BASE_LOCATION, 이전의 FILE_PATH)을 사용하는 스크립트는 계속 실행할 수 있어요. 그 경우 Parquet 데이터 파일과 Iceberg 메타데이터 파일이 BASE_LOCATION 내에 있어야 해요.

더 알아보기 (Learn more)