CREATE ICEBERG TABLE(Iceberg REST 카탈로그)¶

Iceberg REST 카탈로그에 대한 현재/지정된 스키마에 Apache Iceberg™ 테이블 을 생성하거나 바꿉니다.

다음 시나리오에서는 이 명령을 사용합니다.

오픈 소스 Apache Iceberg REST OpenAPI 사양 을 준수하는 원격 Iceberg 카탈로그를 사용하려고 합니다.
Snowflake Open Catalog 또는 Apache Polaris™의 테이블을 쿼리하려는 경우. 자세한 내용은 Snowflake를 사용하여 Snowflake Open Catalog 의 테이블 쿼리하기 섹션을 참조하세요.
카탈로그 연결 데이터베이스 에서 쓰기 지원을 사용하여 외부 관리형 테이블을 생성하려는 경우. CREATE ICEBERG TABLE(카탈로그 연결 데이터베이스) 섹션을 참조하십시오.

참고

테이블을 만들기 전에 Iceberg 메타데이터와 데이터 파일이 저장되는 외부 볼륨 을 만들어야 합니다. 자세한 지침은 외부 볼륨 구성 섹션을 참조하십시오.

테이블에 대한 카탈로그 통합도 필요합니다. 자세한 내용은 Apache Iceberg™ REST 카탈로그에 대한 카탈로그 통합 구성 또는 Snowflake Open Catalog 의 카탈로그 통합 구성하기 섹션을 참조하십시오.

참고 항목:: ALTER ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE , UNDROP ICEBERG TABLE

구문¶

CREATE [ OR REPLACE ] ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [ EXTERNAL_VOLUME = '<external_volume_name>' ]
  [ CATALOG = '<catalog_integration_name>' ]
  CATALOG_TABLE_NAME = '<rest_catalog_table_name>'
  [ CATALOG_NAMESPACE = '<catalog_namespace>' ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]
  [ WITH CONTACT ( <purpose> = <contact_name> [ , <purpose> = <contact_name> ... ] ) ]

Copy

베리언트 구문¶

CREATE ICEBERG TABLE(카탈로그 연결 데이터베이스)¶

CREATE ICEBERG TABLE [ IF NOT EXISTS ] <table_name>
  [
    --Column definition
    <col_name> <col_type>
      [ [ WITH ] MASKING POLICY <policy_name> [ USING ( <col_name> , <cond_col1> , ... ) ] ]

    -- Additional column definitions
    [ , <col_name> <col_type> [ ... ] ]
  ]
  [ PARTITION BY ( partitionExpression [ , partitionExpression , ... ] ) ]
  [ TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }' ]
  [ MAX_DATA_EXTENSION_TIME_IN_DAYS = <integer> ]
  [ AUTO_REFRESH = { TRUE | FALSE } ]
  [ REPLACE_INVALID_CHARACTERS = { TRUE | FALSE } ]
  [ COPY GRANTS ]
  [ COMMENT = '<string_literal>' ]
  [ [ WITH ] TAG ( <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' , ... ] ) ]

Copy

CREATE ICEBERG TABLE(카탈로그 연결 데이터베이스) … AS SELECT¶

CREATE ICEBERG TABLE <table_name> [ ( <col_name> [ <col_type> ] , <col_name> [ <col_type> ] , ... ) ]
  [ ... ]
  AS SELECT <query>

Copy

CTAS 문의 열에 마스킹 정책을 적용할 수 있습니다. 열 데이터 타입 뒤에 마스킹 정책을 지정합니다. 예:

CREATE ICEBERG TABLE <table_name> ( <col1> <data_type> [ WITH ] MASKING POLICY <policy_name> [ , ... ] )
  [ ... ]
  AS SELECT <query>

Copy

필수 매개 변수¶

table_name

Snowflake에서 테이블의 식별자(이름)를 지정하며, 테이블이 생성되는 스키마에 대해 고유해야 합니다.

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

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

참고

원격 카탈로그에서 테이블 또는 네임스페이스 목록을 검색하려면 다음 함수를 사용하면 됩니다.

CATALOG_TABLE_NAME = 'rest_catalog_table_name'

외부 카탈로그에서 인식되는 테이블 이름을 지정합니다. 테이블을 생성한 후에는 이 매개 변수를 변경할 수 없습니다.

참고

테이블 이름(mynamespace.mytable)으로 네임스페이스를 지정하지 마십시오. 이 테이블의 네임스페이스를 지정하고 카탈로그 통합을 위해 설정된 기본 네임스페이스를 재정의하려면 CATALOG_NAMESPACE 매개 변수를 사용하십시오.

col_name

카탈로그 연결 데이터베이스(미리 보기) 에서 테이블을 생성하기 위한 것입니다.

열 식별자(이름)를 지정합니다. 테이블 식별자에 대한 모든 요구 사항은 열 식별자에도 적용됩니다.

자세한 내용은 식별자 요구 사항 및 예약된 키워드와 제한된 키워드 섹션을 참조하십시오.

참고

표준 예약 키워드 외에, 다음 키워드는 ANSI 표준 컨텍스트 함수용으로 예약되어 있으므로 열 식별자로 사용할 수 없습니다.

CURRENT_DATE
CURRENT_ROLE
CURRENT_TIME
CURRENT_TIMESTAMP
CURRENT_USER

예약된 키워드의 목록은 예약된 키워드와 제한된 키워드 를 참조하십시오.

col_type

카탈로그 연결 데이터베이스(미리 보기) 에서 테이블을 생성하기 위한 것입니다.

열의 데이터 타입을 지정합니다.

테이블 열에 지정할 수 있는 데이터 타입에 대한 자세한 내용은 Apache Iceberg™ 테이블의 데이터 타입 섹션을 참조하십시오.

선택적 매개 변수¶

MASKING POLICY = policy_name

카탈로그 연결 데이터베이스(미리 보기) 에서 테이블을 생성하기 위한 것입니다.

열에 설정할 마스킹 정책 을 지정합니다. 마스킹 정책은 표준 Snowflake 데이터베이스(카탈로그 연결 데이터베이스가 아님)에 속해야 합니다.

EXTERNAL_VOLUME = 'external_volume_name'

Iceberg 테이블이 메타데이터 파일과 데이터를 Parquet 형식으로 저장하는 외부 볼륨의 식별자(이름)를 지정합니다. Iceberg 메타데이터 및 매니페스트 파일은 테이블 스키마, 파티션, 스냅샷, 기타 메타데이터를 저장합니다.

이 매개 변수를 지정하지 않으면 Iceberg 테이블은 기본적으로 스키마, 데이터베이스 또는 계정의 외부 볼륨으로 설정됩니다. 스키마는 데이터베이스보다 우선하고, 데이터베이스는 계정보다 우선합니다.

CATALOG = 'catalog_integration_name'

이 테이블에 대한 카탈로그 통합의 식별자(이름)를 지정합니다.

이 매개 변수를 지정하지 않으면 Iceberg 테이블은 기본적으로 스키마, 데이터베이스 또는 계정의 카탈로그 통합으로 설정됩니다. 스키마는 데이터베이스보다 우선하고, 데이터베이스는 계정보다 우선합니다.

CATALOG_NAMESPACE = 'catalog_namespace'

선택적으로 REST 카탈로그 원본에 대한 네임스페이스(예: my_database)를 지정합니다. 카탈로그 통합으로 네임스페이스를 지정한 다음 테이블 수준에서 단일 REST 카탈로그 통합을 사용하여 여러 데이터베이스에 걸쳐 Iceberg 테이블을 만들 수 있습니다. 테이블에 네임스페이스를 지정하지 않으면 테이블은 카탈로그 통합과 연결된 기본 카탈로그 네임스페이스를 사용합니다.
카탈로그 통합으로 기본 네임스페이스가 지정되지 않은 경우 테이블의 카탈로그 네임스페이스를 설정하려면 REST 카탈로그 원본에 대한 네임스페이스를 지정해야 합니다.

참고

원격 카탈로그에서 테이블 또는 네임스페이스 목록을 검색하려면 다음 함수를 사용하면 됩니다.

TARGET_FILE_SIZE = '{ AUTO | 16MB | 32MB | 64MB | 128MB }'

테이블의 대상 Parquet 파일 크기를 지정합니다.

'{ 16MB | 32MB | 64MB | 128MB }' 는 테이블의 고정 대상 파일 크기를 지정합니다.
'AUTO' 는 테이블 타입에 따라 다르게 작동합니다.
- Snowflake 관리 테이블: AUTO는 Snowflake가 크기, DML 패턴, 수집 워크로드, 클러스터링 구성과 같은 테이블 특성을 기반으로 테이블의 파일 크기를 선택해야 함을 명시합니다. Snowflake는 Snowflake의 읽기 및 쓰기 성능을 향상하기 위해 16MB부터 시작하여 파일 크기를 자동으로 조정합니다. Snowflake에서 테이블 성능을 최적화하려면 이 옵션을 사용합니다.
- 외부 관리 테이블: AUTO는 Snowflake가 가장 큰 파일 크기(128MB)로 적극적으로 확장해야 함을 명시합니다.

자세한 내용은 대상 파일 크기 설정하기 섹션을 참조하십시오.

기본값: AUTO

MAX_DATA_EXTENSION_TIME_IN_DAYS = integer

Snowflake가 테이블의 스트림이 부실해지는 것을 방지하기 위해 테이블의 데이터 보존 기간을 연장할 수 있는 최대 일수를 지정하는 오브젝트 매개 변수입니다.

이 매개 변수에 대한 자세한 설명은 MAX_DATA_EXTENSION_TIME_IN_DAYS 섹션을 참조하십시오.

REPLACE_INVALID_CHARACTERS = { TRUE | FALSE }

쿼리 결과에서 유효하지 않은 UTF-8 문자를 UNICODE 대체 문자(�)로 대체할지 여부를 지정합니다. 외부 Iceberg 카탈로그를 사용하는 테이블에 대해서만 이 매개 변수를 설정할 수 있습니다.

TRUE 는 잘못된 UTF-8 문자를 유니코드 대체 문자로 바꿉니다.
FALSE 는 유효하지 않은 UTF-8 문자를 변경하지 않습니다. Parquet 데이터 파일에서 유효하지 않은 UTF-8 문자를 발견하면 Snowflake는 사용자 오류 메시지를 반환합니다.

지정하지 않으면 Iceberg 테이블은 기본적으로 스키마, 데이터베이스 또는 계정에 대한 매개 변수 값으로 설정됩니다. 스키마는 데이터베이스보다 우선하고, 데이터베이스는 계정보다 우선합니다.

기본값: FALSE

AUTO_REFRESH = { TRUE | FALSE }

Snowflake가 메타데이터 업데이트를 위해 테이블과 연결된 외부 Iceberg 카탈로그를 자동으로 폴링해야 하는지 여부를 지정합니다.

카탈로그 통합에서 REFRESH_INTERVAL_SECONDS 매개 변수에 대한 값이 지정되지 않은 경우 Snowflake에서 사용하는 기본 새로 고침 간격은 30초입니다.

자세한 내용은 자동 새로 고침 을 참조하세요.

기본값: FALSE

참고

INFER_SCHEMA에서 AUTO_REFRESH를 사용하는 것은 지원되지 않습니다.

COPY GRANTS

다음 CREATE TABLE 베리언트 중 하나를 사용하여 새 테이블을 만들 때 원본 테이블의 액세스 권한을 유지하도록 지정합니다.

CREATE OR REPLACE TABLE

이 매개 변수는 OWNERSHIP을 제외한 모든 권한을 기존 테이블에서 새 테이블로 복사합니다. 새 테이블은 스키마의 오브젝트 유형에 대해 정의된 향후 모든 권한 부여를 상속하지는 않습니다. 기본적으로, CREATE TABLE 문을 실행하는 역할은 새 테이블을 소유합니다.

CREATE ICEBERG TABLE 문에 이 매개 변수가 포함되지 않은 경우에는 새 테이블이 원본 테이블에 부여된 모든 명시적인 액세스 권한을 상속하지 않지만, 스키마의 오브젝트 유형에 대해 정의된 향후 모든 권한 부여를 상속하지는 않습니다.

참고:

데이터 공유 사용 시:
- 기존 테이블을 다른 계정과 공유한 경우 대체 테이블도 공유됩니다.
- 기존 테이블을 데이터 컨슈머로서 자신의 계정과 공유하고 (부모 데이터베이스에서 GRANT IMPORTED PRIVILEGES 를 사용하여) 계정의 다른 역할에 추가로 액세스 권한을 부여한 경우 대체 테이블에도 액세스 권한이 부여됩니다.
대체 테이블에 대한 SHOW GRANTS 출력에는 CREATE ICEBERG TABLE 문이 실행될 때 현재 타임스탬프를 포함한 이 문을 실행한 역할로서 복사된 권한의 피부여자가 나열됩니다.
권한 부여 복사 작업은 CREATE ICEBERG TABLE 명령에서 원자적으로(즉, 같은 트랜잭션 내에서) 발생합니다.

COMMENT = 'string_literal'

테이블에 대한 설명을 지정합니다.

기본값: 값 없음

TAG ( tag_name = 'tag_value' [ , tag_name = 'tag_value' , ... ] )

태그 이름과 태그 문자열 값을 지정합니다.

태그 값은 항상 문자열이며, 태그 값의 최대 문자 수는 256자입니다.

문에서 태그를 지정하는 방법에 대한 자세한 내용은 오브젝트에 대한 태그 할당량 섹션을 참조하십시오.

WITH CONTACT ( purpose = contact [ , purpose = contact ...] ): 새 오브젝트를 하나 이상의 연락처 와 연결합니다.

액세스 제어 요구 사항¶

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

권한	오브젝트	참고
CREATE ICEBERG TABLE	스키마
CREATE EXTERNAL VOLUME	계정	새 외부 볼륨을 생성하는 데 필요합니다.
USAGE	외부 볼륨	기존 외부 볼륨을 참조하는 데 필요합니다.
CREATE INTEGRATION	계정	새 카탈로그 통합을 생성하는 데 필요합니다.
USAGE	카탈로그 통합	기존 카탈로그 통합을 참조하는 데 필요합니다.

스키마의 모든 오브젝트에 대해 작업을 수행하려면 상위 데이터베이스 및 스키마에 대한 USAGE 권한.

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

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

사용법 노트¶

예¶

원격 Iceberg REST 카탈로그를 사용하는 Iceberg 테이블 만들기¶

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'my_rest_catalog_integration'
  CATALOG_TABLE_NAME = 'my_remote_table'
  AUTO_REFRESH = TRUE;

Copy

Snowflake Open Catalog 에서 테이블을 쿼리하기 위해 Iceberg 테이블 만들기¶

이 예에서는 Snowflake를 사용하여 Snowflake Open Catalog 의 테이블 쿼리하기 에 사용할 수 있는 Iceberg 테이블을 만듭니다.

CREATE ICEBERG TABLE open_catalog_iceberg_table
  EXTERNAL_VOLUME = 'my_external_volume'
  CATALOG = 'open_catalog_int'
  CATALOG_TABLE_NAME = 'my_open_catalog_table'
  AUTO_REFRESH = TRUE;

Copy

카탈로그 연결 데이터베이스에서 Iceberg 테이블 만들기¶

다음 예제에서는 열 정의가 포함된 카탈로그 연결 데이터베이스 에서 쓰기 가능한 Iceberg 테이블을 생성합니다.

USE DATABASE my_catalog_linked_db;

USE SCHEMA 'my_namespace';

CREATE OR REPLACE ICEBERG TABLE my_iceberg_table (
  first_name string,
  last_name string,
  amount int,
  create_date date
);

Copy