CREATE ICEBERG TABLE

CREATE ICEBERG TABLE (Snowflake as the Iceberg catalog)

현재/지정한 스키마에 Snowflake를 Iceberg 카탈로그로 사용하는 Apache Iceberg™ 테이블을 만들거나 교체하는 명령이에요.

출처: 문서

본문

이 명령은 다음 변형(variant)을 지원해요:

  • CREATE ICEBERG TABLE … AS SELECT (CTAS): 데이터가 채워진 테이블 생성.
  • CREATE ICEBERG TABLE … LIKE: 기존 테이블의 빈 복사본 생성.
  • CREATE ICEBERG TABLE … CLONE: 기존 테이블의 복제본 생성 (Time Travel로 과거 시점 복제 포함).

Iceberg 데이터와 메타데이터를 클라우드 저장소에 저장하려면 외부 볼륨을 만들고 테이블에서 참조하세요. 대신 EXTERNAL_VOLUME = 'SNOWFLAKE_MANAGED'를 설정하면 Snowflake Storage를 사용할 수 있어요 (이 경우 별도 외부 볼륨 객체를 만들 필요 없어요).

구문 (Syntax)

CREATE [ OR REPLACE ] [ TRANSIENT ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name> (
    -- Column definition
    <col_name> <col_type> [ DEFAULT <col_default> ]
      [ inlineConstraint ]
      [ NOT NULL ]
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]
      [ [ WITH ] PROJECTION POLICY <policy_name> ]
      [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
      [ COMMENT '<string_literal>' ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ DEFAULT <col_default> ] [ ... ] ]

    -- Out-of-line constraints
    [ , outoflineConstraint [ ... ] ]
  )
  [ PARTITION BY ( partitionExpression [, partitionExpression , ...] ) ]
  [ PATH_LAYOUT = { FLAT | HIERARCHICAL } ]
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  [ BASE_LOCATION = '<directory_for_table_files>' ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ CATALOG_SYNC = '<open_catalog_integration_name>']
  [ STORAGE_SERIALIZATION_POLICY = { COMPATIBLE | OPTIMIZED } ]
  [ DATA_RETENTION_TIME_IN_DAYS = <integer> ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ CHANGE_TRACKING = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ COPY TAGS ]
  [ ERROR_LOGGING = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ ICEBERG_VERSION = <integer> ]
  [ ICEBERG_MERGE_ON_READ_BEHAVIOR = { 'AUTO' | 'ENABLED' | 'DISABLED' } ]
  [ ENABLE_ICEBERG_MERGE_ON_READ = { TRUE | FALSE } ]
  [ [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col_name> [ , <col_name> ... ] ) ]
  [ [ WITH ] AGGREGATION POLICY <policy_name> ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]
  [ ENABLE_DATA_COMPACTION = { TRUE | FALSE } ]

여기서:

inlineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  {   UNIQUE
    | PRIMARY KEY
    | [ FOREIGN KEY ] REFERENCES <ref_table_name> [ ( <ref_col_name> ) ]
    | CHECK ( <expr> )
  }
  [ <constraint_properties> ]

outoflineConstraint ::=
  [ CONSTRAINT <constraint_name> ]
  {   UNIQUE [ ( <col_name> [ , <col_name> , ... ] ) ]
    | PRIMARY KEY [ ( <col_name> [ , <col_name> , ... ] ) ]
    | [ FOREIGN KEY ] [ ( <col_name> [ , <col_name> , ... ] ) ]
      REFERENCES <ref_table_name> [ ( <ref_col_name> [ , <ref_col_name> , ... ] ) ]
    | CHECK ( <expr> )
  }
  [ <constraint_properties> ]

partitionExpression ::=
  <col_name> -- identity transform
  | BUCKET ( <num_buckets> , <col_name> )
  | TRUNCATE ( <width> , <col_name> )
  | YEAR ( <col_name> )
  | MONTH ( <col_name> )
  | DAY ( <col_name> )
  | HOUR ( <col_name> )

PRIMARY KEY로 정의된 컬럼은 Iceberg 메타데이터의 식별자 필드로 표현돼요. Snowflake는 PRIMARY KEY 컬럼의 NOT NULL/UNIQUE 제약 조건을 강제하지 않아요.

CREATE ICEBERG TABLE … AS SELECT (CTAS)

CREATE [ OR REPLACE ] [ TRANSIENT ] ICEBERG TABLE <table_name> [ ( <col_name> [ <col_type> ] [ DEFAULT <col_default> ] , ... ) ]
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  [ BASE_LOCATION = '<relative_path_from_external_volume>' ]
  [ COPY GRANTS ]
  [ COPY TAGS ]
  [ ICEBERG_VERSION = <integer> ]
  [ ... ]
  AS SELECT <query>

CTAS 문에서 컬럼에 마스킹 폴리시를 적용할 수 있고, 테이블에 행 접근 폴리시를 적용할 수 있어요. CTAS에서 COPY GRANTS는 OR REPLACE 절과 결합할 때만 유효해요 — CREATE OR REPLACE로 교체되는 테이블(이미 존재하는 경우)의 권한을 복사하지, SELECT 문에서 쿼리하는 소스 테이블의 권한이 아니에요.

CREATE ICEBERG TABLE <table_name> ( <col1> <data_type> [ DEFAULT <col_default> ] [ WITH ] MASKING POLICY <policy_name> [ , ... ] )
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = 'SNOWFLAKE' ]
  [ BASE_LOCATION = '<directory_for_table_files>' ]
  [ ICEBERG_VERSION = <integer> ]
  [ ... ]
  [ WITH ] ROW ACCESS POLICY <policy_name> ON ( <col1> [ , ... ] )
  AS SELECT <query>

CREATE ICEBERG TABLE … LIKE

기존 테이블과 동일한 컬럼 정의를 가지지만 데이터는 복사하지 않는 새 테이블을 만들어요:

CREATE [ OR REPLACE ] [ TRANSIENT ] ICEBERG TABLE <table_name> LIKE <source_table>
  [ CLUSTER BY ( <expr> [ , <expr> , ... ] ) ]
  [ COPY GRANTS ]
  [ COPY TAGS ]
  [ ... ]

CREATE ICEBERG TABLE … CLONE

소스 테이블의 모든 기존 데이터를 실제로 복사하지 않고 포함하는 새 Iceberg 테이블을 만들어요. Time Travel로 과거 특정 시점에 복제할 수도 있어요.

주요 매개변수

  • <table_name>: 테이블의 식별자예요. 스키마 내에서 고유해야 해요.
  • <col_name> <col_type>: 컬럼 이름과 데이터 타입을 지정해요.
  • EXTERNAL_VOLUME = '<external_volume_name>': Iceberg 데이터/메타데이터를 저장할 외부 볼륨을 지정해요. 'SNOWFLAKE_MANAGED'는 Snowflake Storage를 사용해요.
  • CATALOG = 'SNOWFLAKE': Snowflake를 Iceberg 카탈로그로 지정해요.
  • BASE_LOCATION = '<directory_for_table_files>': 테이블 파일을 위한 디렉터리를 지정해요.
  • PARTITION BY ( partitionExpression ... ): Iceberg 테이블의 파티션 표현식을 지정해요 (identity, BUCKET, TRUNCATE, YEAR, MONTH, DAY, HOUR 변환).
  • PATH_LAYOUT = { FLAT | HIERARCHICAL }: Parquet 파일의 경로 레이아웃을 지정해요.
  • TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }': 대상 Parquet 파일 크기를 지정해요.
  • ICEBERG_VERSION = <integer>: Iceberg 사양 버전. 기본 2 (Snowflake 관리 v3도 지원).
  • CLUSTER BY, DATA_RETENTION_TIME_IN_DAYS, MAX_DATA_EXTENSION_TIME_IN_DAYS, CHANGE_TRACKING, COPY GRANTS, COPY TAGS, ERROR_LOGGING, COMMENT, ROW ACCESS POLICY, AGGREGATION POLICY, MASKING POLICY(컬럼), TAG, WITH CONTACT, ENABLE_DATA_COMPACTION 등 매개변수를 지원해요.

더 알아보기 (Learn more)