아이스버그 테이블 새로고침

아이스버그 테이블 새로고침 (ALTER ICEBERG TABLE ... REFRESH)

외부 Iceberg 카탈로그를 사용하는 Apache Iceberg™ table의 메타데이터를 새로고침해요. Iceberg 테이블을 새로고침하면 테이블 메타데이터가 가장 최근의 테이블 변경 사항과 동기화돼요.

이 항목에서는 혼동을 피하기 위해 Iceberg tables라고 명시해야 하는 경우를 제외하고 Iceberg 테이블을 간단히 "tables"라고 지칭해요.

출처: 문서

본문

Syntax

ALTER ICEBERG TABLE [ IF EXISTS ]  REFRESH [ '' ]

Parameters

table_name

새로 고침할 테이블의 식별자예요.

식별자에 공백이나 특수 문자가 포함되어 있으면 전체 문자열을 큰따옴표로 묶어야 해요. 큰따옴표로 묶인 식별자는 대소문자도 구분해요.

자세한 내용은 Identifier requirements를 참조하세요.

'metadata_file_relative_path'

객체 스토리지의 Iceberg 파일에서 생성된 테이블의 메타데이터 파일 경로를 지정해요. 경로는 테이블과 연결된 외부 볼륨의 active storage location을 기준으로 하는 상대 경로여야 해요.

다음 표는 예시 스토리지 위치를 기준으로 지정할 값을 보여줘요.

테이블의 외부 볼륨에 대한 활성 스토리지 위치	`s3://mybucket_us_east_1`
메타데이터 파일의 전체 경로	`s3://mybucket_us_east_1/metadata/v1.metadata.json`
'metadata_file_relative_path'로 지정할 값	`metadata/v1.metadata.json` (앞에 슬래시(`/`) 없이)

테이블이 카탈로그로 AWS Glue를 사용하거나 Delta 테이블 파일에서 생성된 경우에는 메타데이터 파일 경로를 지정하지 마세요.
메타데이터 파일 경로에서 앞의 슬래시(/)는 생략해요.

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-file-relative-path}로 metadata/v1.metadata.json을 지정해요.

Access control requirements

이 작업을 실행하는 데 사용되는 role은 최소한 다음 privileges을 보유해야 해요.

권한	개체	참고
OWNERSHIP	Iceberg 테이블	%ac-ownership%
USAGE	외부 볼륨	vended credentials를 사용하는 경우 필요하지 않아요.
USAGE	카탈로그 통합

스키마의 개체를 운영하려면 상위 데이터베이스에 대한 권한이 하나 이상, 상위 스키마에 대한 권한이 하나 이상 필요해요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 을 참조하세요.

securable objects에 대해 SQL 작업을 수행하기 위한 역할 및 권한 부여에 대한 일반적인 정보는 Overview of Access Control을 참조하세요.

Usage notes

테이블 소유자(즉, 테이블에 대한 OWNERSHIP 권한이 있는 역할) 이상만 이 명령을 실행할 수 있어요.
트랜잭션(암시적 또는 명시적)에서 ALTER ICEBERG TABLE ... REFRESH 명령을 사용하는 것은 지원되지 않아요.
Delta Direct 테이블에 대한 고려 사항: 이 명령을 사용하여 Delta Direct 테이블을 새로 고치면 Snowflake는 새로 고침당 최대 1,000개의 Delta 커밋 파일을 처리하며 특정 조건에서 체크포인트 새로 고침(전체 새로 고침)을 수행할 수 있어요. 1,000개 커밋 파일 제한, 체크포인트 새로 고침 트리거 및 예시는 Refresh를 참조하세요.
메타데이터 관련:

Examples

테이블 새로 고치기

이 예시에서는 다음 시나리오에 대해 테이블의 메타데이터를 수동으로 새로 고쳐요.

테이블이 Iceberg 카탈로그에 AWS Glue를 사용해요.
테이블이 객체 스토리지의 Delta 테이블 파일을 기반으로 해요.

이 시나리오에서는 새로 고침 명령에 메타데이터 파일 경로를 지정하지 않아요.

ALTER ICEBERG TABLE myIcebergTable REFRESH;

객체 스토리지의 Iceberg 파일에서 생성된 테이블 새로 고치기

이 예시에서는 새 메타데이터 파일의 변경 사항을 기준으로 테이블 메타데이터를 수동으로 새로 고쳐요. 이 예시에서 메타데이터 파일의 전체 경로는 /path/to/metadata/v2.metadata.json이에요.

메타데이터 파일을 지정할 때 메타데이터 파일 경로에 앞의 슬래시(/)를 포함하지 않아요.

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

아이스버그 테이블 새로고침