Trino 쿼리를 통한 Iceberg 내부 살펴보기

 

📌 1. Iceberg 파일 구조 개요

Iceberg 테이블은 HDFS, S3, HDFS-compatible storage 등에 저장되며 크게 두 가지 계층으로 나뉩니다:

table_name/
 ├── data/                  # 실제 데이터 파일 (Parquet/ORC/Avro)
 │    ├── ...partition.../
 │    │    └── 00000-aaaa.parquet
 │    └── ...
 └── metadata/              # 테이블 스냅샷과 스키마/파티션 정의
      ├── version-hash.json
      ├── v0001.metadata.json
      ├── v0002.metadata.json
      └── snapshots/

 

구성 요소

• 데이터 파일 (data/)
  • 실질적인 레코드가 저장되는 Parquet/ORC 파일
  • 파티션 규칙에 따라 디렉터리 구조로 나뉨
• 매니페스트 파일 (manifest)
  • 데이터 파일 리스트 + min/max statistics 보관
  • 파일 단위 pruning에 활용
• 매니페스트 리스트 (manifest list)
  • 하나의 스냅샷을 구성하는 매니페스트들의 목록
• 스냅샷 (snapshot)
  • 테이블의 특정 시점 상태 (매니페스트 리스트를 가리킴)
• 메타데이터 JSON (v000N.metadata.json)
  • 테이블 전체 이력과 모든 스냅샷/스키마 정의를 관리

📌 2. Iceberg 스냅샷의 연결 관계

아키텍처 플로우 (간단 버전):

metadata.json
   │
   └─ snapshot → manifest list → manifest → data files

 

• metadata.json: 스냅샷 목록 + 현재 활성 snapshot ID
• snapshot: manifest list 파일 경로 + 요약 정보
• manifest list: 여러 manifest 파일 경로 모음
• manifest: 개별 데이터 파일 경로와 통계
• data file: 실제 row 데이터 저장

 

📌 3. $snapshots에서 Manifest List 확인하기

Trino에서 $snapshots를 조회하면 manifest list 경로를 볼 수 있습니다.

SELECT snapshot_id,
       committed_at,
       manifest_list
FROM table_name$snapshots
ORDER BY committed_at DESC
LIMIT 3;

 

예시 결과

snapshot_id	committed_at	manifest_list
4151342690114749344	2025-07-27 00:00	hdfs://warehouse/table_name/metadata/snap-4151342690114749344-1-ml.avro
4151342690114749221	2025-07-26 00:00	hdfs://warehouse/table_name/metadata/snap-4151342690114749221-1-ml.avro

• manifest_list: manifest list 파일 경로
• Iceberg는 이 파일을 통해 어떤 manifest들이 이 스냅샷에 속하는지 알 수 있음

---

📌 4. Manifest List 내부 구조

manifest list 파일 자체는 Avro 포맷으로 저장되어 있으며, 각 행은 하나의 manifest 파일을 나타냅니다.

 

manifest_path	manifest 파일 경로
manifest_length	manifest 파일 크기
partition_spec_id	어떤 partition spec에 해당하는지
added_snapshot_id	어떤 스냅샷에서 추가됐는지
existing	기존 데이터 파일 개수
added_files_count	새로 추가된 데이터 파일 개수
deleted_files_count	삭제된 데이터 파일 개수

 

 

 

📌 5. Manifest 파일 구조 (참고)

각 manifest 파일에는 실제 데이터 파일 정보가 들어 있습니다:

• data_file_path: parquet/orc 파일 경로
• partition_data: 파티션 값
• record_count: 파일의 레코드 수
• lower_bounds / upper_bounds: 각 컬럼의 최소/최대 값 (→ pruning 가능)
• file_size_in_bytes

이 덕분에 Iceberg는 **파일 단위 프루닝(file pruning)**을 할 수 있음.

 

📌 6. Trino에서 $snapshots 메타테이블

Trino는 Iceberg 테이블 메타데이터를 SQL로 조회할 수 있게 $snapshots를 제공합니다.

SELECT snapshot_id,
       committed_at,
       parent_id,
       operation,
       summary
FROM table_name$snapshots
ORDER BY committed_at DESC;

 

출력 예시

 

snapshot_id	committed_at	parent_id	operation	summary
4151342690114749344	2025-07-27 00:00	4151342690114749221	append	{"added-records":"12000"}
4151342690114749221	2025-07-26 00:00	NULL	overwrite	{"deleted-records":"500"}

 

• snapshot_id: 스냅샷 고유 ID
• parent_id: 이전 스냅샷 (branch 구조 추적)
• operation: append / overwrite / delete 등
• summary: record count, 파일 수, 파티션 통계 등

👉 $snapshots는 Iceberg 테이블의 전체 히스토리와 파일 구조 추적의 시작점

---

📌 7. Trino에서 $refs (Branch / Tag)

$refs는 현재 살아있는 참조 (branch, tag) 목록을 보여줍니다.
즉, 어떤 snapshot_id를 보호하고 있는지 확인 가능.

 

SELECT name,
       type,
       snapshot_id,
       min_snapshots_to_keep,
       max_snapshot_age_ms,
       max_ref_age_ms
FROM table_name$refs;

 

 

 

name	type	snapshot_id	min_snapshots_to_keep	max_snapshot_age_ms	max_ref_age_ms
main	BRANCH	4151342690114749344	1	NULL	NULL
month_end_202507	TAG	4151342690114749221	NULL	NULL	31536000000

• name: 참조 이름 (main, branch명, tag명)
• type: BRANCH / TAG
• snapshot_id: 해당 참조가 가리키는 snapshot
• 보존 정책 필드: 만료 정책 (ms 단위)

👉 $refs를 보면 어떤 snapshot이 expire 대상에서 제외되는지 한눈에 알 수 있음

 

 

 

📌 8. $snapshots + $refs로 Iceberg 구조 이해하기

예시:

SELECT r.name, r.type, r.snapshot_id, s.committed_at, s.operation
FROM table_name$refs r
JOIN table_name$snapshots s
  ON r.snapshot_id = s.snapshot_id
ORDER BY s.committed_at DESC;

 

결과:

 

name	type	snapshot_id	committed_at	operation
main	BRANCH	4151342690114749344	2025-07-27 00:00	append
month_end_202507	TAG	4151342690114749221	2025-07-26 00:00	overwrite

 

• main branch → 최신 snapshot
• month_end_202507 tag → 이전 snapshot 고정 보존

이 구조를 통해:

• 데이터 파일 계층이 어떻게 스냅샷으로 묶여있는지 확인 가능
• 어떤 snapshot이 보존되고 어떤 건 expire 대상인지 식별 가능

 

✅ 정리

• data/ → 실제 파티션별 데이터 파일
• metadata/ → snapshot/manifest 정의
• $snapshots → 모든 snapshot 이력 (commit, operation, parent 관계)
• $refs → branch/tag → snapshot 매핑, 보존 정책 확인
• Trino에서는 FOR VERSION AS OF 'tag_name' 문법으로 태그 기반 조회 가능

 

.

---

📌 9. Manifest List ↔ Snapshot ↔ Ref 관계 쿼리 예시

Trino에서 manifest list를 확인하고 어떤 태그/브랜치가 참조 중인지 조회:

SELECT r.name AS ref_name,
       r.type,
       s.snapshot_id,
       s.committed_at,
       s.manifest_list
FROM table_name$refs r
JOIN table_name$snapshots s
  ON r.snapshot_id = s.snapshot_id
ORDER BY s.committed_at DESC;

 

 

📌 그림으로 요약 (텍스트 다이어그램)

[table_name$refs]
   │   (태그: month_end_202507 → snapshot_id=4151342690114749344)
   │
   ▼
[table_name$snapshots]
   snapshot_id=4151342690114749344
   manifest_list = snap-4151342690114749344-1-ml.avro
   │
   ▼
[manifest list]
   ├─ manifest-001.avro
   └─ manifest-002.avro
       │
       ├─ data-0001.parquet
       ├─ data-0002.parquet
       └─ ...

 

✅ 정리

• $snapshots.manifest_list → 특정 snapshot이 참조하는 manifest list 파일 경로
• manifest list 파일 → 여러 manifest 파일을 가리키는 Avro
• manifest 파일 → 실제 데이터 파일(Parquet 등) + 통계 정보
• $refs와 조합해 "어떤 태그/브랜치가 어떤 manifest list를 보호 중인지" 파악 가능