도구가 지원하는 범위에서 포맷을 선택하라

읽는 데 약 24분분 걸린다, 11절에 5개 예제이(가) 있음.

2026.11.10판 예제 통과 2026년 11월 20 39개 예제 중 39개 통과 변경 사항

AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식

영어판 2026.11.10판을 번역한 것이다. 원문 읽기

이 장을 읽고 나면 테이블을 읽거나 쓰는 모든 도구를 나열하고, 고정된 버전에서 각 도구가 무엇을 지원하는지 측정하며, 그 측정값으로 포맷과 포맷의 기능을 선택할 수 있다.

1장부터 9장까지 테이블 하나, wiki.pageviews_hourly는 Apache Iceberg, Delta Lake, DuckLake라는 세 가지 포맷으로 전체 수명 주기를 거쳤다. 각 포맷은 같은 작업을 서로 다른 방식으로 수행했고, 각 라이브러리는 그 작업 중 서로 다른 일부만 지원했다. 여러분이 마주한 선택은 어떤 포맷이 일반적으로 가장 좋은가가 아니다. 팀의 모든 도구가 실행 중인 버전에서 열고, 변경하고, 정리할 수 있는 포맷이 무엇인가이다. 이 장은 그것을 측정하는 방법을 제시하고, 이 책에서 고정한 버전의 측정값을 보여 주며, 선택을 위한 짧은 지침을 제공한다.

선택은 읽는 쪽에 달려 있으며, 이어지는 사례인 wiki.pageviews_hourly에는 세 가지가 있다. DuckDB로 질의하는 대시보드, pyiceberg로 데이터를 추가하는 파이프라인, deltalake로 Delta Lake 사본을 읽는 보관 작업이다. 각 읽기 도구는 자신의 고정된 버전이 있으며, 다른 도구가 쓴 데이터를 모두 열 수 있어야 한다. 이 장의 나머지는 이러한 상황에 대비하도록 구성되어 있다.

세 가지 이유로 이 선택은 보기보다 어렵다. 삭제, 이름 변경, 파티션 변경처럼 포맷마다 가장 크게 다른 기능은 팀이 가장 먼저 필요로 하는 기능이다. 또한 각 라이브러리는 자체 일정에 따라 바뀌므로, 어떤 도구가 한 버전에서 읽는 테이블이 다른 버전에서는 열리지 않을 수 있다. 그리고 한 컴퓨터에서 통과한 검사는 다른 도구가 실행 중인 버전에 대해 아무것도 알려 주지 않는다. 이 장의 각 절은 이 문제를 차례로 다룬다.

선택하기 전에 지원 여부를 측정한다

마지막으로 변경된 판: 2026.11.7판

형식의 이름만으로는 도구가 무엇을 지원하는지 알 수 없다. 지원 여부는 특정 버전의 도구에 속한다. 쓰기 도구가 만들 수 있는 기능을 읽기 도구가 열지 못할 수 있고, 공급업체의 페이지는 노트북에 설치된 라이브러리가 아니라 공급업체의 엔진을 설명한다. 따라서 형식이 아니라 읽기 도구에서 출발한다. 테이블을 읽을 모든 도구를 버전과 함께 적고, 사용할 계획인 각 기능을 그 버전들에서 하나씩 시험한다.

아래의 각 측정은 읽기 도구에서 출발하여 그 도구에서 기능 하나를 시험한다. pyiceberg에는 형식 버전 2 테이블에 삭제를 수행한 다음 버전 3을 요청한다(iceberg-format-versions). deltalake에는 삭제 벡터를 켜고 다시 읽어 확인한다(feature-check). ducklake-catalog-version 예제는 DuckLake 카탈로그의 버전을 출력하고, ducklake-delete-files 예제와 ducklake-inlined-delete 예제는 작은 삭제와 큰 삭제 뒤에 삭제 파일의 수를 센다. 모든 예제는 결과마다 레이블이 붙은 한 줄을 출력하므로, 출력을 지원 매트릭스의 표 및 직접 사용하는 읽기 도구와 비교할 수 있다.

테이블을 책임지는 사람은 읽기 도구가 실행되는 머신에서 측정해야 하며, 버전이 다른 개발자의 노트북에서 해서는 안 된다. 이 문장은 다음과 같이 바꾼다: 읽기 도구가 실행되는 머신에서 측정을 수행해야 한다. 기록은 읽기 도구마다 한 행을 두는 작은 표로 남긴다. 열은 읽기 도구, 고정된 버전, 테이블에 필요한 기능, 측정한 날짜이다. 측정하지 않은 기능은 지원하지 않는 것으로 간주하며, 이 규칙은 이 장의 뒷부분에서 나오는 대부분의 실패를 막아 준다.

읽기 도구 고정된 버전 필요한 기능 측정일
pyiceberg 0.12.0 형식 버전 2 쓰기, 삭제 실행한 날짜

출력된 각 줄은 한 도구의 한 버전에서 성립하는 주장으로 읽는다. 쓰기가 거부되었다고 알려 주는 줄은 성공했다고 알려 주는 줄만큼 유용하다. 거부는 어떤 형식 버전을 포기해야 하는지 알려 주기 때문이다. 오류를 잡는 예제는 메시지가 아니라 클래스 이름을 출력하므로, 라이브러리가 오류 문구를 바꾸어도 출력은 같게 유지된다.

작업 규칙: 형식 버전이나 기능을 선택하기 전에 각 읽기 도구를 그 도구의 고정된 버전에서 측정한다. 각 결과는 측정한 버전과 함께 기록한다. 읽기 도구의 버전이 바뀔 때마다 측정을 다시 수행하며, 공급업체 페이지의 지원 표를 재사용하지 않는다.

고정된 도구가 한 일 읽기

이 표들은 이 책의 실행에서 고정된 도구가 한 일을 보여 준다. 각 열은 하나의 도구에 해당한다. Iceberg는 pyiceberg, Delta Lake는 deltalake, DuckLake는 DuckDB의 DuckLake 확장이다. 고정된 버전은 pyiceberg 0.12.0, deltalake 1.6.6, DuckDB 2.0.0이다. DuckDB 2.0.0은 장기 지원 릴리스이며, 날짜는 2026년 10월 21일이다(DuckDB 릴리스 일정). DuckLake 1.0은 2026년 4월 13일에 릴리스되었다(DuckLake 릴리스 일정). 이 고정 버전에서 카탈로그는 버전 1.1을 보고하며, 독자가 열어야 하는 버전이 바로 이것이다. 확장은 별도의 버전을 가진다. DuckDB는 확장의 빌드를 417a9117f5로 보고하고, 확장은 DuckDB 2.0.0와 함께 배포되므로 확장의 버전은 DuckDB의 버전을 따른다. 마지막 열에는 각 셀의 근거가 되는 예제나 출처를 적었다. 표에 나타나지 않음은 기능이 없다는 뜻이 아니라 이 책에 해당 내용이 빠져 있다는 뜻이다.

ducklake-catalog-version.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Attach a DuckLake catalog and print its catalog version, which readers must open, and the build of the DuckLake extension that DuckDB loaded. The point rests on the first printed line."""from lib.lakehouse import attach_ducklake, connect_ducklake, new_warehousedef main():    with new_warehouse() as wh:        con = connect_ducklake(wh.con)        # the alias also names the catalog's metadata schema, which the next line reads        attach_ducklake(con, "probe", wh.root)        # the version is stored as a key and value row in the metadata table; the one row, first column        version = con.execute("SELECT value FROM __ducklake_metadata_probe.ducklake_metadata WHERE key = 'version'").fetchall()[0][0]        print("ducklake catalog version:", version)        # a build hash, not a release number        extension = con.execute("SELECT extension_version FROM duckdb_extensions() WHERE extension_name = 'ducklake'").fetchall()[0][0]        print("ducklake extension version:", extension)if __name__ == "__main__":    main()
출력python ducklake-catalog-version.py
ducklake catalog version: 1.1
ducklake extension version: 417a9117f5

버전 쓰기와 읽기

버전과 읽기 pyiceberg deltalake DuckLake 나오는 곳
행을 커밋으로 기록한다 지원한다 지원한다 지원한다 세 시간 분량을 적재하기
번호로 이전 커밋을 읽는다 지원한다. 스냅샷으로 읽는다 지원한다. 버전으로 읽는다 지원한다. 스냅샷으로 읽는다 아이스버그, 델타와 덕레이크
포맷 버전 3을 생성한다 지원하지 않는다. 오류가 발생한다 — — 예제
열 이름을 바꾼다 지원한다. 필드 ID로 처리한다 지원하지 않는다. 아무 동작도 하지 않고 조용히 넘어간다 여기에서는 다루지 않는다 아이스버그, deltalake
생성 시 열 매핑을 지정한다 — 지원한다 — deltalake

변경과 정리

변경과 정리 pyiceberg deltalake DuckLake 설명한 곳
행 삭제 파일을 다시 쓴다 파일을 다시 쓴다 삭제 파일을 쓴다 5장
삭제 파일 기록 여부 없음 없음 있음, 인라인된 경우는 제외 형식 버전, 기능 확인, DuckLake, 인라인
업서트 또는 병합 업서트, 스냅샷 여러 개 여기서는 다루지 않음 MERGE INTO 업서트, MERGE
파티셔닝 변경 기존 파일은 이전 명세를 유지한다 스키마 모드로 덮어쓴다 ALTER TABLE로 변경한다 4장, 다른 형식
작은 파일 압축 방법 없음, 테이블을 덮어쓴다 optimize.compact() 인접한 파일을 병합한다 Iceberg, deltalake, DuckLake
스냅샷 만료 ID 또는 older_than로 지정하며 파일은 삭제하지 않는다 보존 기간에 따라 vacuum한다 만료한 뒤 정리한다 Iceberg, deltalake, DuckLake
ducklake-delete-files.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Load six hours into a DuckLake table with data inlining off, then count the delete files that a small and a large delete write. The point rests on the delete-file line after the small delete."""from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, new_warehouse, read_cut_hourLOW_VIEWS = 180  # few rows of hour 02 fall below thisVERY_LOW_VIEWS = 1000  # most of the table's rows fall below thisdef delete_files(con):    # one row per data file, so the rows with a delete file count the files a delete touched    return con.execute(f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "                       "WHERE delete_file IS NOT NULL").fetchall()[0][0]def main():    with new_warehouse() as wh:        con = connect_ducklake(wh.con)        # 0 turns inlining off, so a delete is written as a delete file rather than kept in the catalog        create_ducklake_table(con, wh.root, inlining_row_limit=0)        table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"        for hour in range(6):            con.register("hour", read_cut_hour(hour))            con.execute(f"INSERT INTO {table} SELECT * FROM hour")            con.unregister("hour")        con.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")        print("rows left after the small delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])        print("delete files after the small delete:", delete_files(con))        # no hour filter, so this delete reaches all six hours        con.execute(f"DELETE FROM {table} WHERE views < {VERY_LOW_VIEWS}")        print("rows left after the large delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])        print("delete files after the large delete:", delete_files(con))if __name__ == "__main__":    main()
출력python ducklake-delete-files.py
rows left after the small delete: 2995
delete files after the small delete: 1
rows left after the large delete: 195
delete files after the large delete: 6
ducklake-inlined-delete.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Repeat `ducklake-delete-files` with DuckLake's default inlining, to show that the small delete writes no delete file. The point rests on the delete-file line after the small delete."""from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, new_warehouse, read_cut_hourLOW_VIEWS = 180  # few rows of hour 02 fall below thisVERY_LOW_VIEWS = 1000  # most of the table's rows fall below thisdef delete_files(con):    # one row per data file, so the rows with a delete file count the files a delete touched    return con.execute(f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "                       "WHERE delete_file IS NOT NULL").fetchall()[0][0]def main():    with new_warehouse() as wh:        con = connect_ducklake(wh.con)        # None keeps DuckLake's default inlining; ducklake-delete-files passes 0 to turn it off        create_ducklake_table(con, wh.root, inlining_row_limit=None)        table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"        for hour in range(6):            con.register("hour", read_cut_hour(hour))            con.execute(f"INSERT INTO {table} SELECT * FROM hour")            con.unregister("hour")        con.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")        print("rows left after the small delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])        print("delete files after the small delete:", delete_files(con))        # no hour filter, so this delete reaches all six hours        con.execute(f"DELETE FROM {table} WHERE views < {VERY_LOW_VIEWS}")        print("rows left after the large delete:", con.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0])        print("delete files after the large delete:", delete_files(con))if __name__ == "__main__":    main()
출력python ducklake-inlined-delete.py
rows left after the small delete: 2995
delete files after the small delete: 0
rows left after the large delete: 195
delete files after the large delete: 6

카탈로그와 DuckDB

카탈로그와 DuckDB pyiceberg deltalake DuckLake 소개된 곳
카탈로그 필요 여부 필요하다. SQL 카탈로그 필요 없다. 경로로 찾는다 필요하다. 카탈로그 파일 8장, 경로로 찾기, 카탈로그 파일
DuckDB의 읽기 Arrow를 통해 읽는다 QueryBuilder에서 Arrow를 통해 읽는다 네이티브로 읽는다 1장, 9장, 8장
DuckDB의 쓰기 — — SQL을 통해 네이티브로 쓴다 8장

DuckDB 자체의 delta 확장은 deltalake와는 별개의 경로이다. 이 확장은 Delta Lake 테이블을 쓸 수 있으며, 이는 아래의 선택 가이드에서 다룬다.

작업 규칙: 각 셀은 그 셀이 가리키는 예제나 출처와 대조하여 읽는다. 뒷받침하는 예제가 없는 셀은 독자를 대상으로 검증해 볼 주장일 뿐, 그대로 의존할 내용이 아니다.

pyiceberg는 버전 3 테이블을 쓰지 않는다

마지막으로 변경된 판: 2026.11.7판

Iceberg 명세의 버전 3 절은 이진 삭제 벡터(deletion vector)를 행 수준 삭제 형식으로 정한다. 이 절은 "작성기는 v3 테이블에 새 위치 삭제 파일을 추가할 수 없다"라고 밝힌다(Iceberg spec). 같은 절은 새 행에 대한 행 계보(row lineage), 열 기본값, variant 타입, 나노초 타임스탬프도 추가한다.

iceberg-format-versions.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Create a format version 2 Iceberg table, delete rows from it, then ask pyiceberg for format version 3. The point rests on the last printed line, which shows the refusal."""from pyiceberg.expressions import LessThanfrom lib.lakehouse import create_iceberg_table, new_warehouse, read_cut_hour, scan_arrowLOW_VIEWS = 180  # about one row in six of hour 00 falls below thisdef main():    with new_warehouse() as wh:        table = create_iceberg_table(wh, properties={"format-version": "2"})  # table properties are strings, so the version is quoted        table.append(read_cut_hour(0))        print("format version:", table.metadata.format_version)        # scan_arrow reads the current snapshot, so the count moves with each commit        before = scan_arrow(table).num_rows        table.delete(LessThan("views", LOW_VIEWS))        print("rows deleted:", before - scan_arrow(table).num_rows)        # content 0 marks a data file; any other value marks a delete file        contents = table.inspect.files().column("content").to_pylist()        print("delete files after the delete:", sum(1 for content in contents if content != 0))        for number, snapshot in enumerate(table.metadata.snapshots, start=1):            print(f"snapshot {number} operation:", snapshot.summary.operation.value)        # pyiceberg refuses version 3 by raising, so the refusal is caught here and its class printed        try:            create_iceberg_table(wh, identifier="wiki.format_three", properties={"format-version": "3"})        except NotImplementedError as exc:            print("format version 3 create:", type(exc).__name__)        else:            print("format version 3 create: created")if __name__ == "__main__":    main()
출력python iceberg-format-versions.py
format version: 2
rows deleted: 82
delete files after the delete: 0
snapshot 1 operation: append
snapshot 2 operation: overwrite
format version 3 create: NotImplementedError

이 고정 버전의 pyiceberg는 형식 버전 2를 쓴다. 예제는 버전 2를 요청하고 테이블의 버전을 출력하며, 그 값은 2이다. 형식 버전 3을 요청하면 NotImplementedError가 발생하므로, 이 작성기에서는 버전 3의 기능을 하나도 사용할 수 없다.

형식 버전 2도 삭제 파일을 허용하지만(5장), 이 고정 버전의 pyiceberg는 삭제할 때 대상이 되는 데이터 파일을 다시 쓴다. 테이블에서 82개 행이 사라졌고 삭제 파일은 0개가 남았다. 두 스냅샷은 append와, 삭제에 해당하는 overwrite이다. 선택하기 전에 자신의 테이블을 복사해 그 재작성을 측정하라.

기능 Iceberg v3 명세 이 고정 버전의 pyiceberg
이진 삭제 벡터 행 수준 삭제 형식 쓰지 않음
위치 삭제 파일 레거시, 형식 버전 2 테이블에만 해당 쓰지 않음
행 계보, 기본값, variant, 나노초 타임스탬프 버전 3에 포함 사용할 수 없음: 버전 3 테이블이 없음

작업 규칙: 이 고정 버전의 pyiceberg로는 형식 버전 2를 쓰고, 어떤 독자(reader)에게도 버전 3 기능을 약속하지 않는다. 사용하는 작성기가 버전 3을 만들고 사용하는 모든 독자가 이를 열 수 있을 때만 버전 3을 선택하며, 둘 다 각자의 고정 버전에서 확인한다.

삭제 벡터에는 프로토콜 업그레이드가 필요하다

마지막으로 변경된 판: 2026.11.10판

Delta Lake 프로토콜은 링크가 가리키는 릴리스 태그 기준으로, 삭제 벡터가 있는 테이블에 리더 버전 3과 라이터 버전 7이 필요하며 두 기능 목록 모두에 deletionVectors 기능이 있어야 한다고 명시한다. 또한 리더는 테이블을 읽기 전에 리더 목록에 있는 모든 기능을 구현해야 한다고 명시한다(Delta protocol). Delta 테이블의 프로토콜에 있는 리더 기능은 모든 리더가 그 기능을 처리한다는 약속이므로, 그 기능이 없는 리더는 테이블을 올바르게 읽을 수 없다.

feature-check.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Turn on deletion vectors in a Delta Lake table, delete the rows below 180 views, and print the protocol the table declares. The point rests on the reader features line, which lists what a reader must implement."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_deltaLOW_VIEWS = 180  # about one row in six of hour 00 falls below thisdef deletion_vector_files(path):    """Count files under the table folder that are not Parquet or the Delta log."""    # the log holds JSON commits and checkpoints, not deletion vectors, so it is skipped    return sum(1 for item in path.rglob("*")               if item.is_file() and item.suffix != ".parquet" and "_delta_log" not in item.parts)def main():    with new_warehouse() as wh:        path = wh.root / "dv_table"        # delta.enableDeletionVectors is the table property that turns deletion vectors on, set when the table is written        write_deltalake(str(path), read_cut_hour(0), configuration={"delta.enableDeletionVectors": "true"})        table = DeltaTable(str(path))        protocol = table.protocol()        print("minimum reader version:", protocol.min_reader_version)        print("minimum writer version:", protocol.min_writer_version)        # sorted so the printed list reads the same on every run        print("reader features:", ", ".join(sorted(protocol.reader_features)))        # read_delta reads through deltalake's QueryBuilder, the only Delta read path in this book        before = read_delta(str(path)).num_rows        metrics = table.delete(f"views < {LOW_VIEWS}")        print("rows deleted:", before - read_delta(str(path)).num_rows)        # the delete's num_removed_files metric, which counts the data files it replaced        print("data files rewritten:", metrics["num_removed_files"])        print("rows through QueryBuilder:", read_delta(str(path)).num_rows)        print("deletion vector files:", deletion_vector_files(path))if __name__ == "__main__":    main()
출력python feature-check.py
minimum reader version: 3
minimum writer version: 7
reader features: deletionVectors, timestampNtz, variantType
rows deleted: 82
data files rewritten: 1
rows through QueryBuilder: 417
deletion vector files: 0

이 설정을 켜면 리더가 지원해야 하는 범위가 달라진다. 설정을 켜고 나면 테이블은 최소 리더 버전 3와 최소 라이터 버전 7를 선언한다. 리더 기능은 deletionVectors, timestampNtz, variantType이며, 리더는 이 기능을 하나도 빠짐없이 구현해야 한다. 우리는 삭제 벡터 설정만 지정했으므로, 나머지 두 기능은 deltalake가 스스로 추가했다.

이 고정 버전에서 deltalake는 기능을 선언하지만 여전히 파일을 다시 써서 삭제한다. 조회수 180 미만인 행을 삭제했을 때 82개 행이 제거되었고 데이터 파일 1개가 다시 쓰였으며, 테이블에 있는 삭제 벡터 파일은 0개다. 그 뒤 QueryBuilder가 읽은 행은 417개다. 이 책은 8장에서 보듯 Delta 테이블을 오직 QueryBuilder로만 읽는다.

삭제 벡터만이 아니라 목록의 모든 기능이 중요하다. timestampNtz나 variantType를 갖추지 못한 리더는 deletionVectors를 갖추지 못한 리더와 같은 문제를 겪는다. 변경할 때마다 출력된 기능 목록을 각 리더 자체의 목록과 비교해야 한다.

따라서 삭제 벡터 설정은 테이블의 모든 리더에게 프로토콜 변경이며, 어떤 리더를 시험해 보기도 전에 쓰기는 성공한다. 사용하는 리더 집합의 모든 리더가 deletionVectors 기능을 구현할 때에만 이 설정을 켜야 한다. 그렇지 않으면 copy-on-write를 유지한다.

여기서 말하는 리더 점검은 첫 운영 쓰기 전에 리더 자체의 인터페이스로 테이블을 여는 것이다. 이 사례의 Delta Lake 사본에서 그 점검은 QueryBuilder를 통한 읽기와 프로토콜 읽기이며, 둘 다 feature-check 예제에 들어 있다.

작업 규칙: 삭제 벡터는 각 리더가 자신의 버전에서 기능을 지원하는지 확인한 뒤에만 활성화한다. 변경할 때마다 테이블의 프로토콜을 다시 읽어 확인하고, 시험을 거친 집합 밖의 리더가 열 수 있는 테이블에는 copy-on-write를 유지한다.

새 테이블을 위한 점검 목록

둘 이상의 도구가 여는 테이블을 만들기 전에 이 목록을 사용한다. 각 항목은 지원 매트릭스와 삭제 벡터 절에서 확인한 위험을 하나씩 막는다.

  1. 모든 읽기 도구와 쓰기 도구를 버전과 함께 나열한다. 목록에서 빠진 도구는 검증하지 않은 읽기 도구이며, 실패하는 것은 바로 그 도구가 된다.
  2. 테이블에 필요한 각 기능마다, 이 장의 예제처럼 도구별 지원 여부를 측정한다. 쓰기 도구만이 아니라 읽기 도구도 측정한다. 쓰기에 성공했다는 사실은 쓰기 도구가 파일을 만들 수 있다는 것만 증명하기 때문이다.
  3. 형식 버전과 프로토콜은 의도적으로 설정한다. 설정한 값을 다시 출력해 확인하고, 각 읽기 도구로 테이블을 읽는다. 직접 고르지 않은 기본값은 받아들이지 않는다.
  4. 집합 안의 읽기 도구 하나라도 지원하지 않는 형식 버전이나 기능은 거부한다. 다른 읽기 도구에 아무리 유용한 기능이라도, 읽기 도구 하나가 열 수 없는 테이블은 장애다.
  5. 측정한 지원 범위가 허용하는 곳에서만 이름 변경을 약속한다. Iceberg는 필드 ID로 이름을 변경한다. deltalake는 이 고정 버전에서 이름 변경을 지원하지 않으므로 대신 재작성을 계획하고, 이후에 열 이름을 확인한다.
  6. 모든 읽기 도구를 삭제 벡터로 검증하기 전까지는 삭제에 단순한 쓰기 시 복사(copy-on-write) 경로를 유지한다. 쓰기 시 복사는 파일을 다시 쓰는 비용이 들지만 어디서나 열린다.
  7. 업그레이드는 읽기 도구, 쓰기 도구, 프로토콜 순서로 계획한다. 각 단계 뒤에 테이블을 읽고, 읽기 도구가 실패하면 중단한다.
  8. 고정 버전이 바뀔 때마다 측정을 다시 실행하고, 새 버전을 읽기 도구 표에 기록한다.

작업 규칙: 이 목록을 테이블의 설계 노트와 함께 보관한다. 그러면 다음에 읽기 도구를 추가하는 사람이 같은 기록에서 시작할 수 있다. 최신으로 유지한 목록은 읽기 실패 뒤에 다시 만든 목록보다 비용이 적게 든다.

독자를 기준으로 형식 고르기

독자를 측정한 뒤에 이 안내를 사용한다. 첫 번째 열은 형식이 아니라 상황이다. 이 표는 측정한 독자 집합을 형식에 대응시킬 뿐이며, 측정을 대신하지 않는다.

상황이 다음과 같다면 선택 이유
pyiceberg와 DuckDB가 테이블을 읽는다 Iceberg, 형식 버전 2 pyiceberg가 이를 읽고, DuckDB가 그 출력을 질의한다
독자가 여럿이며 제자리 이름 변경이 필요하다 Iceberg 3장에서 보듯이 이름을 바꿔도 필드 ID가 유지된다
DuckDB가 유일한 엔진이며 SQL로 변경하고 싶다 DuckLake 삭제, 병합, 파티션 변경을 SQL로 실행한다
Delta 테이블이 이미 있고 deltalake가 이를 읽는다 Delta Lake 유지, 이름 변경은 보장하지 않음 파티션은 덮어쓰기로 바꾸고, 변경할 때마다 다시 읽어 확인한다
DuckDB로 Delta 테이블을 변경하고 싶다 이 버전 조합에서는 불가 DuckDB는 추가만 할 수 있으므로 갱신과 삭제에는 deltalake를 사용한다

DuckDB의 delta 확장은 Delta Lake 테이블을 쓸 수 있다. 고정한 릴리스 2.0.0의 DuckDB 문서에 따르면 테이블을 만들고 여기에 추가할 수 있으며, UPDATE, DELETE, MERGE INTO, ALTER TABLE, DROP TABLE는 지원하지 않는 것으로 나열되어 있다(DuckDB delta docs, Limitations). 이 책의 어떤 예제도 이 확장을 실행하지 않는다. 예제는 실행 시점에 아무것도 설치하지 않고 각 형식의 자체 라이브러리를 사용한다. 따라서 독자는 테이블을 쓰는 라이브러리를 그대로 보게 되며, 예제를 실행하는 동안 내려받는 것도 없다.

표를 행 단위로 읽는다. 두 행이 서로 다른 방향을 가리키면 독자가 결정한다. 먼저 측정한 집합의 모든 독자가 여는 형식을 고르고, 그다음 모든 독자가 지원하는 기능을 고른다.

이 안내를 진행 중인 사례에 적용해 보자. 대시보드와 파이프라인은 모두 pyiceberg 또는 DuckDB로 pageviews 테이블을 열므로 Iceberg 형식 버전 2가 적합하다. 보관 작업은 Delta Lake 사본을 읽으므로 Delta 행은 그 사본에만 적용되며, 사본은 삭제를 copy-on-write로 처리한다.

여러 도구가 읽는 테이블에는 기본값으로 Iceberg 형식 버전 2를 권장한다. pyiceberg가 이를 쓰고, DuckDB가 그 출력을 읽으며, 예제가 둘 다 측정하기 때문이다. 이 버전 조합에서의 비용은 다음과 같다. 삭제할 때마다 해당 데이터 파일을 다시 쓰며, 테이블에 카탈로그가 필요하고, pyiceberg에는 압축(compaction)이나 고아 파일 정리를 호출하는 기능이 없다. DuckDB가 유일한 엔진이라면 DuckLake를 권장한다. 읽는 쪽과 쓰는 쪽이 하나의 SQL 인터페이스를 공유하기 때문이다. 비용은 다음과 같다. 독자가 DuckDB로 한정되고, 카탈로그 버전이 DuckDB 릴리스에 묶이며, 인라이닝을 끄지 않으면 작은 삭제가 인라인으로 처리된다. 이 장의 검사에서 어떤 독자가 필요한 작업을 하지 못한다고 나오면 다르게 선택한다.

작업 규칙: 측정한 집합의 모든 독자가 여는 형식을 고른 다음, 그 집합이 지원하는 기능만 선택한다. 어떤 형식도 모든 요구를 충족하지 못하면 테이블을 나누거나 독자를 바꾼다. 측정이 다루지 않는 기능을 독자에게 약속하지 않는다.

운영 환경에서 무엇이 잘못되는가

마지막으로 변경된 판: 2026.11.7판

공유 레이크하우스에서 일어나는 형식 관련 장애는 대부분 형식 자체의 버그가 아니라, 기록하는 쪽이 테스트하지 않은 도구에서 비롯된다. 여기에 나오는 장애는 모두 앞선 절에서 측정했거나 인용한 것이므로, 자신의 테이블에서도 확인할 수 있다.

공급업체의 주장만 보고 선택하기. 지원 안내 페이지는 하나의 엔진을 설명하며, 그 버전은 사용자의 버전과 다른 경우가 많다. 이 페이지는 무엇을 테스트할지 찾는 데 쓰고, 답으로 삼지 않는다. 그 주장을 자신의 고정된 버전에서 확인한다.

엔진 하나만 테스트하기. 한 라이브러리가 기록한 테이블을, 같은 기능을 지원하지 않는 다른 라이브러리가 읽지 못할 수 있다. 쓰기는 한 도구에서 성공하고, 실패는 두 번째 도구가 테이블을 열 때 나타난다. 첫 쓰기 전에 집합에 속한 모든 도구에 대해 읽기 검사를 실행한다.

리더가 구현하지 않은 기능. 삭제 벡터 설정은 테이블에 리더 기능을 추가하며, 프로토콜은 리더가 이를 구현하도록 요구한다. 집합 밖의 리더는 테이블을 열 수는 있어도 그 기능에서 실패할 수 있다. 이후의 쿼리 오류로 알아내지 말고, 기능 검사 예제가 출력하는 프로토콜 기록에서 확인한다.

아무 일도 하지 않는 이름 변경. 이 고정된 버전에서 deltalake의 set_column_metadata 호출은 오류 없이 반환하고 버전도 올리지만, 열 이름은 그대로 남는다. 3장에서 이 함정을 보여 준다. 확인 방법은 변경 후에 열 이름을 읽어 보는 것이다.

잘못된 순서로 업그레이드하기. 라이터가 리더보다 앞서 업그레이드되면 리더가 열 수 없는 테이블이 만들어질 수 있고, 첫 징후는 다른 팀 작업에서 발생하는 읽기 실패다. 점검 목록의 순서를 따르면 각 단계에서 모든 리더가 테이블을 열 수 있는 상태가 유지된다.

쓰기 결과로 테이블을 판단하기. 쓰기가 성공했다는 것은 라이터가 파일을 만들 수 있다는 것만 보여 준다. 다른 도구가 그 파일을 읽을 수 있다는 것은 보여 주지 않는다. 이 장의 삭제 벡터 검사가 기록하고, 삭제하고, 리더의 기능 수를 세는 것도 바로 이 때문이다.

DuckLake 삭제를 행 수로 확인하기. DuckLake의 기본 인라이닝에서는 몇 개 행을 지우는 작은 삭제가 삭제 파일을 쓰지 않고, 인라이닝을 끄면 같은 삭제가 삭제 파일을 쓴다. 행 수를 세는 검사는 어느 쪽이든 삭제가 성공했다고 말한다. DuckLake 삭제 예제처럼 삭제 파일의 수도 함께 센다.

DuckDB와 함께 움직이는 카탈로그 버전. 이 고정된 버전에서 DuckLake 카탈로그는 버전 1.1을 보고하고, 이를 여는 확장은 빌드 417a9117f5를 보고한다. DuckLake 문서는 버전 1.1이 요구하는 DuckDB 릴리스를 밝히고 있다(DuckLake 문서). 더 오래된 DuckDB는 그 카탈로그를 열지 못할 수 있으므로, 업그레이드가 바뀌지 않은 리더를 깨뜨릴 수 있다.

작업 규칙: 기록하거나 업그레이드하거나 공급업체의 주장에 의존하기 전에, 모든 리더를 각자의 고정된 버전에서 측정한다. 라이터나 카탈로그를 업그레이드할 때는 모든 리더가 그 결과를 열어 볼 때까지 이전 릴리스를 그대로 둔다.

이 장이 내린 결정

  • 이 버전 고정에서는 pyiceberg와 함께 Iceberg 형식 버전 2를 권장한다. 어떤 독자에게도 형식 버전 3을 약속하지 않으며, 그것이 바뀌는 시점도 정하지 않는다. 고정된 버전이 결정하고, 측정이 그것을 보여 준다.
  • 호환성 표는 이 버전 고정에서 측정한 대로 기술하며, 각 칸은 예제 또는 인용한 출처를 가리킨다.
  • 테스트한 범위 밖의 독자가 열게 될 테이블에는 삭제 벡터를 쓰지 않는다.
  • 이 버전 고정에서는 deltalake 테이블의 이름 변경을 약속하지 않는다.
  • DuckLake는 행뿐 아니라 삭제 파일도 센다.
  • 측정하지 않은 기능은 지원하지 않는 것으로 취급한다. 이 장의 실패 사례가 모두 누군가 지원된다고 가정한 기능에서 나왔기 때문이다.
  • DuckLake 카탈로그 버전은 확장 버전과 구분하여 기술한다. 카탈로그 버전은 어떤 리더가 그 카탈로그를 열 수 있는지를 결정하고, 확장 버전은 DuckDB를 따른다.
  • 공급업체의 지원 페이지 대신 측정한 호환성 표를 택했다. 무엇이 열리는지는 고정된 버전이 결정하기 때문이다.
  • Iceberg 형식 버전 2를 기본값으로 삼은 것은 판단이며, 판단이라고 밝혀 둔다. 그 근거가 되는 측정은 예제이고, 다시 실행해야 할 부분도 예제이다.
  • 이 책은 DuckDB delta 확장이나 iceberg 확장을 실행하지 않는다. 예제는 실행 시점에 아무것도 설치하지 않으며 각 형식의 고유 라이브러리를 사용한다. DuckDB delta 확장은 문서에 설명된 대로 Delta Lake 테이블을 쓸 수 있다.

이 판의 이 장

2026.11.10판예제 통과 2026년 11월 20이 장에서 5개 예제개 중 5개가 통과한다

영어판 2026.11.10판을 번역한 것이다.

이 절 인용

형식

각 형식은 이 번역이 따르는 영문 원서를 출처로 표기한다.

모든 형식은 이 판을 명시한다. 링크는 현재 판을 열며, 여기서 절의 제목은 본문이 마지막으로 바뀐 시점을 알려 준다. 접근 날짜와 검색 날짜는 이 자료를 여는 날짜다.

이 페이지의 내용

10장 중 10장: 도구가 지원하는 범위에서 포맷을 선택하라

  1. 선택하기 전에 지원 여부를 측정한다
  2. 고정된 도구가 한 일 읽기
  3. 버전 쓰기와 읽기
  4. 변경과 정리
  5. 카탈로그와 DuckDB
  6. pyiceberg는 버전 3 테이블을 쓰지 않는다
  7. 삭제 벡터에는 프로토콜 업그레이드가 필요하다
  8. 새 테이블을 위한 점검 목록
  9. 독자를 기준으로 형식 고르기
  10. 운영 환경에서 무엇이 잘못되는가
  11. 이 장이 내린 결정

맨 위로 돌아가기전체 장