ALTER ICEBERG TABLE

기존 Iceberg 테이블 의 속성, 열 또는 제약 조건을 수정합니다. Iceberg 테이블이 카탈로그 통합을 사용하는 경우 ALTER ICEBERG TABLE을 사용하여 새 데이터로 테이블을 새로 고치십시오.

또한 ALTER ICEBERG TABLE을 사용하여 카탈로그 통합을 사용하는 테이블을 Snowflake를 Iceberg 카탈로그로 사용하는 테이블로 변환할 수도 있습니다. 자세한 내용은 Iceberg 테이블 변환하기 섹션을 참조하십시오.

이 항목에서는 Iceberg 테이블 을 지정하여 혼동을 방지하는 경우를 제외하고는 Iceberg 테이블을 간단히 ‘테이블’이라고 부릅니다.

참고 항목:

CREATE ICEBERG TABLE , DROP ICEBERG TABLE , SHOW ICEBERG TABLES , DESCRIBE ICEBERG TABLE

구문

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> REFRESH [ '<metadata_file_relative_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> CONVERT TO MANAGED [ BASE_LOCATION = '<file_path>' ]

ALTER ICEBERG TABLE [ IF EXISTS ] <table_name> clusteringAction

ALTER ICEBERG TABLE [ IF EXISTS ] <name> SET TAG <tag_name> = '<tag_value>' [ , <tag_name> = '<tag_value>' ... ]

ALTER ICEBERG TABLE [ IF EXISTS ] <name> UNSET TAG <tag_name> [ , <tag_name> ... ]
Copy

여기서

clusteringAction ::=
  {
     CLUSTER BY ( <expr> [ , <expr> , ... ] )
     /* { SUSPEND | RESUME } RECLUSTER is valid action */
   | { SUSPEND | RESUME } RECLUSTER
   | DROP CLUSTERING KEY
  }
Copy

매개 변수

name

변경할 Iceberg 테이블의 식별자입니다. 식별자에 공백이나 특수 문자가 포함된 경우 전체 문자열을 큰따옴표로 묶어야 합니다. 큰따옴표로 묶인 식별자도 대/소문자를 구분합니다.

REFRESH [ 'metadata_file_relative_path' ]

Snowflake에서 관리하지 않는 Iceberg 테이블에 대해 지정된 경로(테이블의 외부 볼륨 저장소 위치 기준)에 있는 메타데이터 파일에 액세스하고 테이블 메타데이터를 업데이트합니다.

Iceberg 테이블이 오브젝트 저장소의 Iceberg 파일을 원본으로 사용하는 경우에만 이 옵션을 사용하십시오. AWS Glue를 Iceberg 카탈로그로 사용하는 경우 이 옵션을 생략하십시오.

예를 들어, s3://mybucket_us_east_1/metadata/v1.metadata.json 이 메타데이터 파일의 전체 경로이고 테이블과 연결된 외부 볼륨의 저장소 위치가 s3://mybucket_us_east_1 인 경우 metadata/v1.metadata.jsonmetadata_file_relative_path 로 지정합니다.

참고

Snowflake 버전 7.34 이전에는 오브젝트 저장소의 Iceberg 파일에서 테이블을 생성하려면 BASE_LOCATION (이전 버전에서는 FILE_PATH 라고도 함)이라는 매개 변수가 필요했습니다. 이 매개 변수는 EXTERNAL_VOLUME 위치에서 상대 경로를 지정했습니다.

이전 구문을 사용하여 생성한 테이블을 새로 고치려면 BASE_LOCATION 을 기준으로 한 상대 경로를 지정하십시오. 예를 들어 메타데이터 파일의 전체 경로가 s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json 인 경우 metadata/v1.metadata.jsonmetadata-file-relative-path 로 지정합니다.

CONVERT TO MANAGED

카탈로그 통합을 사용하는 읽기 전용 Iceberg 테이블을 Snowflake를 Iceberg 카탈로그로 사용하는 테이블로 변환합니다. 변환된 테이블은 읽기 및 쓰기 작업을 모두 지원하며 Snowflake는 테이블에 대해 압축과 같은 모든 수명 주기 유지 관리를 처리합니다. 자세한 내용은 Iceberg 테이블 변환하기 섹션을 참조하십시오.

[ BASE_LOCATION = 'file_path' ]

Snowflake가 테이블 데이터와 메타데이터를 쓸 수 있는 테이블의 EXTERNAL_VOLUME 위치에서 디렉터리에 대한 상대 경로를 지정합니다. 원래 CREATE ICEBERG TABLE 문이 BASE_LOCATION 을 허용하거나 포함하지 않은 경우 변환 중에 이 속성의 값을 지정해야 합니다.

테이블을 변환한 후에는 이 매개 변수의 값을 변경할 수 없습니다.

SET ...

외부 테이블에 대해 설정할 하나 이상의 속성/매개 변수를 지정합니다(공백, 쉼표 또는 새 줄로 구분).

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

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

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

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

UNSET

현재는 이 명령으로 다음 항목만 설정 해제할 수 있습니다.

  • TAG tag_name [ , tag_name ... ]

클러스터링 작업(clusteringAction)

참고

클러스터링은 Snowflake를 Iceberg 카탈로그로 사용하는 테이블에만 지원됩니다.

CLUSTER BY ( expr [ , expr , ... ] )

하나 이상의 테이블 열 또는 열 식을 테이블의 클러스터링 키로 지정(또는 수정)합니다. 자동 클러스터링 으로 클러스터링을 유지 관리하는 열/식입니다.

클러스터링에 대해 자세히 알아보려면 클러스터링 키 및 클러스터링된 테이블 섹션을 참조하십시오.

SUSPEND | RESUME RECLUSTER

테이블에 대해 자동 클러스터링 을 활성화하거나 비활성화합니다.

DROP CLUSTERING KEY

테이블에 대한 클러스터링 키를 삭제합니다.

클러스터링 키와 재클러스터링에 대한 자세한 내용은 Snowflake 테이블 구조 이해하기 를 참조하십시오.

액세스 제어 요구 사항

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

권한

오브젝트

참고

OWNERSHIP

Iceberg 테이블

OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege).

USAGE

외부 볼륨

테이블 메타데이터를 수동으로 새로 고치는 데 필요합니다.

USAGE

파일 형식

테이블 메타데이터를 수동으로 새로 고치는 데 필요합니다.

스키마의 모든 오브젝트에 대해 작업하려면 상위 데이터베이스 및 스키마에 대한 USAGE 권한도 필요합니다.

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

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

사용법 노트

  • 테이블 소유자(즉, 테이블에 대한 OWNERSHIP 권한을 가진 역할) 이상만이 명령을 실행할 수 있습니다.

  • 클러스터링은 Snowflake를 Iceberg 카탈로그로 사용하는 테이블에만 지원됩니다. Iceberg 테이블에 클러스터링을 추가하려면 테이블을 포함한 스키마와 데이터베이스에 대한 USAGE 또는 OWNERSHIP 권한도 있어야 합니다.

  • (암시적 또는 명시적) 트랜잭션에서는 ALTER ICEBERG TABLE … REFRESH 명령을 사용할 수 없습니다.

  • Snowflake 버전 7.34 이전에는 오브젝트 저장소의 Iceberg 파일에서 테이블을 생성하려면 BASE_LOCATION (이전 버전에서는 FILE_PATH 라고도 함)이라는 매개 변수가 필요했습니다. 이 매개 변수는 EXTERNAL_VOLUME 위치에서 상대 경로를 지정했습니다.

    이전 구문을 사용하여 생성한 테이블을 새로 고치려면 BASE_LOCATION 을 기준으로 한 상대 경로를 지정하십시오. 예를 들어 메타데이터 파일의 전체 경로가 s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json 인 경우 metadata/v1.metadata.jsonmetadata-file-relative-path 로 지정합니다.

  • 메타데이터 관련:

    주의

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

카탈로그 통합을 사용하는 테이블의 테이블 메타데이터를 수동으로 새로 고치기

오브젝트 저장소의 Iceberg 파일

이 예에서는 새 메타데이터 파일의 변경 사항을 기준으로 테이블 메타데이터를 수동으로 새로 고칩니다. 이 예에서 메타데이터 파일의 전체 경로는 <external-volume-storage-base-url>/path/to/metadata/v2.metadata.json 입니다.

참고

Snowflake 버전 7.34 이전에는 오브젝트 저장소의 Iceberg 파일에서 테이블을 생성하려면 BASE_LOCATION (이전 버전에서는 FILE_PATH 라고도 함)이라는 매개 변수가 필요했습니다. 이 매개 변수는 EXTERNAL_VOLUME 위치에서 상대 경로를 지정했습니다.

이전 구문을 사용하여 생성한 테이블을 새로 고치려면 BASE_LOCATION 을 기준으로 한 상대 경로를 지정하십시오. 예를 들어 메타데이터 파일의 전체 경로가 s3://mybucket_us_east_1/my_base_location/metadata/v1.metadata.json 인 경우 metadata/v1.metadata.jsonmetadata-file-relative-path 로 지정합니다.

ALTER ICEBERG TABLE my_iceberg_table REFRESH 'path/to/metadata/v2.metadata.json';
Copy

AWS Glue

이 예에서는 Iceberg 카탈로그에 AWS Glue를 사용하는 테이블의 메타데이터를 수동으로 새로 고칩니다. AWS Glue를 Iceberg 카탈로그로 사용하는 경우 새로 고침 명령에 메타데이터 파일 경로를 지정하지 않습니다.

ALTER ICEBERG TABLE myIcebergTable REFRESH;
Copy

Iceberg 테이블 변환하기

다음 예에서는 ALTER ICEBERG TABLE … CONVERT TO MANAGED 문을 사용하여 Snowflake에서 관리하지 않는 테이블을 Snowflake를 Iceberg 카탈로그로 사용하는 테이블로 변환합니다.

ALTER ICEBERG TABLE myTable CONVERT TO MANAGED
  BASE_LOCATION = myBaseLocation;
Copy