카탈로그에 테이블을 등록하고 DuckDB에서 조회하기

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

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

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

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

이 장에서는 Iceberg 테이블을 SQL 카탈로그에 등록하고, DuckLake 카탈로그를 연결(attach)하고, Delta Lake 테이블을 경로로 열고, Iceberg 테이블과 DuckLake 테이블을 조인하는 DuckDB 구문 하나를 실행한다. 또한 각 카탈로그가 무엇을 담고 있는지, 그리고 카탈로그와 데이터 파일의 내용이 서로 어긋날 때 테이블에 어떤 일이 일어나는지도 다룬다.

앞선 장들에서는 테이블마다 서로 다른 경로로 열었다. Iceberg는 카탈로그 객체로, DuckLake는 파일로, Delta Lake는 폴더로 열었다. 첫 번째 테이블에서는 wiki.pageviews_hourly를 Iceberg SQL 카탈로그에 local라는 이름으로 등록했다. 이 장에서는 그 이름이 어떤 역할을 하는지, 그리고 각 형식이 그 자리에 무엇을 쓰는지 설명한다. 또한 두 번째 테이블인 wiki.domains를 추가한다. 이 테이블은 도메인 코드와 각 코드가 사용하는 언어를 담은 4행짜리 목록이다. 이 테이블은 DuckLake 카탈로그에 있으며, 조인 절에서 Iceberg의 페이지뷰 테이블과 조인한다.

카탈로그가 담고 있는 것

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

wiki.pageviews_hourly이 어디에 있는지 물으면, 답은 형식에 따라 달라진다. 내부적으로 모든 형식은 테이블을 데이터 파일과 메타데이터 파일로 저장한다. 메타데이터는 테이블의 현재 상태를 기술한다. 여기에는 스키마, 파티션 사양, 그리고 직접 또는 매니페스트 파일을 거쳐 현재 스냅샷이나 버전에 속한 데이터 파일이 들어 있다. 커밋할 때마다 새 메타데이터가 쓰이고 테이블은 그 메타데이터로 옮겨 간다. 카탈로그는 테이블의 이름을 현재 메타데이터가 있는 위치에 대응시키는 등록부다. 카탈로그에 wiki.pageviews_hourly을 요청한 리더는 메타데이터를 가리키는 포인터를 받고, 이어서 메타데이터가 나열한 데이터 파일을 읽는다.

카탈로그가 담는 것은 포인터이지 행이 아니다. Parquet 파일은 웨어하우스 폴더에 그대로 있고, 카탈로그는 어디서부터 읽을지를 알려 준다. 이름에는 두 번째 수준도 있다. wiki는 네임스페이스이며, 이 책의 모든 Iceberg 테이블 이름은 네임스페이스와 테이블 이름을 점으로 이은 것이다.

카탈로그를 고르는 일은 두 질문으로 정리된다. 누가 테이블에 쓰는가, 그리고 무엇이 테이블을 읽는가. 하나의 작업이 쓰고 하나의 엔진이 읽는 테이블은 파일 기반 카탈로그에 두고 경로로 찾을 수 있다. 여러 엔진이 읽는 테이블에는 각 엔진이 해석할 수 있는 이름이 필요하며, SQL 카탈로그나 서비스가 이를 제공한다. 테이블마다 카탈로그를 하나씩 두고, 테이블 옆에 그 카탈로그와 소유자를 적은 기록을 두기를 권한다. 조인 절이 보여 주듯이 카탈로그 간 조인은 한 세션 안에서 동작한다. 그렇다고 두 카탈로그가 하나가 되는 것은 아니다.

이 책의 세 형식은 서로 다른 세 카탈로그를 사용한다.

형식 테이블에 이름을 주는 것 현재 메타데이터가 있는 곳
Iceberg SQL 카탈로그 객체, 여기서는 local라는 이름 카탈로그의 데이터베이스, 이 데이터베이스가 메타데이터 파일을 가리킨다
DuckLake 경로로 연결(attach)한 카탈로그 파일 카탈로그 파일 내부
Delta Lake 없음. 테이블의 폴더 경로가 이름을 대신한다 테이블의 폴더 안

Iceberg REST 카탈로그는 파일이 아니라 서비스라는 점에서 다른 종류의 카탈로그다. REST 카탈로그 문서는 어떤 Iceberg 카탈로그와도 상호작용할 수 있는, OpenAPI로 명세된 공통 API를 설명하며, 덕분에 클라이언트는 모든 카탈로그에 대해 하나의 구현만 있으면 된다. 같은 문서에 따르면 이 프로토콜은 변경 기반 커밋을 사용하므로 서비스가 충돌을 해결하고 자기 쪽에서 재시도할 수 있으며, 루트 메타데이터는 카탈로그 서비스가 쓴다. 이 장에서는 REST 카탈로그를 실행하지 않는다. REST 카탈로그는 저마다 실행 중인 서비스가 필요한데, 여기의 예제는 서비스 없이 오프라인으로 실행되기 때문이다. 이 프로토콜을 구현한 제품들을 비교하는 일은 이 책의 범위가 아니다.

카탈로그는 이름 이상의 것을 담을 수 있다. 분류와 보존 규칙도 테이블 메타데이터에 속한다. 이 주제는 Data Governance as Code가 다루며, 이 책에서는 가르치지 않는다.

작업 규칙: 테이블에 쓰기 전에 어느 카탈로그나 경로가 그 테이블에 이름을 주는지 확인하고, 데이터 폴더와 함께 그 카탈로그도 백업한다. Parquet 파일은 테이블의 이름을 알려 주지 않는다. 이름을 주는 것은 카탈로그이며, 장애 절이 이를 보여 준다.

SQL 카탈로그에 테이블 등록하기

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

pyiceberg의 SqlCatalog은 테이블을 데이터베이스에 보관한다. 이 카탈로그에는 데이터베이스를 가리키는 uri와, 데이터 파일과 메타데이터를 쓸 폴더를 가리키는 warehouse를 지정한다. 이 책은 데이터베이스로 SQLite 파일을, 웨어하우스로 로컬 폴더를 사용한다. pyiceberg 구성 페이지는 SQL 카탈로그에 그 뒤에서 받쳐 줄 데이터베이스가 필요하다고 설명하며, SQLite는 동시성을 염두에 두고 만들어지지 않았고 탐색용이나 개발용에 적합하다고 경고한다. 이 예제들은 개발용이므로 이 제약은 예제의 동작에 아무 영향을 주지 않는다. 운영 환경의 카탈로그에는 여러 기록자가 사용할 수 있는 데이터베이스가 필요하다.

다음 예제는 같은 카탈로그 파일을 같은 이름으로 한 번 더 열고, 그 두 번째 객체를 통해 테이블을 읽는다. 이어서 테이블의 메타데이터에 두 번째 이름을 등록하고, 이름이 다른 카탈로그 객체에서 무엇이 보이는지 보여 준다.

register-iceberg-table.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Register an Iceberg table in a SQL catalog, then reach it through a second catalog object, a stale object and asecond name. The point rests on the 'loaded object' and 'after a reload' lines, and the last line shows what anobject under another catalog name can see."""from lib.lakehouse import (ICEBERG_ID, NAMESPACE, create_iceberg_table, new_warehouse,                           open_catalog, read_cut_hour, safe_error, scan_arrow)with new_warehouse() as wh:    table = create_iceberg_table(wh)    for hour in range(3):                                # hours 0, 1 and 2 of the cut, one commit each        table.append(read_cut_hour(hour))    # A second object with the same catalog name sees the same tables.    same = open_catalog(wh)                              # the default name, local, as the first object had    loaded = same.load_table(ICEBERG_ID)    print("rows read through the second object:", scan_arrow(loaded).num_rows)    # A loaded table is a snapshot of the catalog as it was when loaded.    stale = same.load_table(ICEBERG_ID)    table.append(read_cut_hour(3))                       # the fourth hour, committed after stale was loaded    print("rows in the loaded object after another append:", scan_arrow(stale).num_rows)    print("rows after a reload:", scan_arrow(same.load_table(ICEBERG_ID)).num_rows)    # Register the same metadata file under a new name: a pointer, not a copy.    same.create_namespace("archive")    same.register_table("archive.pageviews_copy", table.metadata_location)    print("rows in archive copy:", scan_arrow(same.load_table("archive.pageviews_copy")).num_rows)    # An object with another name does not see the namespace: the SQL catalog keeps tables apart by catalog name.    try:        open_catalog(wh, name="other").list_tables(NAMESPACE)    except Exception as exc:        print("other name:", safe_error(exc, wh))
출력python register-iceberg-table.py
rows read through the second object: 1499
rows in the loaded object after another append: 1499
rows after a reload: 1999
rows in archive copy: 1999
other name: NoSuchNamespaceError: Namespace does not exist: wiki

두 번째 객체는 wiki.pageviews_hourly의 행을 1499개 읽는다. 1장에서 적재한 세 시간 분량이다. pyiceberg는 각 테이블을 SqlCatalog에 넘긴 카탈로그 이름 아래에 저장한다. 이름이 같은 객체는 같은 테이블을 찾는다.

카탈로그와 웨어하우스 폴더는 한 쌍이다. 카탈로그는 메타데이터 파일의 위치를 담고 있고, 그 위치는 warehouse 속성이 지정한 폴더 아래에 있다. 웨어하우스 폴더 없이 카탈로그 파일만 복사하거나 파일 없이 폴더만 복사하면, 존재하지 않는 파일을 가리키는 포인터만 남는다. 둘을 함께 백업하고 함께 옮겨야 한다.

각 프로세스는 자기만의 카탈로그 객체를 열며, 어떤 객체도 다른 객체와 상태를 공유하지 않는다. 여기서는 한 프로세스 안의 객체 두 개가 프로세스 두 개를 대신한다.

로드된 테이블은 로드된 시점의 상태를 유지한다. 네 번째 시간의 추가 이전에 로드한 객체는 여전히 1499개의 행을 읽지만, 다시 로드하면 1999개를 읽는다. 시작할 때 테이블을 로드하고 끝날 때 읽는 프로세스는 시작 시점의 상태를 읽는다. 그사이에 이루어진 커밋을 보려면 다시 로드해야 한다.

작업 규칙: 코드 전체에서 SQL 카탈로그 파일은 하나의 이름으로 열고, 테이블을 로드한 뒤 다른 기록자가 커밋했을 수 있다면 읽기 전에 테이블을 다시 로드한다. SQLite는 한 번에 한 기록자만 쓰는 경우에 사용하고, 여러 기록자를 운영하기 전에 동시 기록자를 위해 만들어진 데이터베이스로 바꾼다.

메타데이터 파일로 테이블 등록하기

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

register_table(identifier, metadata_location)는 이미 존재하는 메타데이터 파일에 이름을 하나 추가한다. pyiceberg API 페이지는 이 함수를 메타데이터로 테이블을 등록하는 방법으로 소개하며, overwrite=True를 전달하면 이미 존재하는 항목을 교체한다고 설명한다. 이 예제는 먼저 네임스페이스를 만든 다음, 그 안의 archive.pageviews_copy 아래에 테이블의 메타데이터를 등록한다. 아카이브 이름은 원래 테이블과 같은 행을 읽으며, 그 행은 1999개이다. 두 이름은 같은 메타데이터를 가리키며, 등록 과정에서는 데이터 파일을 쓰지 않는다.

등록된 이름은 두 번째 테이블이 아니라 같은 테이블로 가는 두 번째 경로이다. 두 이름이 같은 메타데이터를 읽으므로, 한 이름으로 수행한 커밋은 두 이름 모두의 커밋이 된다. 두 번째 이름은 백업이 아니라 읽기 경로로 취급한다.

작업 규칙: 테이블마다 쓰기용 이름은 하나만 유지한다. 메타데이터 파일을 두 번째 이름으로 등록하는 것은 나중에 제거할 읽기 작업에만 하고, overwrite=True는 그 항목을 교체하려는 의도가 있을 때만 전달한다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

Attach a DuckLake catalog

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

DuckLake's catalog is a database file, and DuckDB attaches it with an ATTACH statement that starts with ducklake: and gives the file's path. The data path, the folder where DuckLake writes Parquet files, is stored in the catalog. The DuckLake connecting page says the data storage location only has to be given when a new DuckLake is created, and that the location is loaded from the catalog database after that. The helper connect_ducklake loads DuckLake into the DuckDB session with downloads off, and attach_ducklake runs the ATTACH for a catalog file under a folder.

The next example creates wiki.domains in a fresh DuckLake catalog, detaches it, and attaches the file again with no data path. It then lists the tables in the wiki schema of the file.

attach-ducklake.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 file, detach it, and attach it again from the file alone. The point rests on the'rows after re-attach' line, and the table list shows what the catalog holds, not what the data folder holds."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, attach_ducklake, connect_ducklake,                           create_ducklake_domains, new_warehouse, print_rows, sql_rows)with new_warehouse() as wh:    con = connect_ducklake(wh.con)    create_ducklake_domains(con, wh.root)                # inlining is off, so the rows become Parquet files    print("rows written:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])    # Detach, then attach with no DATA_PATH: the catalog file stores the data path.    con.execute(f"DETACH {DUCKLAKE_ALIAS}")    attach_ducklake(con, DUCKLAKE_ALIAS, wh.root)    print("tables in the catalog:")    print_rows(sql_rows(con, f"""SELECT schema_name, table_name FROM duckdb_tables()                                 WHERE database_name = '{DUCKLAKE_ALIAS}' AND schema_name = '{NAMESPACE}'"""))    print("rows after re-attach:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])
출력python attach-ducklake.py
rows written: 4
tables in the catalog:
wiki	domains
rows after re-attach: 4

The 4 rows of wiki.domains are written, and 4 rows read back after the re-attach. The table list shows one table in the wiki schema, domains. The second attach needed no data path, because the file already held it. The listing comes from the catalog, not from the data folder. The catalog file holds the list of tables, and the data folder holds the bytes. Losing the first loses the names even when the second is intact, as the failure section shows.

The same connecting page says that DuckLake inlines small inserts into the catalog database, with a default limit of 10 rows. The helper this chapter uses sets the inlining limit to 0, so every insert in these examples becomes a Parquet file in the data folder, the setting chapter 1 explains. Without that setting, a small table lives in the catalog file, and a copy of the data folder would not hold its rows. That is one reason the catalog file needs a backup of its own.

Working rule: Back up a DuckLake catalog file with the data folder, and copy the file while no session has it attached. Give the data path when you create a catalog, and attach later with the catalog file alone.

카탈로그 없이 경로로 테이블 찾기

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

이 책에서 Delta Lake 테이블은 하나의 폴더다. 카탈로그가 없으며, 이 책의 설정 어디에서도 경로 외에 테이블에 이름을 붙이지 않는다. deltalake 패키지는 DeltaTable(path)로 폴더를 열고, 모든 읽기는 그 경로를 거친다. 다음 예제의 세 번의 추가(append)는 버전 0, 1, 2가 된다.

open-delta-by-path.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Open a Delta Lake table by its path, with no catalog, and read its first version and its current one. The pointrests on the 'rows at that version' and 'rows at version 0' lines, and the missing-path line shows the error."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import new_warehouse, read_cut_hour, read_deltawith new_warehouse() as wh:    path = str(wh.root / "delta" / "pageviews_hourly")    for hour in range(3):        write_deltalake(path, read_cut_hour(hour), mode="append")   # each append is one version, counted from 0    table = DeltaTable(path)    print("delta version:", table.version())    print("rows at that version:", read_delta(path).num_rows)    print("rows at version 0:", read_delta(path, version=0).num_rows)    # The path is the only name a Delta table has here: a wrong path is a missing table.    try:        DeltaTable(str(wh.root / "delta" / "pageviews_typo"))           # a path never written, so no log to open        print("missing path: opened")    except Exception as exc:        print("missing path:", type(exc).__name__)
출력python open-delta-by-path.py
delta version: 2
rows at that version: 1499
rows at version 0: 499
missing path: TableNotFoundError

테이블의 현재 버전은 2이고, 읽은 행은 1499개다. 버전 0에는 첫 한 시간 분량만 담긴 499개의 행이 있다. 여기서 행은 Arrow 테이블을 반환하는 read_delta로 읽는다. 이 책이 Delta 테이블을 그렇게 읽는 이유는 이 장 끝의 결정 사항에서 설명한다.

경로가 곧 이름의 전부이므로, 경로에 오타가 있으면 테이블이 없는 것과 같다. 예제는 존재하지 않는 폴더를 열고, DeltaTable은 TableNotFoundError를 발생시킨다. 오류는 시도한 경로를 알려 주지만, 그것은 잘못된 경로가 이미 사용된 뒤의 일이다. 따라서 확인은 경로를 만드는 코드에 두어야 한다.

경로는 한 작업이 쓰고 몇몇 작업이 읽는 테이블의 이름으로 알맞다. 서비스도 설정도 필요하지 않다. 그러나 대가도 있다. 경로는 테이블이 어느 네임스페이스에 속하는지 알려 주지 않으므로, 서로 다른 위치에 폴더 이름이 같은 테이블이 둘 있으면 읽는 사람에게는 똑같아 보인다. 이름으로 테이블을 찾으려는 엔진은 조회할 대상이 없다. 이 책의 Delta 테이블은 작고 로컬에 있으므로 경로로 충분하다. 여러 엔진이 읽는 공유 레이크에서는 Delta Lake 테이블을 위한 카탈로그가 필요하며, 이 책은 그것을 다루지 않는다.

작업 규칙: 각 Delta 테이블의 경로는 코드가 읽는 한곳, 예를 들어 설정 값에 보관하고, 작업을 시작할 때 테이블을 한 번 열어 경로를 확인한다. 존재하지 않는 경로는 빈 테이블이 아니라 오류다.

두 카탈로그의 테이블 조인

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

DuckDB는 라이브러리가 넘겨주는 Arrow 테이블과 같은 세션에 연결된 DuckLake 테이블을 하나의 문장으로 질의할 수 있다. Iceberg 테이블은 scan_arrow를 통해 pyiceberg에서 Arrow 테이블로 나온다. DuckDB는 그 테이블을 어떤 이름으로 등록하고, 조인은 연결된 카탈로그를 통해 wiki.domains를 읽는다. 이 책은 이 작업을 위해 DuckDB의 iceberg 확장을 로드하지 않는다. 따라서 Iceberg 쪽은 Arrow 테이블일 뿐 다른 것이 아니다.

join-pageviews-and-domains.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Join an Iceberg table, read through Arrow, with a DuckLake table in one DuckDB statement. The point rests on the'rows with no language' line, and the top-three block shows which rows the join returns first."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_iceberg_table,                           create_ducklake_domains, new_warehouse, print_rows, read_cut_hour,                           scan_arrow, sql_rows)with new_warehouse() as wh:    table = create_iceberg_table(wh)    for hour in range(3):                                # hours 0, 1 and 2 of the cut        table.append(read_cut_hour(hour))    con = connect_ducklake(wh.con)    create_ducklake_domains(con, wh.root)    pageviews = scan_arrow(table)                        # read now: the join sees the table as it is at this line    # sql_rows registers pageviews under that keyword name, so the SQL can refer to it as pageviews    joined = f"FROM pageviews p JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code"    print("joined rows:", sql_rows(con, f"SELECT count(*) {joined}", pageviews=pageviews)[0][0])    # the left join keeps every pageview, and this condition counts the ones that found no domain row    print("rows with no language:", sql_rows(con, f"""SELECT count(*) FROM pageviews p        LEFT JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code        WHERE d.domain_code IS NULL""", pageviews=pageviews)[0][0])    print("top three by views:")    print_rows(sql_rows(con, f"""SELECT p.domain_code, d.language, p.page_title, p.views {joined}        ORDER BY p.views DESC, p.domain_code, p.page_title, p.hour_utc LIMIT 3""", pageviews=pageviews, keep_order=True),        keep_order=True)
출력python join-pageviews-and-domains.py
joined rows: 1499
rows with no language: 0
top three by views:
en	English	Main_Page	64859
en	English	Main_Page	64564
en	English	Main_Page	61107

페이지뷰에 있는 모든 도메인 코드는 4행짜리 차원 테이블에 들어 있다. 조인은 페이지뷰 1499행을 언어에 대응시키고, 언어가 없는 행은 0행으로 남긴다. 조회수 상위 3개는 모두 같은 페이지로, 영어 도메인의 Main_Page이다.

조인 키는 domain_code이며 양쪽 모두 문자열이다. 대소문자나 뒤쪽 공백이 다른 키로 조인하면 어떤 행도 일치하지 않는다. 그러면 조인된 행 수는 0으로 줄고, 언어가 없는 행 수는 테이블의 행 수와 같아진다. 조인 결과를 믿기 전에 같은 세션에서 양쪽의 키를 확인한다.

이 질의가 동작하는 것은 양쪽이 하나의 DuckDB 세션에서 만나기 때문이다. 그렇다고 두 테이블이 하나가 되지는 않는다. 각 테이블은 자기 커밋을 그대로 가지며, Arrow 테이블은 scan_arrow가 실행된 시점의 Iceberg 테이블 스냅숏이다. 다른 쓰기 작업자가 바꾸고 있는 테이블을 조인하면, 그 시점에 최신이던 상태를 읽는다.

이와 같은 조회에는 카탈로그 간 조인을 권장한다. 자기 카탈로그에 남아 있는 작은 차원 테이블을, 큰 테이블에 대한 질의가 읽는 경우다. 어떤 테이블이 다른 테이블을 읽는 거의 모든 질의에 나타난다면, 그 질의들이 쓰는 카탈로그로 복사한다. 9장은 형식 사이에서 테이블을 복사하고 각 복사본을 검증하는데, 테이블을 어디로 옮기든 그 전에 거쳐야 할 단계가 이 검증이다.

작업 규칙: 한 세션에서 카탈로그 간 조인은 Arrow로 읽는 쪽이 메모리에 들어갈 때만 한다. 읽기 전에 그 상태를 정하고, 일치하는 짝이 없는 행의 수를 센다. 그 수는 0이어야 한다.

이 부분은 아직 번역되지 않았으므로 영어로 표시된다.

What goes wrong in production

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

The symptoms are usually small: a count that stops moving, a namespace that is missing, or a read error on a table that was read before. Each case here starts from one of them.

Only the last failure below has no example.

The wrong catalog name. The last line of register-iceberg-table opens the same file under the name other. Listing the namespace then fails with NoSuchNamespaceError: Namespace does not exist: wiki. The table is still in the file. The SQL catalog scopes its tables by catalog name, so the second name sees an empty catalog. The message names the namespace, not the name, so the error looks like a missing schema. A job that builds its catalog name from configuration can fail this way after a small edit. You notice it at the first read, not at the write, so log the catalog name at the start of the job.

The stale pointer. A process that loads a table and reads it much later reads the state from when it loaded. register-iceberg-table showed 1499 rows in the loaded object, where a reload shows 1999. Nothing fails. The job runs and reports fewer rows than the table holds. You notice it when two jobs disagree about a count, so keep the load next to the read.

The catalog file replaced by an empty one. The next example attaches a fresh, empty catalog file to the data folder of a live catalog, then runs ducklake_delete_orphaned_files with cleanup_all => true. The DuckLake cleanup page shows cleanup_all deleting all orphaned files, and dry_run listing them instead. It defines an orphan as a file that the catalog you run it against does not track. A fresh catalog tracks nothing, so every Parquet file in the folder is an orphan to it.

ducklake-orphan-cleanup-hazard.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 통과
"""Run cleanup_all against a fresh, empty DuckLake catalog that shares a data folder with a live one. The point restson the 'parquet files after cleanup_all' line and the 'reading the live catalog' line."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_ducklake_domains,                           new_warehouse, sql_rows)# One statement, run twice: first with dry_run => true, then for real. {dry} holds the dry-run argument or nothing.CLEANUP = "CALL ducklake_delete_orphaned_files('fresh', cleanup_all => true{dry})"def parquet_count(root):    # the data folder that attach_ducklake gives the catalog with the live alias; rglob searches it at any depth    return len(list((root / f"{DUCKLAKE_ALIAS}_data").rglob("*.parquet")))with new_warehouse() as wh:    con = connect_ducklake(wh.con)    create_ducklake_domains(con, wh.root)    print("parquet files, live catalog:", parquet_count(wh.root))    # A replacement catalog: a new, empty file that points at the same data folder.    con.execute(f"DETACH {DUCKLAKE_ALIAS}")    # Attached by hand: attach_ducklake would give fresh its own data folder, not the live one.    con.execute(f"ATTACH 'ducklake:{wh.root}/fresh.ducklake' AS fresh (DATA_PATH '{wh.root}/{DUCKLAKE_ALIAS}_data/')")    print("files the dry run lists:", len(sql_rows(con, CLEANUP.format(dry=", dry_run => true"))))    con.execute(CLEANUP.format(dry=""))    print("parquet files after cleanup_all:", parquet_count(wh.root))    # The live catalog still names the table, and its data files are gone.    con.execute(f"ATTACH 'ducklake:{wh.root}/{DUCKLAKE_ALIAS}.ducklake' AS live")    print("count through the live catalog:", sql_rows(con, f"SELECT count(*) FROM live.{NAMESPACE}.domains")[0][0])    try:        print("reading the live catalog:", len(sql_rows(con, f"SELECT domain_code, language FROM live.{NAMESPACE}.domains")))    except Exception as exc:        print("reading the live catalog:", type(exc).__name__)
출력python ducklake-orphan-cleanup-hazard.py
parquet files, live catalog: 1
files the dry run lists: 1
parquet files after cleanup_all: 0
count through the live catalog: 4
reading the live catalog: IOException

A fresh catalog is enough to delete the live data. Before the cleanup, the live catalog's data is in 1 Parquet file. The dry run with cleanup_all lists 1 file, which the real run deletes, and afterwards the folder holds 0 Parquet files.

A count check passes here, and that is the trap: it does not show missing files. The live catalog still names the table, and it answers count(*) with 4, from the catalog's statistics. Reading its columns fails with IOException.

The safe order begins with what the example skipped. Back up the catalog file first. Run the cleanup with dry_run => true against the catalog that owns the data folder, and read the list. Run it for real only when every listed file is one you know is orphaned. Never run cleanup_all => true against a catalog you have not confirmed.

Two writers on one SQLite catalog. The pyiceberg documentation says SQLite is not built for concurrency. This chapter does not show what two writers do to the SQL catalog, so the book does not claim that they are safe. The stale-pointer example is the nearest case it does show: an object loaded before a commit reads the older state, and no error is raised. A writer that holds an old object does not write against that old state. At the pinned version of pyiceberg, an append through such an object is retried against the new metadata and commits on top of the newer state. The book makes no claim for other operations, or for two processes on one SQLite catalog. The reload rule in the SQL catalog section applies to reads.

Working rule: Run an orphan cleanup with dry_run => true first, against the catalog that owns the data folder, and read the list before any real run. If the catalog file is missing or empty, restore it before you run anything that deletes files.

이 장에서 내린 결정

마지막으로 변경된 판: 2026.11.7판
  • Iceberg는 로컬 웨어하우스를 사용하는 SQLite 기반 pyiceberg SQL 카탈로그에 등록한다. 이 책의 카탈로그 이름은 local 하나뿐이며, 모든 예제가 이 이름을 사용한다. pyiceberg 문서는 개발용으로 SQLite를 설명하고, 이 책의 예제도 개발용 예제이다.
  • Iceberg 테이블은 Arrow 테이블로 DuckDB에 전달된다. 이 책은 DuckDB의 iceberg 확장을 사용하지 않으므로, 예제는 scan_arrow을 통해 Iceberg 데이터를 읽는다.
  • Delta Lake 테이블은 경로로 찾으며, 이 책은 Delta 카탈로그를 다루지 않는다. 모든 Delta 예제는 폴더를 열고, 폴더가 없으면 오류가 발생한다.
  • Delta 테이블은 QueryBuilder만으로 읽는다. 이는 1차 자료가 아니라 이 책을 빌드하면서 얻은 측정 결과이다. 고정된 버전에서 다른 Arrow 변환 방법은 20회 실행 중 약 17회에서 종료 시 프로세스가 중단되었다. QueryBuilder 경로는 이전 버전을 읽는 경우를 포함하여 24회 실행 중 한 번도 중단되지 않았다.
  • DuckLake는 다운로드를 끈 상태로 connect_ducklake를 통해 로드한다. 모든 예제는 고정된 DuckDB 버전에서 오프라인으로 실행된다.
  • 정리 작업의 위험은 임시 폴더에서 실행하며 개수만 출력한다. 이 책은 안전한 단계의 순서가 분명해지도록 실패 사례를 보여 준다. 실행할 때마다 달라지는 파일 이름은 출력하지 않는다.
  • 각 예제는 개수와 이름을 붙인 값만 출력한다. 그 이유는 1장에 있으며, 이렇게 하면 출력이 실행할 때마다, 어느 기기에서나 같게 읽힌다.
  • REST 카탈로그는 실행 가능한 예제가 없다. REST 카탈로그에는 네트워크가 필요하므로, 이 장은 해당 문서를 바탕으로 프로토콜을 설명하고 어떤 제품에 대해서도 주장하지 않는다.

이 판의 이 장

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

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

이 절 인용

형식

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

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

이 페이지의 내용

10장 중 8장: 카탈로그에 테이블을 등록하고 DuckDB에서 조회하기

  1. 카탈로그가 담고 있는 것
  2. SQL 카탈로그에 테이블 등록하기
  3. 메타데이터 파일로 테이블 등록하기
  4. Attach a DuckLake catalog
  5. 카탈로그 없이 경로로 테이블 찾기
  6. 두 카탈로그의 테이블 조인
  7. What goes wrong in production
  8. 이 장에서 내린 결정

맨 위로 돌아가기전체 장