Iceberg 테이블 스펙: 포맷 버전부터 개요·용어까지

Iceberg의 테이블 스펙(Table Spec)은 분산 파일 시스템이나 키-값 스토어에 있는 크고 천천히 변하는 파일 컬렉션을 하나의 테이블로 관리하기 위한 공식 규격이에요. 이 문서는 그 스펙이 어떤 목표를 갖고, 어떻게 구성되며, 어떤 용어를 쓰는지 한눈에 정리해 준답니다. 포맷 버전 규칙을 이해하면 테이블이 왜 그렇게 진화하는지도 쉽게 따라와요.

출처: Apache Iceberg™ Spec — Iceberg Table Spec

본문

포맷 버전 (Format Versioning)

Iceberg 스펙의 버전 1, 2, 3은 완성되어 커뮤니티에서 채택된 상태예요. 버전 4는 활발히 개발 중이라 아직 공식 채택되지 않았어요.

포맷 버전 번호는 읽는 쪽의 호환성을 깨뜨리는 새 기능이 추가될 때 올라가요. 즉, 옛 버전의 리더(reader)가 새 테이블 기능을 제대로 읽지 못하는 상황이 생길 때죠. 처리 엔진이 아직 구현하지 못한 기능을 쓰지 않으면, 테이블은 계속 옛 버전의 스펙으로 쓰여질 수 있어요.

버전 1: 분석 데이터 테이블 (Analytic Data Tables)

버전 1은 Parquet, Avro, ORC 같은 불변(immutable) 파일 포맷으로 대규모 분석 테이블을 관리하는 방법을 정의해요. 테이블을 버전 2로 업그레이드한 뒤에도 버전 1의 모든 데이터·메타데이터 파일은 여전히 유효해요.

버전 2: 행 수준 삭제 (Row-level Deletes)

버전 2는 불변 파일을 쓰는 분석 테이블에 행 수준 업데이트·삭제를 추가해요. 핵심 변화는 기존 데이터 파일에서 삭제된 행을 표현하는 delete 파일을 도입한 거예요. 파일을 다시 쓰지 않고도 특정 행만 지우거나 교체할 수 있죠. 행 삭제 외에도 버전 2는 라이터(writer)에 대한 요구사항을 더 엄격하게 만들었어요.

버전 3: 확장 타입과 기능 (Extended Types and Capabilities)

버전 3은 데이터 타입과 기존 메타데이터 구조를 확장해 새 기능을 더해요:

새 데이터 타입: nanosecond timestamp(tz), unknown, variant, geometry, geography
컬럼 기본값(default value) 지원
파티셔닝·정렬을 위한 다중 인자 트랜스폼
행 계보(Row Lineage) 추적
이진 삭제 벡터(Binary deletion vectors)
테이블 암호화 키(Table encryption keys)

버전 4: 메타데이터 구조와 표현 (Metadata Structure and Representation)

버전 4는 성능과 새 기능을 위해 메타데이터를 재구성해요:

메타데이터 필드의 상대 경로(relative locations) 지원

목표 (Goals)

직렬화 격리 (Serializable isolation) — 읽기는 동시 쓰기와 격리되고, 항상 커밋된 스냅샷을 사용해요. 쓰기는 파일 제거·추가를 한 번의 연산으로 처리하며 절대 부분적으로 보이지 않아요. 리더는 락을 잡지 않아요.
속도 (Speed) — 스캔 파일 계획에 O(1)의 원격 호출만 써요. 파티션이나 파일 수처럼 테이블 크기에 비례해 커지는 O(n)이 아니라는 뜻이에요.
규모 (Scale) — 잡 계획은 주로 클라이언트가 처리하고, 중앙 메타데이터 스토어가 병목이 되지 않아요. 메타데이터에는 비용 기반 최적화에 필요한 정보가 담겨요.
진화 (Evolution) — 테이블은 완전한 스키마·파티션 스펙 진화를 지원해요. 중첩 구조를 포함해 컬럼 추가·삭제·재배열·이름 변경이 안전하게 가능해요.
믿을 수 있는 타입 (Dependable types) — 핵심 타입 집합에 대해 잘 정의되고 신뢰할 수 있는 지원을 제공해요.
스토리지 분리 (Storage separation) — 파티셔닝은 테이블 설정이에요. 읽기는 파티션 값이 아니라 **데이터 값에 대한 술어(predicate)**로 계획돼요. 테이블은 진화하는 파티션 방식을 지원해요.
포맷 (Formats) — 기본 데이터 파일 포맷은 동일한 스키마 진화 규칙과 타입을 지원해요. 읽기 최적화·쓰기 최적화 포맷이 모두 제공돼요.

개요 (Overview)

이 테이블 포맷은 디렉터리가 아니라 테이블 안의 개별 데이터 파일 각각을 추적해요. 그래서 라이터가 파일을 그 자리에(in-place) 만들어 두고, 명시적인 커밋에서만 테이블에 파일을 추가할 수 있죠.

테이블 상태는 메타데이터 파일에 유지돼요. 테이블 상태가 바뀔 때마다 새 메타데이터 파일을 만들고, 옛 메타데이터를 **원자적 교체(atomic swap)**로 대체해요. 테이블 메타데이터 파일은 테이블 스키마·파티셔닝 설정·커스텀 속성·스냅샷을 추적해요. 스냅샷은 어떤 시점의 테이블 상태를 뜻하고, 테이블의 전체 데이터 파일 집합에 접근하는 데 쓰여요.

스냅샷 안의 데이터 파일은 하나 이상의 매니페스트(manifest) 파일이 추적해요. 매니페스트에는 테이블의 각 데이터 파일에 대한 행, 해당 파일의 파티션 데이터, 그리고 메트릭이 담겨요. 스냅샷의 데이터는 매니페스트에 있는 모든 live 파일의 합집합이에요. 천천히 변하는 메타데이터를 다시 쓰지 않도록 매니페스트는 여러 스냅샷에 걸쳐 재사용돼요.

스냅샷을 구성하는 매니페스트들은 매니페스트 리스트(manifest list) 파일에 저장돼요. 각 매니페스트 리스트는 파티션 통계와 데이터 파일 수 같은 매니페스트 메타데이터를 보관해서, 연산에 필요 없는 매니페스트를 읽지 않도록 도와줘요.

낙관적 동시성 (Optimistic Concurrency)

하나의 테이블 메타데이터 파일을 다른 것으로 원자적 교체하는 방식이 직렬화 격리의 토대예요. 리더는 메타데이터를 로드할 당시의 스냅샷을 쓰고, refresh할 때까지 변경의 영향을 받지 않아요.

라이터는 현재 버전이 커밋 전에 바뀌지 않을 것이라 낙관적으로 가정하고 메타데이터 파일을 만들고, 커밋 시 메타데이터 파일 포인터를 base 버전에서 새 버전으로 교체해요. 업데이트의 기반이 된 스냅샷이 더 이상 최신이 아니면, 새 최신 버전 기준으로 업데이트를 다시 시도해야 해요.

시퀀스 번호 (Sequence Numbers)

데이터·delete 파일의 상대적 나이는 매 성공적인 커밋에 부여되는 시퀀스 번호에 의존해요. 스냅샷이 커밋에 만들어질 때 낙관적으로 다음 시퀀스 번호가 부여되고 스냅샷 메타데이터에 기록돼요. 커밋이 실패해 재시도하면 시퀀스 번호를 다시 부여받아 새 스냅샷 메타데이터에 기록되죠.

한 스냅샷을 위해 만들어진 모든 매니페스트·데이터 파일·delete 파일은 그 스냅샷의 시퀀스 번호를 상속해요. 이렇게 매니페스트 메타데이터에서 시퀀스 번호를 상속하면, 커밋 재시도에서 새 매니페스트를 한 번 쓰고 재사용할 수 있어요. 재시도에서 시퀀스 번호를 바꾸려면 매니페스트 리스트만 다시 쓰면 되죠.

파일 시스템 연산 (File System Operations)

Iceberg는 파일 시스템에 다음 연산만 요구해요:

제자리 쓰기 (In-place write) — 파일은 쓰인 뒤 이동·변경되지 않아요.
탐색 가능한 읽기 (Seekable reads) — 데이터 파일 포맷은 seek 지원이 필요해요.
삭제 (Deletes) — 더 이상 쓰지 않는 테이블 파일을 삭제할 수 있어요.

이 요구사항들은 S3 같은 객체 스토리지와도 호환돼요. 테이블은 random-access 쓰기를 요구하지 않아요. 데이터·메타데이터 파일은 삭제되기 전까지 불변(immutable)이고, 새 메타데이터 파일의 커밋 연산을 원자적 rename으로 구현하는 테이블을 제외하면 rename도 요구하지 않아요.

용어 (Terms)

Schema — 테이블 필드의 이름과 타입.
Partition spec — 데이터 필드에서 파티션 값을 어떻게 유도하는지에 대한 정의.
Snapshot — 어떤 시점의 테이블 상태. 모든 데이터 파일의 집합을 포함해요.
Manifest list — 매니페스트 파일을 나열하는 파일. 스냅샷당 하나예요.
Manifest — 데이터 파일 또는 delete 파일을 나열하는 파일. 스냅샷의 부분집합이에요.
Data file — 테이블의 행을 담는 파일.
Delete file — 위치(position)나 데이터 값으로 삭제된 테이블 행을 인코딩하는 파일.
Absolute path — URI 스킴을 포함해 바로 사용할 수 있는 경로 문자열.
Relative path — URI 스킴이 없는 경로 문자열. 테이블 위치에 대해 해석되어야 해요.

Iceberg 테이블 스펙: 포맷 버전부터 개요·용어까지