Apache Iceberg 사양 버전 비교 — V1·V2·V3, 무엇이 어떻게 달라졌나

Apache Iceberg를 도입할 때 흔히 간과되는 결정 중 하나가 사양 버전(format-version) 선택입니다. "Iceberg를 쓰자"는 결정과 "Iceberg V2를 쓰자"는 결정은 다릅니다. 같은 테이블이라도 사양 버전에 따라 가능한 연산, 운영 비용, 엔진 호환성이 크게 달라지기 때문입니다.

이 글은 V1·V2·V3 각 사양이 무엇을 풀었고, 어떤 한계를 가졌으며, 실무에서는 어떻게 선택해야 하는지를 정리합니다.

1. 사양 버전(format-version)이란

Iceberg 테이블의 metadata.json 최상단에는 format-version 필드가 있습니다.

{
  "format-version": 2,
  "table-uuid": "5f8a...e9",
  "location": "s3://bucket/warehouse/db/events",
  ...
}

이 정수 한 값이 테이블이 어떤 사양에 따라 해석되어야 하는지를 결정합니다. 엔진(리더·라이터)은 이 값을 보고 어떤 연산이 가능한지, 어떤 메타데이터 필드가 존재하는지를 판단합니다.

세 가지 핵심 관찰:

• 사양은 누적적이다. V2는 V1의 모든 개념을 포함하고 그 위에 새 기능을 더합니다. V3 또한 V2 위에 더합니다.
• 사양은 업그레이드 가능하다. 한 번 V1으로 만든 테이블도 format-version=2로 올릴 수 있습니다. 데이터 재작성 없이 메타데이터만 갱신됩니다.
• 사양은 다운그레이드되지 않습니다. V2로 올린 뒤 V1 전용 기능만 쓴다고 해서 V1으로 내릴 수 없습니다. 엔진들도 이를 가정합니다.

2. V1 (2018) — 기초의 정립

2.1 무엇이 등장했나

Iceberg V1은 2018년 Netflix에서 출발해 2020년 Apache Top-Level로 승격된 사양입니다. 그 핵심은 다음 다섯 가지였습니다.

1. 3계층 메타데이터 모델 — catalog → metadata.json → manifest list → manifest → data file
2. Snapshot 기반 격리 — 모든 변경은 새 스냅샷을 만들고, 카탈로그에서 포인터를 원자적으로 바꾼다.
3. Field-ID 기반 컬럼 매핑 — 컬럼에 영구 ID를 부여, 이름 변경·재배치를 데이터 재작성 없이 수행.
4. Hidden Partitioning — 사용자에게서 파티션 키를 숨김. Query Predicate가 자동으로 Pruning에 활용됨.
5. Time Travel — 스냅샷 ID나 시각으로 과거 상태 조회.

V1은 **"Hive의 구조적 한계를 어떻게 메타데이터로 풀 것인가"**에 대한 답을 처음으로 정립했습니다.

2.2 V1 metadata.json (단순화)

{
  "format-version": 1,
  "table-uuid": "5f8a-...",
  "location": "s3://...",
  "last-updated-ms": 1714000000000,
  "last-column-id": 4,
  "schema": {
    "schema-id": 0,
    "fields": [
      { "id": 1, "name": "event_id",   "required": true,  "type": "long" },
      { "id": 2, "name": "user_id",    "required": false, "type": "long" },
      { "id": 3, "name": "event_ts",   "required": true,  "type": "timestamptz" },
      { "id": 4, "name": "event_type", "required": true,  "type": "string" }
    ]
  },
  "partition-spec": [
    { "name": "event_day", "source-id": 3, "transform": "day", "field-id": 1000 }
  ],
  "current-snapshot-id": 8123412345678901234,
  "snapshots": [ ... ]
}

V2와 비교해 두드러진 차이:

• schema / partition-spec이 단일 객체다 (V2는 배열).
• 시퀀스 번호(sequence-number)가 없다.
• delete file 관련 필드가 없다.

2.3 V1이 풀지 못한 문제

V1은 분석 워크로드에는 충분했지만, 운영을 시작하면 다음 한계가 드러났습니다.

문제 1 — Row-level UPDATE/DELETE 비용

V1에는 delete file 개념이 없습니다. 한 행을 지우거나 갱신하려면, 그 행이 속한 데이터 파일을 통째로 다시 써야 합니다. 이를 Copy-on-Write(CoW) 라고 합니다.

시나리오: 1 GB Parquet 파일 중 한 행을 UPDATE
─────────────────────────────────────────
V1 동작:  1 GB를 모두 읽고 → 한 행 수정 → 1 GB 다시 씀
실제 비용: 약 2 GB의 I/O, 셔플, S3 PUT

이 비용은 다음 워크로드에서 치명적이었습니다.

• CDC(Change Data Capture) — 초당 수천 건의 row-level 갱신을 받는 테이블에서는 작동 불가.
• GDPR·법적 정정 — 한 사용자의 데이터를 지우려면 그 사용자의 흔적이 있는 모든 파일을 다시 써야 함.
• 빈번한 MERGE — Slowly Changing Dimension(SCD) 패턴의 비용이 폭증.

문제 2 — 시퀀스 번호 부재로 인한 정합성 한계

V1은 스냅샷에 시간 순서는 있지만, 메타데이터 파일·데이터 파일 간 명시적 시퀀스 번호가 없습니다. 동시 작성자(concurrent writer)가 많은 환경에서 충돌 감지가 까다로워졌습니다.

2.4 V1이 적합한 워크로드

• append-only 로그: 클릭스트림, 이벤트 적재
• 일별·시간별 ETL의 batch 결과 테이블
• 읽기 중심의 마트 테이블

2026년 현재 신규 테이블에 V1을 선택할 이유는 거의 없습니다. V2가 모든 V1 기능을 포함하면서 더 안정적인 정합성과 row-level 연산을 제공하기 때문입니다.

3. V2 (2021~) — Row-level operations의 등장

3.1 무엇이 추가됐나

V2는 두 가지 큰 변화를 가져왔습니다.

1. Sequence number 도입 — 스냅샷마다 고유한 단조 증가 번호. 동시 작성·삭제의 정합성 보장.
2. Delete file 도입 — 두 종류(position / equality)의 delete file로 row-level 연산을 데이터 파일 재작성 없이 표현.

이로써 Merge-on-Read(MoR) 모드가 가능해졌습니다.

3.2 Position delete file

(file_path, position) 형태로 "어느 데이터 파일의 몇 번째 행이 지워졌는가"를 기록합니다.

position delete file (Parquet)
┌──────────────────────────────────────────────────────┬──────────┐
│ file_path                                            │ position │
├──────────────────────────────────────────────────────┼──────────┤
│ s3://.../data/00000-aab.parquet                      │       42 │
│ s3://.../data/00000-aab.parquet                      │      105 │
│ s3://.../data/00000-aab.parquet                      │      219 │
│ s3://.../data/00001-bcd.parquet                      │        7 │
└──────────────────────────────────────────────────────┴──────────┘

특징:

• 데이터 파일을 다시 쓰지 않고 삭제 표시만 추가.
• 읽기 시 엔진은 데이터 파일과 position delete를 함께 로드해 메모리에서 삭제 행을 걸러냄.
• 갱신(UPDATE)은 "옛 위치 삭제 + 새 데이터 파일 append"로 표현.

적합 워크로드:

• CDC 적재 (각 변경의 옛 위치를 알고 있을 때).
• MERGE 잡 (옛 위치를 join으로 찾아낼 수 있을 때).

3.3 Equality delete file

(column = value) Predicate 형태로 삭제를 표현합니다.

equality delete file (Parquet)
─────────────────────────────────
schema: (user_id long)

user_id
───────
   1024
   2050
   3199

이는 "현재 시점 기준 user_id가 1024, 2050, 3199인 모든 행은 삭제됨"을 의미합니다. 다음 스냅샷에서 같은 키가 다시 등장하면 그 행은 살아 있는 것으로 간주됩니다(시퀀스 번호로 구분).

적합 워크로드:

• 키만 알 때: "이 사용자 ID들을 모두 지워라" (GDPR 정정의 일반적 패턴).
• 옛 위치(파일·행 번호)를 일일이 추적할 수 없는 외부 시스템의 삭제 이벤트.

3.4 Position vs Equality 비교

권고:

• 가능하면 position delete 우선. equality는 "위치를 모르는" 경우의 안전망.
• 둘이 섞이는 것은 정상이며, Iceberg는 시퀀스 번호로 적용 순서를 결정합니다.

3.5 V2 metadata.json — V1과 다른 점

{
  "format-version": 2,
  "table-uuid": "5f8a-...",
  "last-sequence-number": 142,
  "schemas": [ { "schema-id": 0, "fields": [ ... ] } ],
  "current-schema-id": 0,
  "partition-specs": [ { "spec-id": 0, "fields": [ ... ] } ],
  "default-spec-id": 0,
  "current-snapshot-id": 8123...,
  "snapshots": [
    {
      "snapshot-id": 8123...,
      "sequence-number": 142,
      "timestamp-ms": 1747804790000,
      "summary": {
        "operation": "delete",
        "added-position-delete-files": "1",
        "added-position-deletes": "47"
      },
      "manifest-list": "s3://.../snap-8123-1-abc.avro",
      "schema-id": 0
    }
  ]
}

V1 대비 변화:

• schema → schemas 배열 (스키마 진화 이력을 모두 보존).
• partition-spec → partition-specs 배열 (partition evolution 지원).
• 최상위에 last-sequence-number 등장.
• 각 snapshot에 sequence-number 추가.
• snapshot summary에 delete file 관련 통계가 등장.

3.6 V2 도입의 운영 영향

V2를 켜는 순간 새로운 운영 부담이 생깁니다.

• Delete file 누적 — 정정·삭제가 잦으면 delete file 수가 빠르게 늘어납니다. 읽기 비용이 누적적으로 증가.
• 컴팩션 필수 — V2 MoR 테이블은 정기 rewrite_data_files로 delete를 흡수시켜야 합니다.
• 읽기 메모리 압력 — equality delete가 많으면 모든 데이터 파일에 대해 키 평가가 일어나 메모리 사용량 증가.

-- V2 테이블 컴팩션 표준 패턴
CALL system.rewrite_data_files(
  table => 'db.events',
  options => map(
    'target-file-size-bytes',  '536870912',
    'delete-file-threshold',   '5',     -- 데이터 파일당 delete 5개 이상이면 재작성
    'min-input-files',         '5'
  )
);

3.7 V2가 표준 권고가 된 이유

2024년 이후 거의 모든 신규 Iceberg 테이블은 V2로 만들어집니다. 이유:

• V2는 V1의 모든 기능을 포함합니다(분석 워크로드에서 V1을 굳이 쓸 이유 없음).
• Partition evolution 같은 운영성 기능이 V2에서야 정상 동작합니다.
• 대부분의 엔진이 V2를 일급으로 지원합니다.
• CDC·MERGE를 시작하면 즉시 V2가 필요합니다.

4. V3 (2025+) — 표현력과 효율성의 도약

V3는 2024~2025년에 합의되어 2025년부터 주요 엔진이 점진 도입한 사양입니다. 다섯 가지 큰 변화가 있습니다.

4.1 Deletion Vectors (Puffin)

V2 position delete의 효율 문제를 해결합니다.

V2 position delete는 Parquet 파일 안에 (file_path, position) 행을 나열했습니다. 한 데이터 파일에서 1만 행을 삭제하면 1만 행짜리 Parquet 파일이 생깁니다. 읽기 시 이를 메모리에 로드해 hash·sort merge로 적용합니다.

V3는 같은 정보를 Roaring bitmap으로 압축해 Puffin 포맷 파일에 저장합니다.

Puffin file
  └─ blob: "deletion-vector-v1"
       schema: Roaring bitmap of deleted positions
       referencedDataFile: s3://.../data/00000-aab.parquet

효과:

• 공간 효율 — 한 파일당 수만~수십만 삭제도 KB 단위로 표현 가능.
• 읽기 효율 — bitmap AND 연산으로 즉시 적용. 정렬·hash join 불필요.
• 단일 파일당 단일 deletion vector — 같은 데이터 파일에 대한 여러 position delete가 누적되지 않습니다.

V3 도입 후 MoR 워크로드의 읽기 성능이 30~70% 향상되는 사례가 보고됩니다(테이블·쿼리에 따라 다름).

4.2 컬럼 Default Value

V1·V2에서 새 컬럼을 추가하면 기존 행에는 항상 NULL이 채워졌습니다. V3는 사양 수준에서 default value를 지원합니다.

ALTER TABLE events ADD COLUMN priority STRING DEFAULT 'normal';
 
-- 기존 행도 'normal'로 읽힘. 데이터 재작성 없음.
SELECT count(*) FROM events WHERE priority = 'normal';

핵심:

• 데이터 재작성 없이 default 적용. metadata.json에 default value가 기록되고, 옛 데이터 파일을 읽을 때 엔진이 자동 적용.
• 두 종류의 default: 컬럼 추가 시점 이전 행을 위한 initial-default, 신규 쓰기에 적용되는 write-default.

4.3 Variant 타입

JSON 같은 반구조화 데이터를 일관된 인코딩으로 저장합니다. Spark·Snowflake·Databricks 등이 이미 자체 Variant를 가지고 있었지만 인코딩이 달랐습니다. V3는 사양 수준의 공통 Variant를 정의해 엔진 간 호환성을 확보합니다.

CREATE TABLE events (
  event_id BIGINT,
  payload  VARIANT
) USING iceberg
TBLPROPERTIES ('format-version' = '3');
 
INSERT INTO events VALUES
  (1, parse_json('{"type":"click","url":"/blog","ua":"chrome/120"}'));
 
-- 엔진별 함수로 추출
SELECT event_id,
       payload:type::STRING AS type,
       payload:url::STRING  AS url
FROM events
WHERE payload:type::STRING = 'click';

장점:

• 스키마 진화의 또 다른 도구 — 빈번히 바뀌는 필드를 Variant로 두면, 컬럼 추가/제거 비용을 피할 수 있습니다.
• 엔진 간 일관성 — 같은 Variant를 Spark·Trino·Snowflake가 동일하게 해석.

주의:

• Variant 안의 필드에는 컬럼 통계가 없습니다. 빈번한 Predicate가 걸리는 필드는 별도 컬럼으로 두는 것이 여전히 권장됩니다.

4.4 Geospatial 타입

V3는 OGC SQL/MM 표준 기반의 Geometry·Geography 타입을 정의합니다.

CREATE TABLE locations (
  id     BIGINT,
  name   STRING,
  geom   GEOMETRY
) USING iceberg
TBLPROPERTIES ('format-version' = '3');
 
-- Spatial Predicate (엔진 함수명은 상이)
SELECT id, name
FROM locations
WHERE ST_Contains(
        ST_GeomFromText('POLYGON((...))'),
        geom);

엔진 간 일관된 표현으로, Spark·Trino·Snowflake·BigQuery에서 같은 공간 데이터를 호환되게 다룰 수 있게 됐습니다(엔진별 함수명은 다르지만 데이터는 호환).

4.5 Row Lineage

각 행에 안정적인 ID와 마지막 갱신 시퀀스를 부여합니다. 두 개의 hidden 컬럼이 추가됩니다.

활용:

• 신뢰 가능한 CDC — 외부 시스템이 _row_id로 행을 추적, 변경 감지를 정확히 표현.
• 재현 가능한 ML 학습 — 학습에 사용한 행 ID 집합을 기록하면, 시간여행만으로는 부족한 "정확히 이 행들"을 재현 가능.
• 데이터 거버넌스 — 행 단위 계보 추적.

-- CDC 패턴 예시
SELECT _row_id,
       _last_updated_sequence_number,
       *
FROM events
WHERE _last_updated_sequence_number > 1024;  -- 마지막 처리한 시퀀스 이후 변경분

4.6 그 외 변화

• multi-arg transform — Partition Transform에 여러 인자를 받을 수 있게 일반화.
• 명시적 nanosecond timestamp — 타임스탬프 정밀도 표준화.
• 개선된 매니페스트 통계 — 새 통계 필드로 Pruning 효율 향상.

5. 한눈에 보는 V1·V2·V3 비교

6. 사양 업그레이드

6.1 V1 → V2

가장 단순한 업그레이드입니다.

ALTER TABLE db.events SET TBLPROPERTIES ('format-version' = '2');

이후:

• 옛 데이터 파일은 그대로 유지됩니다. 새 데이터 파일·delete 파일만 V2 형식으로 추가됩니다.
• 시퀀스 번호가 부여되기 시작합니다(옛 스냅샷은 0 또는 null로 남고, 이후부터 단조 증가).
• 새 쓰기부터 MoR(write.delete.mode = 'merge-on-read') 사용 가능합니다.

체크 포인트:

• 사내 모든 엔진이 V2를 지원하는지 확인합니다(2026년 기준 거의 모든 주요 엔진이 지원).
• 다운그레이드 불가라는 점을 운영팀에 공지합니다.

6.2 V2 → V3

V3는 사양이 풍부해진 만큼, 업그레이드는 더 신중해야 합니다.

ALTER TABLE db.events SET TBLPROPERTIES ('format-version' = '3');

확인할 사항:

• 모든 리더 엔진이 V3를 읽을 수 있는가. 한 엔진이라도 V3를 모르면 그 엔진은 테이블 전체에 대해 실패할 수 있습니다.
• 신규 기능을 곧바로 쓰지 않아도 된다. V3로 올린 뒤에도 Variant·Geospatial·Row Lineage를 안 쓰면 사실상 V2와 동일하게 운영됩니다. V3로 올리는 것은 "옵션을 열어두는" 결정입니다.
• Deletion Vectors는 점진적으로 활성화할 수 있습니다. 새 delete만 vector로, 옛 V2 delete는 그대로 두는 것이 일반적입니다.

6.3 업그레이드 전 점검 체크리스트

• 사내 사용 엔진과 사양 호환 매트릭스 확인 (특히 V3)
• 백업 카탈로그 / 메타데이터 스냅샷 보관
• 운영 자동화 잡이 새 사양에서도 정상 동작하는지 테스트 환경에서 확인
• 모니터링 지표 임계값을 새 사양에 맞춰 조정 (예: deletion vector 크기 지표 추가)
• 변경 사실을 사내 데이터 카탈로그·문서에 반영

7. 엔진별 사양 지원 현황 (2026년 5월 기준)

위 표는 일반적 지원 수준 요약입니다. 실제 도입 시점에는 해당 엔진의 최신 릴리스 노트와 Iceberg 공식 사양 문서의 호환성 표를 함께 확인할 것을 권합니다.

핵심 관찰:

• V1·V2는 모든 주요 엔진에서 충분히 성숙합니다.
• V3는 2026년 현재 도입 초기이며, 엔진별 지원 격차가 큽니다.
• 멀티-엔진 환경에서 V3를 적용하려면 가장 약한 엔진의 지원 수준에 맞춰야 합니다.

8. 어떤 버전을 선택할 것인가

8.1 신규 테이블

• 기본 권고: V2. 모든 주요 엔진에서 안정적이며, MoR·partition evolution·시퀀스 번호 등 운영 필수 기능을 모두 제공합니다.
• V3로 시작할 때: 사내 모든 엔진이 V3를 지원하고, Variant·Geospatial·Row Lineage 중 하나 이상의 명확한 사용 사례가 있는 경우.

8.2 기존 V1 테이블

• append-only 분석 테이블: V1을 유지해도 큰 문제 없음. 다만 운영 일관성·partition evolution 가능성을 생각하면 V2 업그레이드 권장.
• CDC·MERGE·정정이 시작될 가능성이 있는 테이블: 즉시 V2로 업그레이드.

8.3 기존 V2 테이블

• 당장 V3로 올릴 필요는 없음. V3 신규 기능을 쓸 명확한 이유가 생긴 뒤에 업그레이드.
• 사내 엔진의 V3 지원이 충분히 성숙한 뒤 도입하는 것이 안전합니다.

8.4 워크로드별 선택 가이드

9. 사양 버전과 함께 결정해야 할 것들

사양 버전 선택은 단독으로 끝나지 않습니다. 다음 결정과 함께 이뤄져야 운영이 깔끔해집니다.

9.1 카탈로그

• V3 메타데이터를 카탈로그가 이해해야 합니다. REST Catalog 사양(v1.6 이후) 또는 Glue·Unity·Polaris의 V3 지원 버전 확인.

9.2 쓰기 모드 (CoW vs MoR)

• V2/V3로 올렸어도, 분석 중심 테이블은 여전히 CoW가 합리적일 수 있습니다.
• 테이블 단위로 write.delete.mode, write.update.mode, write.merge.mode를 명시합니다.

9.3 운영 자동화

• V2 이후 컴팩션·만료·고아 정리는 선택이 아닌 필수입니다.
• delete file/data file 비율, deletion vector 누적량을 모니터링 지표로 추가합니다.

9.4 엔진 표준

• 멀티-엔진 환경에서는 가장 약한 엔진이 사양 버전을 제약합니다.
• 새 엔진을 도입할 때마다 사양 호환성을 점검하는 절차를 운영 프로세스에 포함합니다.

10. 정리

• V1은 Iceberg의 기본 모델을 정립했지만, row-level 연산을 다루지 못합니다. 2026년 신규 테이블에서 V1을 선택할 이유는 거의 없습니다.
• V2는 시퀀스 번호와 delete file을 도입해 MoR·CDC·정정 워크로드를 가능하게 만들었습니다. 2026년 현재 신규 테이블의 표준 권고입니다.
• V3는 Deletion Vectors·Variant·Geospatial·Row Lineage·default value 등으로 표현력과 효율을 한 단계 끌어올립니다. 엔진 지원이 충분히 성숙한 영역에서 점진 도입을 권합니다.
• 사양 버전은 카탈로그·쓰기 모드·운영 자동화·엔진 표준과 함께 결정되어야 합니다.

Iceberg 사양은 빠르게 진화하고 있고, 그 진화의 방향은 일관됩니다 — 개체 스토리지 위에 데이터베이스 의미론을 더 깊이, 더 효율적으로 구현하는 쪽입니다. 사양 버전을 이해하는 것은 단순한 기술 호기심이 아니라, 도입 의사결정과 운영 비용을 직접 좌우하는 핵심 변수입니다.

함께 보면 좋은 글

• Apache Iceberg 백서 — 차세대 Lakehouse 테이블 포맷의 구조와 도입 전략
• Delta Lake 완벽 가이드 — Delta Table 개념부터 Iceberg 비교까지

참고 자료

• Apache Iceberg 공식 사양 — iceberg.apache.org/spec
• Iceberg V2 사양 — format-version: 2 도입 PR 및 디자인 문서
• Iceberg V3 사양 — Variant·Geospatial·Row Lineage 제안 문서
• Puffin 파일 포맷 — iceberg.apache.org/puffin-spec
• Roaring Bitmap — roaringbitmap.org