첫 번째 테이블을 처음부터 끝까지 만들기
읽는 데 약 28분분 걸린다, 10절에 3개 예제이(가) 있음.
AI로 번역함. 영어 원문을 사람이 검증함. 우리가 책을 만드는 방식
영어판 2026.11.10판을 번역한 것이다. 원문 읽기
이 장을 마치면 행 묶음을 테이블에 커밋하고, DuckDB에서 그 테이블을 다시 읽고, 합계를 확인할 수 있다. 이 책은 SQL과 Python을 쓰며, 레이크하우스 테이블을 어떻게 저장하고, 변경하고, 정리하고, 공유하고, 다른 형식으로 옮길지 결정해야 하는 데이터 엔지니어와 분석 엔지니어를 위한 책이다. 이 책은 하나의 결과물을 만든다. 그것은 pageviews 테이블이며, 이 테이블을 저장하고, 변경하고, 이전 스냅샷 기준으로 읽고, 정리하고, 카탈로그에 등록하고, 형식 사이에서 옮긴다.
폴더에 들어 있는 여섯 시간 분량의 Wikimedia 페이지뷰는 아직 테이블이 아니다. 폴더는 어떤 파일이 테이블에 속하는지 알려 주지 않으며, 중간에 멈춘 적재는 다른 파일과 똑같아 보이는 파일을 남긴다. 이 책이 만드는 테이블은 시간 단위다. 각 행은 공개된 Wikipedia 문서 하나가 한 시간 동안 한 언어판에서 몇 번 조회되었는지를 나타낸다. 이 테이블을 pageviews 테이블이라고 부른다.
이 장은 그 테이블의 거친 버전을 만든다. 테이블을 세 가지 형식(Apache Iceberg, Delta Lake, DuckLake)으로 쓰고, 각각을 DuckDB로 다시 읽어 합계를 비교한다. 이후의 각 장은 한 단계씩 단단하게 다진다. 다음은 그 목록이다.
- 2장은 이전 스냅샷 시점의 테이블을 읽는다.
- 3장은 파일을 다시 쓰지 않고 열을 추가하고 이름을 바꾼다.
- 4장은 오래된 파일을 다시 쓰지 않고 파티셔닝을 바꾼다.
- 5장은 삭제, 갱신, 병합으로 행을 바로잡는다.
- 6장은 시간 단위 추가가 남기는 작은 파일을 압축한다.
- 7장은 스냅샷을 만료시키고 어떤 스냅샷도 참조하지 않는 파일을 제거한다.
- 8장은 테이블을 카탈로그에 등록하고 DuckDB에서 질의한다.
- 9장은 테이블을 형식 사이에서 옮기고 사본을 검사한다.
- 10장은 사용하는 도구가 지원하는 범위를 바탕으로 형식을 고른다.
독자는 SQL, Python, Parquet을 알고 있고 파티션이 무엇인지도 안다고 가정한다. 이 장은 그것들을 설명하지 않는다.
pageviews 테이블의 행은 2024년 6월 3일 여섯 시간, 즉 UTC 기준 00:00부터 05:59까지를 다룬다. 이 행들은 Wikimedia 페이지뷰 덤프에서 가져온 것이며, Wikimedia 프로젝트가 CC0로 공개한다. 이 책은 특수 문서를 제거한 뒤 영어판, 독일어판, 프랑스어판, 일본어판에서 시간마다 조회수가 가장 많은 500개 제목을 남긴다. 그 날짜는 고정되어 있고 과거이므로 해당 덤프는 바뀌지 않으며, 저장소의 데이터도 낡지 않는다. 데이터 폴더의 README에 출처, 라이선스, 정확한 추출 범위가 나와 있다.
데이터는 일부러 지저분하게 두었다. 제목에는 밑줄과 라틴 문자가 아닌 문자가 들어 있고, 조회수는 한쪽으로 치우쳐 있다. 00시의 최상위 제목은 500위 제목보다 조회수가 훨씬 많다. 추출된 모든 행의 response_bytes 값은 0이며, 이는 데이터 폴더의 README에 기록되어 있다. 이 책은 그 열을 추출본이 주는 그대로 유지하므로 전체에서 0이다. 이런 값은 데이터에 그대로 남겨 둔다. 테이블 형식은 값을 있는 그대로 저장해야 하기 때문이다.
테이블 형식이 파일에 더하는 것
폴더를 읽는 쪽에는 그 안의 모든 파일이 보인다. 테이블 형식은 이 문제를 메타데이터로 해결한다. 테이블의 메타데이터는 테이블의 스키마와, 이력의 각 시점에 테이블을 구성하는 데이터 파일을 기록한 것이다. 테이블에 가하는 변경은 커밋이며, 커밋은 새 메타데이터를 한 단계로 기록한다. 이 한 단계가 테이블을 한 상태에서 다음 상태로 옮기는 유일한 변경이다.
테이블 형식마다 메타데이터와 이 개념들을 가리키는 용어가 다르다. Iceberg는 커밋 이후의 상태를 스냅숏이라고 부른다. Delta Lake는 버전에 번호를 매긴다. DuckLake는 스냅숏을 카탈로그 파일에 기록한다. 이 장에서는 세 형식 모두에 같은 행을 기록하므로, 각 형식에서 같은 행을 확인할 수 있다.
메타데이터가 놓이는 위치도 다르다. Iceberg 테이블은 현재 스냅숏을 가리키는 메타데이터 파일을 유지한다. pyiceberg가 기록하는 형식 버전 2에서는 각 스냅숏이 매니페스트 리스트를 가리키고, 매니페스트 리스트는 매니페스트들을 가리키며, 각 매니페스트는 데이터 파일과 그 통계를 가리킨다. Iceberg 명세가 이 계층을 하나씩 정의한다. Delta Lake 테이블은 Delta Lake 프로토콜에 설명된 대로 데이터 옆의 _delta_log 폴더에 커밋 파일의 순서 있는 로그를 유지한다. DuckLake 테이블은 연결(attach)하는 카탈로그 파일에 메타데이터를 유지하고, 그 파일 옆의 폴더에 데이터 파일을 기록한다.
여섯 시간 분량을 한 시간씩 세 형식에 모두 넣은 다음, 각 테이블을 다시 읽어 합계를 비교한다.
1"""Load six hours into Iceberg, Delta Lake and DuckLake, then read each table back.23The rows and views lines print each format's totals, and the assert after them checks that the three agree.4The titles at the end come from the Iceberg table alone.5"""67from lib.lakehouse import (8 format_report,9 load_three_formats,10 new_warehouse,11 print_rows,12 safe_error,13 sql_rows,14 scan_arrow,15)1617# page_title breaks ties in views, so titles with equal views always print in the same order.18TOP_THREE = """19 SELECT sum(views) AS views, page_title FROM pageviews20 GROUP BY page_title ORDER BY views DESC, page_title LIMIT 321"""222324def main():25 try:26 with new_warehouse() as wh:27 # range(6) is hours 0 to 5, the six hours of the cut, one commit per hour in each format.28 iceberg, delta_path, lake = load_three_formats(wh, range(6))29 report = format_report(wh, iceberg, delta_path, lake)3031 for name, (rows, views, files) in report.items():32 print(f"{name} rows: {rows}")33 print(f"{name} views: {views}")34 print(f"{name} data files: {files}")35 # A set of (rows, views) pairs has one entry only when all three formats agree.36 totals = {(rows, views) for rows, views, _ in report.values()}37 assert len(totals) == 1, "the three formats disagree on rows or views"3839 print("top three page titles over six hours (views, page_title):")40 # pageviews names the Arrow table for the SQL; keep_order prints the rows in the SQL's order, not re-sorted.41 print_rows(sql_rows(wh.con, TOP_THREE, keep_order=True, pageviews=scan_arrow(iceberg)), keep_order=True)42 except Exception as exc:43 print(safe_error(exc))44 raise SystemExit(1)454647if __name__ == "__main__":48 main()
python rough-lakehouse.pyiceberg rows: 2999
iceberg views: 1807299
iceberg data files: 6
delta rows: 2999
delta views: 1807299
delta data files: 6
ducklake rows: 2999
ducklake views: 1807299
ducklake data files: 6
top three page titles over six hours (views, page_title):
399885 Main_Page
102089 メインページ
54796 Wikipedia:Hauptseite
세 형식은 같은 행 수와 같은 조회수 합계를 보고하며, 모두 시간마다 데이터 파일을 하나씩 기록했다.
- Iceberg: 행 2999개, 조회수 1807299, 데이터 파일 6개.
- Delta Lake: 행 2999개, 조회수 1807299, 데이터 파일 6개.
- DuckLake: 행 2999개, 조회수 1807299, 데이터 파일 6개.
세 형식의 행 수나 조회수 합계가 하나라도 다르면 assert가 실행을 멈춘다. 이어서 출력은 여섯 시간 동안 조회수가 가장 많은 제목 세 개를 Iceberg 테이블만으로 읽어 나열한다. Main_Page, メインページ, Wikipedia:Hauptseite이며, 각각 영어판, 일본어판, 독일어판의 대문이다.
스냅숏 ID, 버전 번호, 파일 이름은 실행할 때마다 달라지므로 출력에 싣지 않는다. 스냅숏에 이름을 붙이는 방법은 시간마다 추가하기에서 다룬다.
DuckLake는 직접 쓰는 컴퓨터에서 한 단계가 더 필요하다. DuckDB에서 INSTALL ducklake을 실행한 다음 LOAD ducklake를 실행한다. 이 책의 실행은 대신 저장소에 있는 파일에서 DuckDB가 공식 서명한 ducklake 확장의 사본을 불러오므로, 네트워크 연결 없이 실행된다. DuckLake에는 파일 수에 영향을 주는 인라이닝 기본값도 있다. 기본적으로 10행 이하의 삽입은 Parquet 파일이 아니라 카탈로그에 보관한다. DuckLake 데이터 인라이닝 문서는 이 기본값을 "Data inlining is enabled by default with a row limit of 10."이라고 밝힌다. 이 예제는 한도를 0으로 설정하므로 모든 삽입이 파일을 기록하며, 따라서 파일 수는 모든 장에서 같은 의미를 갖는다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
One load loop, three commit styles
The helper load_three_formats() in examples/lib/lakehouse.py holds the loop that rough-lakehouse calls. The loop writes each hour to all three tables, and each line that writes is one commit in one format:
for hour in hours:
rows = read_cut_hour(hour)
iceberg.append(rows)
write_deltalake(delta_path, rows, mode="append")
lake.register("hour", rows)
lake.execute(f"INSERT INTO {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SELECT * FROM hour")
lake.unregister("hour")
read_cut_hour returns one hour of the cut as an Arrow table, with the same five columns in every format. The Iceberg append creates a snapshot. The Delta append creates a new version, and it creates the table on the first call, when the path does not yet hold one. The DuckLake insert writes a Parquet file and records a snapshot in the catalog file. The three calls differ, and the table each one writes is the same six hours of rows. The loop itself checks nothing. It runs the six loads in order and stops if one of them raises an error. The checks come after all six hours are in, when rough-lakehouse reads back each format's totals and compares them.
커밋은 테이블의 파일을 지정한다
Apache Iceberg table spec은 스냅샷(snapshot)을 어느 시점의 테이블 상태로 정의하며, 리더는 이 스냅샷으로 테이블의 모든 데이터 파일을 찾는다. 따라서 스냅샷은 두 가지 일을 한다. 그 시점에 테이블이 가진 데이터 파일을 지정하고, 그 스냅샷을 만든 연산(operation)을 기록한다. 스펙은 연산의 종류를 나열한다. 추가(append)의 경우 연산은 append이며, Iceberg 스펙은 이를 "Only data files were added and no files were removed."라고 설명한다.
pageviews 테이블을 예로 들면 이해하기 쉽다. 적재하는 시간대마다 데이터 파일이 하나씩 생기고, 적재 한 번이 커밋 한 번이다. 첫 번째 커밋 후 테이블에는 00시의 파일만 있다. 두 번째 커밋 후에는 파일이 두 개가 되고, 이후에도 같은 식으로 늘어난다. 데이터 파일은 수정되지 않는다. 커밋은 파일을 추가하고, 새 스냅샷은 커밋 후 테이블이 가진 파일을 지정한다.
테이블의 데이터 파일 수는 폴더가 아니라 스냅샷에서 나온다. rough-lakehouse는 각 포맷이 해당 테이블에 대해 보고하는 데이터 파일 수를 출력한다. 이 숫자는 테이블 자신이 가졌다고 말하는 파일의 수이며, 폴더 목록은 이와 다른 숫자를 보여 줄 수 있다.
작업 규칙: 테이블이 무엇을 가졌는지는 폴더를 나열해서 확인하지 말고 현재 스냅샷을 통해 테이블에 직접 물어야 한다. 폴더에는 작성기(writer)가 그곳에 둔 모든 파일이 들어 있고, 그중 테이블이 읽는 파일이 무엇인지는 스냅샷이 알려 준다.
각 포맷을 Python 라이브러리로 가르치는 이유
rough-lakehouse 예제는 포맷마다 서로 다른 라이브러리로 데이터를 썼는데, 이 절은 그 이유를 설명한다. 이 책은 Apache Iceberg와 Delta Lake를 독자가 실제로 실행할 때 쓰게 될 Python 라이브러리로 기록한다. 그 라이브러리는 버전 0.12.0의 pyiceberg와 버전 1.6.6의 deltalake이다. 버전 2.0.0의 DuckDB는 이 라이브러리들이 기록한 데이터를 읽는다. Iceberg 테이블은 스캔에서 얻은 Arrow 테이블로 읽고, Delta 테이블은 deltalake가 실행하는 쿼리에서 얻은 Arrow 테이블로 읽는다. DuckLake는 예외이다. DuckDB가 ducklake 확장을 통해 DuckLake를 직접 실행하며, 테이블의 카탈로그 파일을 연결한다. 이 책은 DuckDB의 iceberg 확장과 delta 확장을 사용하지 않으며, 이를 실행하는 예제도 없다.
| 포맷 | 기록하는 도구 | DuckDB가 읽는 방식 |
|---|---|---|
| Apache Iceberg | pyiceberg, 0.12.0 | 스캔에서 얻은 Arrow 테이블 |
| Delta Lake | deltalake, 1.6.6 | deltalake의 QueryBuilder에서 얻은 Arrow 테이블 |
| DuckLake | DuckDB의 ducklake 확장, DuckDB 2.0.0 기반 |
카탈로그 파일에 대한 ATTACH |
이 선택에는 대가가 따른다. Spark나 Trino로 Iceberg를 실행하는 독자는 그곳에서 이 책이 다루지 않는 기능을 포함해 포맷의 더 많은 부분을 만나게 된다. 이 책은 그런 지점을 언급하되 해당 엔진을 가르치지는 않는다. 얻는 것은 움직이는 부품의 감소이다. 각 포맷은 자체 라이브러리가 기록하고, DuckDB는 그 출력을 읽는다. 각 라이브러리의 버전은 고정되어 있으며, 각 장은 포맷 명세의 버전이 아니라 고정된 라이브러리 버전을 명시한다. 고정된 버전은 examples/requirements.txt에 있으며, 이 파일은 모든 패키지를 한 줄에 정확히 하나의 버전으로 나열한다. 이 파일로 설치한 독자는 이 장이 실행된 것과 같은 라이브러리를 얻는다. examples/.python-version가 지정하는 Python 버전을 사용한다. pip는 Python 버전을 선택해 주지 않기 때문이다.
작업 규칙: 각 테이블은 버전을 고정한 라이브러리로 쓰고 읽으며, 읽기에 사용하는 버전을 밝힌다. 라이브러리가 해 주지 못하는 일이 무엇인지 측정으로 확인한 뒤에만 엔진 자체의 확장을 사용한다.
세 시간 분량을 테이블에 적재하기
rough-lakehouse 예제는 전체 순환 과정을 보여 주었으므로, 이 절에서는 속도를 늦추어 테이블 하나만 다룬다. 배치를 적재하는 일은 두 단계로 이루어진다. 먼저 테이블을 만들고, 그다음 각 배치를 그 테이블에 커밋한다. pageviews 테이블에는 먼저 00시, 01시, 02시 데이터를 적재하므로 한 시간 분량이 커밋 하나가 된다. 이 예제는 처음 세 시간 분량 뒤에 03시부터 05시까지의 데이터도 같은 방식으로 적재한다. 이 절의 나머지 부분은 Iceberg 테이블만 대상으로 한다. 이 테이블이 보여 줄 내용이 가장 많기 때문이다.
이 부분은 아직 번역되지 않았으므로 영어로 표시된다.
Create the table in a catalog
An Iceberg table needs a catalog, which is the registry that maps a table name to the table's current metadata. A Delta Lake table is found by its path, with no catalog, and a DuckLake table lives in its catalog file. The book uses pyiceberg's SQL catalog on SQLite for the Iceberg table. The catalog is one file, and the table's data files go in a warehouse folder beside it. The catalog holds pointers and metadata, not rows. Inside the catalog file, a table name such as wiki.pageviews_hourly maps to the location of the table's current metadata file. A commit writes a new metadata file and moves that mapping, so anyone who asks the catalog for the table gets the metadata that the most recent commit wrote. The helper new_warehouse() in examples/lib/lakehouse.py makes a temporary catalog and warehouse for each run, and removes them when the run ends. Because SQLite is a file and needs no server, the whole catalog runs on a laptop with the network off.
The table has five columns, and its schema says what each one holds:
Schema(
NestedField(1, "hour_utc", TimestampType(), required=False),
NestedField(2, "domain_code", StringType(), required=False),
NestedField(3, "page_title", StringType(), required=False),
NestedField(4, "views", LongType(), required=False),
NestedField(5, "response_bytes", LongType(), required=False),
)
The hour_utc column holds a timestamp without a time zone, in UTC, and the two counts are 64-bit integers. The helper create_iceberg_table() creates the table in the catalog, unpartitioned. Chapter 4 adds a partition spec to it.
Working rule: Write the schema out in code, with the type each column really has, before the first commit. The types are then decided on purpose, and not by whichever batch happens to arrive first.
시간별 데이터를 커밋 하나로 추가하기
추가(append)는 커밋 하나다. 아래에서 pyiceberg는 테이블을 만들고, 00시, 01시, 02시 데이터를 순서대로 추가한 뒤, 스냅숏을 커밋 순서대로 나열하여 각 커밋의 연산(operation)과 그 커밋이 추가한 행 수를 보여 준다.
1"""Create the Iceberg table, append hours 00 to 02 as three commits, then repeat hour 00.23The hour 00 point rests on the `snapshot 1 rows added` and `snapshot 2 rows added` lines, and the repeated-load point on the two `repeat of hour 00` lines.4"""56from lib.lakehouse import (7 create_iceberg_table,8 iceberg_file_count,9 new_warehouse,10 read_cut_hour,11 safe_error,12 scan_arrow,13 snapshot_labels,14)151617def main():18 try:19 with new_warehouse() as wh:20 table = create_iceberg_table(wh)21 for hour in range(3):22 table.append(read_cut_hour(hour))2324 # pyiceberg returns the snapshots in commit order, which the labels below depend on.25 snapshots = table.snapshots()26 # Snapshot IDs change from run to run, so each one prints as its position in commit order.27 labels = snapshot_labels([snap.snapshot_id for snap in snapshots])28 for snap in snapshots:29 label = labels[snap.snapshot_id]30 print(f"{label} operation: {snap.summary.operation.value}")31 # The commit's own summary holds the rows it added, not a count of the whole table.32 print(f"{label} rows added: {snap.summary['added-records']}")3334 print(f"rows in table: {scan_arrow(table).num_rows}")35 # Counted from the current snapshot, not from the folder.36 print(f"data files: {iceberg_file_count(table)}")3738 # Hour 00 again.39 table.append(read_cut_hour(0))40 repeat = table.current_snapshot()41 print(f"repeat of hour 00 operation: {repeat.summary.operation.value}")42 print(f"repeat of hour 00 rows added: {repeat.summary['added-records']}")43 print(f"rows in table after the repeat: {scan_arrow(table).num_rows}")44 except Exception as exc:45 print(safe_error(exc))46 raise SystemExit(1)474849if __name__ == "__main__":50 main()
python append-hours.pysnapshot 1 operation: append
snapshot 1 rows added: 499
snapshot 2 operation: append
snapshot 2 rows added: 500
snapshot 3 operation: append
snapshot 3 rows added: 500
rows in table: 1499
data files: 3
repeat of hour 00 operation: append
repeat of hour 00 rows added: 499
rows in table after the repeat: 1998
00시 데이터는 한 행이 모자란다. 첫 번째 커밋은 499행을 추가하고, 이어지는 두 커밋은 각각 500행을 추가한다. 데이터 README에서 설명하듯이, 개인정보 점검에서 00시 데이터의 한 행이 제거되었다. 세 번의 커밋이 끝나면 테이블에는 1499행이 3개의 데이터 파일에 담기며, 커밋마다 파일이 하나씩 생긴다.
각 커밋은 요약(summary)도 함께 기록하며, pyiceberg는 스냅숏을 커밋 순서대로 반환한다. 연산과 추가된 행 수는 여기에서 얻는다. 각 커밋의 연산은 append이며, 이는 명세가 정의하는 추가 연산이다. 스냅숏 요약은 테이블이 자신의 커밋에 대해 기록해 두는 내용이므로, 개수가 맞지 않을 때 가장 먼저 확인할 곳이다.
출력된 레이블 snapshot 1, snapshot 2, snapshot 3은 스냅숏 ID를 대신한다. Iceberg 스냅숏 ID는 명세가 고유해야 한다고 요구하는 긴 정수이며, 커밋이 이루어질 때 pyiceberg가 정하므로 실행할 때마다 달라진다. 각 ID를 커밋 순서상의 위치로 대응시키면 출력이 매번 같게 유지된다.
작업 규칙: 이름을 붙일 수 있는 배치마다 커밋을 하나씩 만들고, 다음 커밋을 만들기 전에 각 커밋이 추가한 행 수를 해당 원천에서 기대하는 개수와 비교한다. 개수가 틀린 경우, 그 커밋이 가장 최근일 때가 원인을 추적하기 쉽고, 그 위에 커밋이 더 쌓이면 어려워진다.
DuckDB로 테이블 질의하기
테이블이 준비되었으니 이제 질문을 던질 차례다. DuckDB는 SQL을 실행하지만, Iceberg 테이블은 DuckDB 테이블이 아니다. 이 책은 테이블의 현재 스냅숏을 Arrow 테이블로 읽는다. 이 Arrow 테이블은 pyiceberg가 스캔 결과로 돌려주는 것이며, 이를 DuckDB에 pageviews이라는 이름으로 등록한다. 그러면 DuckDB는 Iceberg 확장 없이 그 위에서 평범한 SQL을 실행한다. 스캔은 테이블이 스스로 스냅숏을 읽는 동작이다. 스냅숏이 가리키는 데이터 파일의 목록을 만들고, 그 파일들을 읽어서, 파일에 들어 있는 행만 넘겨준다. DuckDB는 바로 그 행들만 보며, 스냅숏이 가리키지 않는 행은 전혀 보지 못한다.
다음 예제는 새 테이블에 00시부터 02시까지의 데이터를 추가한 뒤 두 가지를 묻는다. 00시에 조회수가 가장 많았던 제목 다섯 개와, 세 시간 동안의 조회수 총합이다. 그리고 이 총계가 스캔 자체의 합계와 같은지 확인한다.
1"""Read the current Iceberg snapshot into DuckDB and check the totals.23The point that DuckDB received every row rests on the two total views lines, which the assert compares.4"""56from lib.lakehouse import (7 create_iceberg_table,8 new_warehouse,9 print_rows,10 read_cut_hour,11 safe_error,12 scan_arrow,13 sql_rows,14)151617def main():18 try:19 with new_warehouse() as wh:20 table = create_iceberg_table(wh)21 for hour in range(3):22 table.append(read_cut_hour(hour))23 # The current snapshot's rows as one Arrow table, sorted by every column.24 arrow = scan_arrow(table)2526 top = sql_rows(27 wh.con,28 # hour_utc is UTC, so this is hour 00 of 3 June 2024; page_title breaks ties in views.29 """30 SELECT views, page_title FROM pageviews31 WHERE hour_utc = TIMESTAMP '2024-06-03 00:00:00'32 ORDER BY views DESC, page_title LIMIT 533 """,34 # keep_order returns the rows in the order the SQL sorted them, not sorted again.35 keep_order=True,36 pageviews=arrow,37 )38 print("top five pages for hour 00 (views, page_title):")39 print_rows(top, keep_order=True)4041 # One row with one column: the sum.42 duckdb_total = sql_rows(wh.con, "SELECT sum(views) FROM pageviews", pageviews=arrow)[0][0]43 # A second route to the same total, summed in Python from the scan's own rows.44 pyiceberg_total = sum(arrow["views"].to_pylist())45 print(f"total views in DuckDB: {duckdb_total}")46 print(f"total views in the scan: {pyiceberg_total}")47 assert duckdb_total == pyiceberg_total, "DuckDB and the scan disagree on the total"48 except Exception as exc:49 print(safe_error(exc))50 raise SystemExit(1)515253if __name__ == "__main__":54 main()
python scan-into-duckdb.pytop five pages for hour 00 (views, page_title):
61107 Main_Page
13791 メインページ
9492 Wikipedia:Hauptseite
7511 Wikipédia:Accueil_principal
3781 笹生優花
total views in DuckDB: 899451
total views in the scan: 899451
목록에는 00시에 조회수가 가장 많은 제목 다섯 개가 조회수가 큰 것부터 나열되며, 조회수가 같으면 제목 순으로 정렬한다. 각 줄에는 조회수, 탭, 제목이 차례로 나온다. DuckDB에서 구한 총계는 899451건이며, 스캔 자체의 합계 899451와 같다. 두 값이 달라지면 assert가 실행을 중단시킨다.
총계가 스캔의 합계와 일치한다는 것은 스캔이 돌려준 모든 행을 DuckDB가 받았다는 뜻이다. 행 자체의 내용을 검증하는 것은 아니며, 상위 다섯 개를 구하는 질의를 검증하는 것도 아니다. 총계를 확인하는 데는 한 줄이면 충분하므로, 질의를 바꿀 때마다 실행해 볼 만하다. 행을 원본과 대조하는 일은 뒤의 장들이 맡는다. 그 장들은 각 변경을 그 변경의 출처가 된 데이터와 비교한다.
작업 규칙: Iceberg 테이블은 스캔이 돌려준 Arrow 테이블로 DuckDB에 읽어 들이고, 총계를 스캔 자체의 합계와 비교하여 DuckDB가 모든 행을 받았는지 확인한다. 그런 다음 각 질의의 결과는 비교할 수 있는 원본과 대조하여 검증한다.
운영 환경에서 생기는 문제
첫 번째 장의 경로는 짧지만, 그 안에는 운영 환경에서 마주치게 될 네 가지 문제가 숨어 있다.
반복된 적재는 같은 행을 다시 추가한다. 명세가 이 연산을 정의한 대로, append는 주어진 데이터 파일을 추가할 뿐 어떤 파일도 제거하지 않는다. 00시 데이터의 두 번째 사본을 막아 주는 장치는 테이블 안에 없다. 00시 데이터의 두 번째 사본을 담은 커밋도 다른 커밋과 다르지 않게 보인다. append-hours가 이를 보여 준다. 반복된 커밋의 연산은 append이고, 첫 번째 사본과 같은 개수인 499개 행을 추가하며, 이후 테이블은 오류 없이 1998개 행을 담게 된다. 적재가 한 번만 실행되도록 의도되었다는 기록은 실행 전에 적어 둔 행 수뿐이다. 잘못 적재된 행을 바로잡는 방법은 5장에서 다룬다.
폴더에는 테이블보다 더 많은 것이 들어 있다. 웨어하우스 폴더에 있는 파일의 수는 테이블이 가진 파일의 수와 다른 질문에 답한다. 폴더에는 기록하는 쪽이 그곳에 둔 모든 파일이 있고, 테이블이 무엇을 담는지는 스냅샷이 정의한다. 폴더의 Parquet 파일을 세는 도구가 보고하는 숫자는 테이블이 약속한 적이 없는 숫자다. 테이블이 더 이상 가리키지 않는 파일은 6장과 7장에서 다룬다.
스냅샷 ID, 버전, 스냅샷 번호는 서로 다른 종류의 숫자다. Iceberg의 ID는 64비트 값이다. Delta Lake의 버전은 커밋 순서대로 0부터 센다. DuckLake도 스냅샷에 번호를 매기며, 행을 삽입할 때뿐 아니라 스키마나 테이블을 만들 때마다 스냅샷을 기록한다. 한 형식의 번호를 저장해 두었다가 다른 형식의 버전으로 읽는 스크립트는 엉뚱한 상태를 읽게 된다.
작은 DuckLake 삽입은 파일을 쓰지 않는다. 기본적으로 DuckLake는 10개 행 이하의 삽입을 카탈로그 안에 보관하므로, 작은 삽입 뒤에 파일 수가 0이라면 실패가 아니라 예상된 결과다. 이 책의 DuckLake 예제는 행 수 한도를 0으로 설정한다. 다만 10장의 ducklake-inlined-delete만은 기본값을 그대로 두어, 작은 삭제가 삭제 파일을 쓰지 않음을 보여 준다. 삽입 구문을 자신의 카탈로그에 그대로 옮기는 독자는 먼저 이 기본값을 알아 두어야 한다.
작업 규칙: 각 커밋이 추가해야 할 행 수를 그 커밋을 만드는 적재 옆에 적어 두고, 적재가 끝날 때마다 그 수를 커밋의 요약과 비교한다. 테이블은 반복된 적재를 검사하지 않는다. 미리 적어 둔 행 수가 그 검사 역할을 한다.
이 장에서 내린 결정
- 이 장의 예제는 세 개다.
rough-lakehouse은 전체 결과를 세 가지 형식으로 만들므로, 이후의 각 장은 독자가 이미 실행해 본 결과의 한 부분만 바꾼다. 나머지 두 예제인append-hours와scan-into-duckdb은 Iceberg 테이블을 커밋 하나씩 쌓아 가며 만들고 DuckDB에서 읽는다. - 먼저 00시부터 02시까지, 그다음 03시부터 05시까지 다룬다. Iceberg 예제는 세 시간 분량을 적재하고, rough 예제는 여섯 시간 분량을 적재한다. 여섯 시간을 모두 합산하는 예제는
rough-lakehouse뿐이다. - 파티션이 없는 테이블을 쓴다. 1장은 파티션 사양 없이 테이블을 만든다. 4장에서 파티셔닝을 바꾼다. 4장의 day 변환과 hour 변환에 pyiceberg-core 패키지가 필요하므로, 이 패키지를 pyiceberg와 나란히 버전을 고정해 둔다.
- 예제에서는 인라이닝을 끈다. DuckLake 예제는
DATA_INLINING_ROW_LIMIT를 0으로 설정한다. 그래서 삽입할 때마다 Parquet 파일이 하나씩 쓰이고, 책이 파일 수를 출력하는 어느 곳에서나 그 수가 같은 의미를 갖는다. 10장의ducklake-inlined-delete은 기본값을 유지한다. 작은 삭제가 삭제 파일을 쓰지 않는다는 점이 그 예제의 요점이기 때문이다. - Delta 테이블은 deltalake의
QueryBuilder로만 읽는다.examples/lib/lakehouse.py의 읽기 도우미가 이 경로를 사용하며, 이후 Delta 테이블을 읽는 각 장도 같은 도우미를 쓴다. - 대역 데이터가 아니라 실제 데이터를 쓴다. 이 장의 각 예제는 데이터 README가 설명하는, 공개 덤프 여섯 개에서 잘라 낸 데이터를 읽는다. 이 책은 이 장을 위해 생성한 데이터를 제공하지 않는다.
- Iceberg 카탈로그에는 SQLite를 쓴다. SQLite 파일은 서버가 필요 없으므로, Iceberg 예제는 네트워크를 끈 노트북에서도 실행된다. 이 실행에서는 DuckDB의 확장 자동 다운로드도 꺼 두므로, 네트워크가 필요한 실행은 내려받지 않고 실패한다.
- 레이블이 ID를 대신한다. 출력에 나오는
snapshot 1,snapshot 2등은 스냅샷 ID를 대신하는 표시이므로, 실행할 때마다 출력이 달라지지 않는다.
이 판의 이 장
2026.11.10판예제 통과 2026년 11월 20이 장에서 3개 예제개 중 3개가 통과한다
영어판 2026.11.10판을 번역한 것이다.