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

구문¶

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>' ]
  [ 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> ... ] ) ]

필수 매개 변수¶

table_name

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

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

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

참고

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

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

CATALOG_TABLE_NAME = 'rest_catalog_table_name'

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

참고

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

선택적 매개 변수¶

EXTERNAL_VOLUME = 'external_volume_name'

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

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

CATALOG = 'catalog_integration_name'

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

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

CATALOG_NAMESPACE = 'catalog_namespace'

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

• 카탈로그 통합으로 기본 네임스페이스가 지정되지 않은 경우 테이블의 카탈로그 네임스페이스를 설정하려면 REST 카탈로그 원본에 대한 네임스페이스를 지정해야 합니다.

참고

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

• SYSTEM$LIST_ICEBERG_TABLES_FROM_CATALOG

• SYSTEM$LIST_NAMESPACES_FROM_CATALOG

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 카탈로그를 자동으로 폴링해야 하는지 여부를 지정합니다.

Delta 기반 테이블의 경우, Snowflake는 외부 클라우드 저장소에서 업데이트를 폴링합니다.

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

기본값: FALSE

COMMENT = 'string_literal'

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

기본값: 값 없음

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

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

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

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

WITH CONTACT ( purpose = contact [ , purpose = contact ...] )

미리 보기 기능 — 공개

모든 계정에서 사용 가능합니다.

새 오브젝트를 하나 이상의 연락처 와 연결합니다.

액세스 제어 요구 사항¶

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

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

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

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

사용법 노트¶

• 큰따옴표로 묶인 식별자를 사용하여 외부 볼륨 또는 카탈로그 통합을 생성한 경우 CREATE ICEBERG TABLE 문에 생성된 것처럼 (큰따옴표를 포함하여) 식별자를 정확히 지정해야 합니다. 따옴표를 포함하지 않으면 Object does not exist 오류(또는 유사한 종류의 오류)가 발생할 수 있습니다.

• 테이블 생성 시 고려 사항

  • 스키마는 이름이 같은 테이블 및/또는 뷰를 포함할 수 없습니다. 테이블을 만들 때는 다음 사항이 적용됩니다.

    • 스키마에 같은 이름의 뷰가 이미 있는 경우 오류가 반환되고 테이블이 생성되지 않습니다.

    • 같은 이름의 테이블이 스키마에 이미 있는 경우 명령에 선택적인 OR REPLACE 키워드를 포함하지 않는 한 오류가 반환되고 테이블이 생성되지 않습니다.

  • CREATE OR REPLACE <오브젝트> 문은 원자성입니다. 즉, 오브젝트가 바뀔 때 단일 트랜잭션으로 이전 오브젝트가 삭제되고 새 오브젝트가 생성됩니다.

    이는 CREATE OR REPLACE ICEBERG TABLE 작업과 동시에 수행되는 모든 쿼리가 이전 또는 새 테이블 버전을 사용함을 의미합니다.

  • OR REPLACE 및 IF NOT EXISTS 절은 상호 배타적입니다. 두 문자를 같은 문에 함께 사용할 수 없습니다.

  • 예약된 키워드 와 마찬가지로, ANSI로 예약된 함수 이름(CURRENT_DATE, CURRENT_TIMESTAMP 등)을 열 이름으로 사용할 수 없습니다.

  • (선택적 OR REPLACE 키워드를 사용하여) 테이블을 다시 만들면 기록이 삭제되고, 이로 인해 테이블의 스트림이 부실해집니다. 부실 스트림은 읽을 수 없습니다.

• 메타데이터 관련:

  주의

  고객은 Snowflake 서비스를 사용할 때 개인 데이터(사용자 오브젝트 제외), 민감한 데이터, 수출 통제 대상 데이터 또는 기타 규제 데이터가 메타데이터로 입력되지 않도록 해야 합니다. 자세한 내용은 Snowflake의 메타데이터 필드 섹션을 참조하십시오.

예¶

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;

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;