Iceberg 옵션

Iceberg 옵션 (Iceberg Options)

이 페이지는 iceberg 익스텐션의 옵션을 정리해요: Iceberg 함수가 받는 파라미터, 카탈로그 연결에 사용되는 ATTACH와 CREATE SECRET 문의 옵션, 그리고 전역 설정이에요.

출처: 문서

본문

이 페이지는 iceberg 익스텐션의 옵션을 나열해요: Iceberg 함수가 받는 파라미터, 카탈로그 연결에 사용되는 ATTACH와 CREATE SECRET 문의 옵션, 그리고 전역 설정.

ATTACH 옵션

Iceberg Catalog(단일 테이블이 아니라)를 시스템에 알리려면 ATTACH 문을 사용해야 해요. ATTACH에 제공되는 옵션은 범주로 나뉘어요:

파라미터	타입	기본값	설명
ENDPOINT	VARCHAR	NULL	REST Catalog와 통신할 URL 엔드포인트.
DEFAULT_SCHEMA	VARCHAR	NULL	연결된 카탈로그에 사용할 기본 스키마(namespace).
ACCESS_DELEGATION_MODE	VARCHAR	vended_credentials	접근 위임 모드. 허용 값은 vended_credentials와 none.
SUPPORT_NESTED_NAMESPACES	BOOLEAN	false	중첩 네임스페이스를 지원하는 카탈로그에 대해 true로 설정.
STAGE_CREATE_TABLES	BOOLEAN	true	DuckDB가 staged CREATE TABLE을 사용하는지 제어. staged 테이블 생성을 지원하지 않는 카탈로그에서는 비활성화.
DISABLE_MULTI_TABLE_COMMIT	BOOLEAN	false	다중 테이블 트랜잭션/커밋 엔드포인트를 비활성화. 이 엔드포인트를 거부하는 카탈로그에서 활성화.
SKIP_CREATE_TABLE_METADATA_UPDATES	BOOLEAN	false	non-staged CREATE TABLE 이후 후속 메타데이터 업데이트를 건너뜀. 테이블 생성 중에 메타데이터를 완전히 초기화하고 후속 업데이트를 거부하는 카탈로그에서 활성화.
REMOVE_FILES_ON_DELETE	BOOLEAN	true	비활성화하면 트랜잭션 중 생성된 파일(데이터·메타데이터)이 ROLLBACK이나 COMMIT 재시도 시 정리되지 않음.
PURGE_REQUESTED	BOOLEAN	false	테이블 삭제 시 PurgeRequested 파라미터를 보냄.
ENCODE_ENTIRE_PREFIX	BOOLEAN	false	카탈로그와 통신할 때 전체 경로 접두사를 URL-encode.
MAX_TABLE_STALENESS	INTERVAL	NULL	Iceberg REST Catalog에 불필요한 요청을 방지. 10 minutes, 30 seconds, 1 year 같은 사람이 읽을 수 있는 인터벌 문자열을 받음.

일부 파라미터는 다른 것을 활성화해요. 아래 표 다음에 관련 추가 파라미터 목록이 있어요.

파라미터	타입	기본값	허용 옵션	설명
ENDPOINT_TYPE	VARCHAR	NULL	S3_TABLES, GLUE	Iceberg Catalog 유형의 공통 식별자로, 특정 기본 파라미터를 설정해요.
AUTHORIZATION_TYPE	VARCHAR	OAUTH2	OAUTH2, SIGV4	연결할 Iceberg Catalog의 Authorization 계층.

Endpoint Type

흔히 쓰이는 Iceberg Catalog 제공자에 대해 ENDPOINT_TYPE 파라미터로 특정 파라미터를 기본값으로 설정할 수 있어요. 이는 이 카탈로그들에 연결하는 단축 표기 역할을 해요.

S3 Tables

S3_TABLES ENDPOINT_TYPE을 사용해서 설정되는 파라미터:

파라미터	값
AUTHORIZATION_TYPE	SIGV4
SIGV4_REGION	ATTACH 경로로 제공된 ARN의 REGION 부분.
ENDPOINT	⟨REGION⟩.s3tables.amazonaws.com/iceberg{:.language-sql .highlight}
REMOVE_FILES_ON_DELETE	false (명시적으로 설정하지 않으면)
STAGE_CREATE_TABLES	false (명시적으로 설정하지 않으면)
PURGE_REQUESTED	true (명시적으로 설정하지 않으면)

Glue

GLUE ENDPOINT_TYPE을 사용할 때는 VARCHAR 타입의 SECRET 파라미터를 기존 S3/AWS SECRET의 경로로 설정해야 해요. GLUE ENDPOINT_TYPE을 사용해서 설정되는 파라미터:

파라미터	값
AUTHORIZATION_TYPE	SIGV4
ENDPOINT	발견된 SECRET의 리전을 사용한 ⟨REGION⟩.glue.amazonaws.com/iceberg{:.language-sql .highlight}
REMOVE_FILES_ON_DELETE	false (명시적으로 설정하지 않으면)
STAGE_CREATE_TABLES	false (명시적으로 설정하지 않으면)
PURGE_REQUESTED	true (명시적으로 설정하지 않으면)

Authorization

Iceberg REST Catalog에 연결하기 위한 Authorization 계층을 구성하려면 AUTHORIZATION_TYPE 파라미터를 전달해야 해요. 지원되는 옵션:

OAUTH2 Authorization 옵션

AUTHORIZATION_TYPE이 OAUTH2로 설정될 때 제공할 수 있는 추가 파라미터:

파라미터	타입	기본값	설명
SECRET	VARCHAR	NULL	CLIENT_ID와 CLIENT_SECRET을 얻을 ICEBERG 타입 SECRET의 경로.
CLIENT_ID	VARCHAR	NULL	OAuth2 인증 요청에 사용되는 CLIENT_ID.
CLIENT_SECRET	VARCHAR	NULL	OAuth2 인증 요청에 사용되는 CLIENT_SECRET.
OAUTH2_SERVER_URI	VARCHAR	NULL	연락할 OAuth2 서버의 엔드포인트.
OAUTH2_GRANT_TYPE	VARCHAR	NULL	사용할 grant_type.
OAUTH2_SCOPE	VARCHAR	NULL	사용할 scope.
DEFAULT_REGION	VARCHAR	NULL	카탈로그가 제공하지 않으면 vended credentials에 추가할 리전.
TOKEN	VARCHAR	NULL	서버에 요청하는 대신 사용할 Bearer Token. (새로 고침 비활성화)

SIGV4 Authorization 옵션

AUTHORIZATION_TYPE이 SIGV4로 설정될 때 제공할 수 있는 추가 파라미터:

파라미터	타입	기본값	설명
SECRET	VARCHAR	NULL	서명에 사용할 S3 또는 AWS SECRET.
SIGV4_SERVICE	VARCHAR	NULL	요청 서명에 사용할 SERVICE 재정의. 그렇지 않으면 ENDPOINT 파라미터에서 추론.
SIGV4_REGION	VARCHAR	NULL	요청 서명에 사용할 REGION 재정의. 그렇지 않으면 ENDPOINT 파라미터에서 추론.
EXTRA_HTTP_HEADERS	MAP(VARCHAR, VARCHAR)	NULL	서명 요청과 함께 보내는 추가 헤더(키-값).

ICEBERG SECRET 옵션

ATTACH Options 섹션과 그 하위 섹션에 언급된 모든 옵션은 ICEBERG SECRET 생성에 사용할 수 있어요. 그런 ICEBERG SECRET이 존재하면 후속 ATTACH 문이 이를 추론하거나, SECRET ATTACH 옵션으로 명시적으로 제공할 수 있어요.

연결된 카탈로그 작업 (Working with an Attached Catalog)

카탈로그가 연결되면 그 테이블에 대해 전체 읽기·쓰기 연산을 실행할 수 있어요:

• 읽기와 메타데이터: SELECT, AT 절로 시간 여행, iceberg_metadata, iceberg_snapshots, 통계 함수. Functions and Settings Reference 참고.
• 쓰기: CREATE/DROP SCHEMA와 TABLE, 파티셔닝, INSERT, UPDATE, DELETE, MERGE INTO, ALTER TABLE, 테이블 프로퍼티, COPY FROM DATABASE. Writing to Iceberg 참고.

메타데이터 함수는 정규화된 테이블 이름을 받아요. 예:

SELECT * FROM iceberg_snapshots(my_catalog.default.t);

설정 (Settings)

설정	타입	기본값	설명
unsafe_enable_version_guessing	BOOLEAN	false	버전이나 힌트 파일이 주어지지 않았을 때 익스텐션이 최신 메타데이터 버전을 추측할 수 있게 함.
iceberg_default_format_version	INTEGER	2	새 테이블을 만들 때 사용할 기본 format_version을 설정.
iceberg_unsafe_skip_puffin_verification	BOOLEAN	false	V3 Deletion Vectors를 읽을 때 Puffin 파일 검증 건너뜀(이전 버전이 쓴 파일과의 호환성용).

스캔 옵션 (Scan Options)

다음 파라미터는 iceberg_scan, iceberg_column_stats, iceberg_metadata, iceberg_partition_stats, iceberg_snapshots에 전달할 수 있어요:

파라미터	타입	기본값	설명
allow_moved_paths	BOOLEAN	false	이동된 Iceberg 테이블 스캔 허용
metadata_compression_codec	VARCHAR	''	'gzip'으로 설정하면 메타데이터 파일을 그렇게 취급
snapshot_from_id	UBIGINT	NULL	특정 id로 스냅샷에 접근
snapshot_from_timestamp	TIMESTAMP	NULL	특정 timestamp로 스냅샷 접근
version	VARCHAR	'?'	명시적 버전 문자열, 힌트 파일 또는 추측 제공
version_name_format	VARCHAR	'v%s%s.metadata.json,%s%s.metadata.json'	버전이 메타데이터 파일 이름으로 변환되는 방법 제어

iceberg_snapshots는 allow_moved_paths, snapshot_from_id, snapshot_from_timestamp를 파라미터로 받지 않아요.

메타데이터 버전 선택하기 (Selecting Metadata Versions)

기본적으로 iceberg 익스텐션은 사용할 적절한 메타데이터 버전을 식별하기 위해 version-hint.text 파일을 찾아요. 이는 iceberg 익스텐션 함수에 version 파라미터로 버전 번호를 명시적으로 제공해 재정의할 수 있어요:

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/lineitem_iceberg',
    version = '1'
);

기본적으로 iceberg 함수는 v{version}.metadata.json과 {version}.metadata.json 파일 둘 다 찾고, metadata_compression_codec = 'gzip'이 지정되면 v{version}.gz.metadata.json과 {version}.gz.metadata.json도 찾아요. 다른 압축 코덱은 지원되지 않아요.

version 파라미터로 텍스트 파일이 제공되면 그 파일을 열어 버전 힌트 파일로 취급해요:

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/lineitem_iceberg',
    version = 'version-hint.txt'
);

iceberg 익스텐션은 이 파일을 열고 파일의 전체 내용을 제공된 버전 번호로 사용해요. version-hint.txt 파일의 전체 내용은 인코딩, 이스케이프, 트리밍 없이 리터럴 버전 이름으로 취급된다는 점을 참고해요. 여기에는 아래 설명된 로직에서 파일 이름으로 명시적으로 포맷되어 전달되는 공백이나 안전하지 않은 문자도 포함돼요.

대체 메타데이터 명명 규칙 작업 (Working with Alternative Metadata Naming Conventions)

iceberg 익스텐션은 version_name_format 파라미터로 쉼표로 구분된 형식 문자열 목록을 지정해 서로 다른 메타데이터 명명 규칙을 다룰 수 있어요. 각 형식 문자열은 두 개의 %s 파라미터를 포함해야 해요. 첫 번째는 메타데이터 파일 이름에서 버전 번호의 위치, 두 번째는 metadata_compression_codec이 지정한 파일 확장자의 위치예요. 위에서 설명한 동작은 기본값 "v%s%s.metadata.gz,%s%smetadata.gz"이 제공해요. 대체로 이름 지어진 메타데이터 파일(예: rev-2.metadata.json.gz)이 있다면 다음 문으로 테이블을 읽을 수 있어요:

SELECT *
FROM iceberg_snapshots(
    'data/iceberg/alternative_metadata_gz_naming',
    version = '2',
    version_name_format = 'rev-%s.metadata.json%s',
    metadata_compression_codec = 'gzip'
);

메타데이터 버전 "추측"하기 ("Guessing" Metadata Versions)

기본적으로 iceberg 익스텐션이 테이블을 읽으려면 테이블 버전 번호나 version-hint.text가 제공되어야 해요. 이는 보통 외부 데이터 카탈로그가 제공해요. 둘 다 없으면 iceberg 익스텐션이 version 파라미터로 ?를 전달해 최신 버전을 추측할 수 있어요:

SELECT count(*)
FROM iceberg_scan(
    'data/iceberg/lineitem_iceberg_no_hint',
    version = '?',
    allow_moved_paths = true
);

"최신" 버전은 파일 이름을 정렬했을 때 사전순으로 가장 큰 파일 이름으로 가정돼요. 콜레이션은 고려되지 않아요. 이 동작은 ACID 제약을 위반할 수 있어 기본으로 활성화되지 않아요. unsafe_enable_version_guessing을 true로 설정해 활성화할 수 있어요. 설정되면 iceberg 함수는 실패하기 전에 기본적으로 최신 버전을 추측하려고 해요.

SET unsafe_enable_version_guessing = true;
SELECT count(*)
FROM iceberg_scan(
    'data/iceberg/lineitem_iceberg_no_hint',
    allow_moved_paths = true
);

더 알아보기 (Learn more)

• Iceberg 함수 — 익스텐션 함수 목록.
• Iceberg 카탈로그 — 카탈로그 연결.