Registra tablas en un catálogo y consúltalas desde DuckDB
Unos 18 minutos de lectura, con 5 ejemplos en 8 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.10. Lee el original
En este capítulo registras una tabla de Iceberg en un catálogo SQL, adjuntas un catálogo de DuckLake, abres una tabla de Delta Lake por su ruta y ejecutas una sentencia de DuckDB que une una tabla de Iceberg con una tabla de DuckLake. También aprendes qué guarda cada catálogo y qué pasa con una tabla cuando su catálogo y sus archivos de datos no coinciden.
Los capítulos anteriores abrieron cada tabla por su propia vía: un objeto de catálogo para Iceberg, un archivo para DuckLake, una carpeta para Delta Lake. La primera tabla registró wiki.pageviews_hourly en un catálogo SQL de Iceberg con el nombre local. Este capítulo explica qué hace ese nombre y qué usa cada formato en su lugar. También añade una segunda tabla, wiki.domains. Es una lista de 4 filas de códigos de dominio y del idioma en que está cada uno. Esa tabla vive en el catálogo de DuckLake, y la sección de la unión la une con las visualizaciones de páginas de Iceberg.
Qué guarda un catálogo
Pregunta dónde vive wiki.pageviews_hourly, y la respuesta depende del formato. Por debajo, cada formato guarda una tabla como archivos de datos más archivos de metadatos. Los metadatos indican el estado actual de la tabla: su esquema, su especificación de particiones y, directamente o a través de archivos de manifiesto, los archivos de datos de su instantánea o versión actual. Cada confirmación escribe metadatos nuevos y mueve la tabla hacia ellos. El catálogo es el registro que asocia el nombre de una tabla con el lugar donde están sus metadatos actuales. Un lector que pide al catálogo wiki.pageviews_hourly obtiene un puntero a los metadatos y, a continuación, lee los archivos de datos que enumeran esos metadatos.
El catálogo guarda punteros, no las filas. Los archivos Parquet permanecen en la carpeta del almacén, y el catálogo indica desde dónde empezar a leer. Los nombres tienen además un segundo nivel: wiki es un espacio de nombres, y cada nombre de tabla Iceberg de este libro es un espacio de nombres y un nombre de tabla unidos por un punto.
Elegir un catálogo se reduce a dos preguntas: quién escribe la tabla y quién la lee. Una tabla que escribe un trabajo y lee un único motor puede vivir en un catálogo basado en archivos y encontrarse por su ruta. Una tabla que leen varios motores necesita un nombre que cada uno pueda resolver, que es lo que ofrece un catálogo SQL o un servicio. Recomendamos un catálogo por cada tabla, y un registro junto a la tabla que indique su catálogo y su propietario. Una unión entre catálogos, como muestra la sección de uniones, funciona en una sola sesión. No convierte los dos catálogos en uno.
Los tres formatos de este libro usan tres catálogos distintos:
| Formato | Qué nombra la tabla | Dónde están los metadatos actuales |
|---|---|---|
| Iceberg | Un objeto de catálogo SQL, aquí llamado local |
La base de datos del catálogo, que apunta al archivo de metadatos |
| DuckLake | El archivo de catálogo, adjuntado por ruta | Dentro del archivo de catálogo |
| Delta Lake | Nada; la ruta de la carpeta de la tabla | En la carpeta de la tabla |
El catálogo REST de Iceberg es un catálogo de otro tipo, un servicio en lugar de un archivo. Su página del catálogo REST describe una API común, especificada con OpenAPI, para interactuar con cualquier catálogo de Iceberg, de modo que los clientes necesiten una sola implementación para todos. La misma página indica que el protocolo usa confirmaciones basadas en cambios, de modo que el servicio puede resolver conflictos y reintentar por su cuenta, y que el servicio del catálogo escribe los metadatos raíz. Este capítulo no ejecuta ningún catálogo REST. Cada uno necesita un servicio en ejecución, y los ejemplos de aquí funcionan sin conexión y sin ningún servicio. El libro no compara los productos que implementan el protocolo.
Un catálogo puede guardar más que nombres. Las clasificaciones y las reglas de retención también son metadatos de tabla. Data Governance as Code las cubre, y este libro no las enseña.
Regla práctica: Antes de escribir en una tabla, averigua qué catálogo o ruta la nombra, y haz una copia de seguridad de ese catálogo junto con la carpeta de datos. Los archivos Parquet no nombran una tabla. El catálogo sí, como muestra la sección de fallos.
Registra una tabla en un catálogo SQL
El SqlCatalog de pyiceberg guarda sus tablas en una base de datos. Le das un uri para esa base de datos y un warehouse para la carpeta donde escribe los archivos de datos y de metadatos. Este libro usa un archivo SQLite para la base de datos y una carpeta local para el warehouse. La página de configuración de pyiceberg indica que el catálogo SQL necesita una base de datos detrás, y advierte que SQLite no está pensado para la concurrencia y es adecuado para uso exploratorio o de desarrollo. Estos ejemplos son para desarrollo, así que ese límite no cambia nada en ellos. Un catálogo de producción necesita una base de datos que varios escritores puedan usar.
El siguiente ejemplo abre por segunda vez el mismo archivo de catálogo, con el mismo nombre, y lee la tabla a través de ese segundo objeto. Después registra un segundo nombre para los metadatos de la tabla y muestra lo que puede ver un objeto de catálogo con un nombre distinto.
1"""Register an Iceberg table in a SQL catalog, then reach it through a second catalog object, a stale object and a2second name. The point rests on the 'loaded object' and 'after a reload' lines, and the last line shows what an3object under another catalog name can see."""45from lib.lakehouse import (ICEBERG_ID, NAMESPACE, create_iceberg_table, new_warehouse,6 open_catalog, read_cut_hour, safe_error, scan_arrow)78with new_warehouse() as wh:9 table = create_iceberg_table(wh)10 for hour in range(3): # hours 0, 1 and 2 of the cut, one commit each11 table.append(read_cut_hour(hour))1213 # A second object with the same catalog name sees the same tables.14 same = open_catalog(wh) # the default name, local, as the first object had15 loaded = same.load_table(ICEBERG_ID)16 print("rows read through the second object:", scan_arrow(loaded).num_rows)1718 # A loaded table is a snapshot of the catalog as it was when loaded.19 stale = same.load_table(ICEBERG_ID)20 table.append(read_cut_hour(3)) # the fourth hour, committed after stale was loaded21 print("rows in the loaded object after another append:", scan_arrow(stale).num_rows)22 print("rows after a reload:", scan_arrow(same.load_table(ICEBERG_ID)).num_rows)2324 # Register the same metadata file under a new name: a pointer, not a copy.25 same.create_namespace("archive")26 same.register_table("archive.pageviews_copy", table.metadata_location)27 print("rows in archive copy:", scan_arrow(same.load_table("archive.pageviews_copy")).num_rows)2829 # An object with another name does not see the namespace: the SQL catalog keeps tables apart by catalog name.30 try:31 open_catalog(wh, name="other").list_tables(NAMESPACE)32 except Exception as exc:33 print("other name:", safe_error(exc, wh))
python register-iceberg-table.pyrows 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
El segundo objeto lee 1499 filas de wiki.pageviews_hourly, las tres horas que el capítulo 1 cargó. pyiceberg guarda cada tabla bajo el nombre de catálogo que pasas a SqlCatalog. Un objeto con el mismo nombre encuentra las mismas tablas.
El catálogo y la carpeta del warehouse forman un par. El catálogo guarda las ubicaciones de los archivos de metadatos, y esas ubicaciones están bajo la carpeta que indica la propiedad warehouse. Una copia del archivo de catálogo sin la carpeta del warehouse, o la carpeta sin el archivo, te deja con punteros a archivos que no existen. Haz copia de seguridad de ambos, y muévelos siempre juntos.
Cada proceso abre su propio objeto de catálogo, y ninguno comparte estado con otro. Aquí, dos objetos dentro de un mismo proceso hacen el papel de dos procesos.
Una tabla cargada conserva el estado que tenía cuando se cargó. Un objeto de antes de la adición de la cuarta hora sigue leyendo 1499 filas, mientras que una recarga lee 1999. Un proceso que carga una tabla al inicio y la lee al final lee el estado del inicio. Tiene que recargarla para ver los commits hechos entre medias.
Regla práctica: Abre un archivo de catálogo SQL con un único nombre en todo tu código, y recarga una tabla antes de leerla cuando otro escritor pueda haber hecho un commit desde que la cargaste. Mantén SQLite para un solo escritor a la vez, y usa una base de datos diseñada para escrituras concurrentes antes de ejecutar varios.
Registrar una tabla desde su archivo de metadatos
register_table(identifier, metadata_location) añade un nombre para un archivo de metadatos existente. La página de la API de pyiceberg lo presenta como la forma de registrar una tabla a partir de sus metadatos, y explica que pasar overwrite=True reemplaza una entrada que ya existe. El ejemplo registra los metadatos de la tabla bajo archive.pageviews_copy, en un espacio de nombres que crea primero. El nombre de archivo (archive) lee las mismas filas que la tabla original, 1999 en total. Ambos nombres apuntan a los mismos metadatos, y el registro no escribe archivos de datos.
Un nombre registrado es una segunda vía hacia la misma tabla, no una segunda tabla. Las confirmaciones realizadas a través de un nombre son las de ambos, porque los dos leen los mismos metadatos. Considera un segundo nombre como una ruta de lectura, y no como una copia de seguridad.
Regla práctica: Mantén un solo nombre de escritura para cada tabla. Registra un archivo de metadatos bajo un segundo nombre solo para una lectura que vayas a eliminar después, y pasa overwrite=True únicamente cuando quieras reemplazar esa entrada.
Adjuntar un catálogo de DuckLake
El catálogo de DuckLake es un archivo de base de datos, y DuckDB lo adjunta con una sentencia ATTACH que empieza con ducklake: y da la ruta del archivo. La ruta de datos, la carpeta donde DuckLake escribe los archivos Parquet, se guarda en el catálogo. La página de conexión de DuckLake indica que la ubicación de almacenamiento de datos solo hay que darla al crear un DuckLake nuevo, y que después la ubicación se carga desde la base de datos del catálogo. El asistente connect_ducklake carga DuckLake en la sesión de DuckDB con las descargas desactivadas, y attach_ducklake ejecuta el ATTACH para un archivo de catálogo ubicado dentro de una carpeta.
El siguiente ejemplo crea wiki.domains en un catálogo de DuckLake nuevo, lo desconecta y vuelve a adjuntar el archivo sin ruta de datos. Después lista las tablas del esquema wiki del archivo.
1"""Attach a DuckLake catalog file, detach it, and attach it again from the file alone. The point rests on the2'rows after re-attach' line, and the table list shows what the catalog holds, not what the data folder holds."""34from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, attach_ducklake, connect_ducklake,5 create_ducklake_domains, new_warehouse, print_rows, sql_rows)67with new_warehouse() as wh:8 con = connect_ducklake(wh.con)9 create_ducklake_domains(con, wh.root) # inlining is off, so the rows become Parquet files10 print("rows written:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])1112 # Detach, then attach with no DATA_PATH: the catalog file stores the data path.13 con.execute(f"DETACH {DUCKLAKE_ALIAS}")14 attach_ducklake(con, DUCKLAKE_ALIAS, wh.root)15 print("tables in the catalog:")16 print_rows(sql_rows(con, f"""SELECT schema_name, table_name FROM duckdb_tables()17 WHERE database_name = '{DUCKLAKE_ALIAS}' AND schema_name = '{NAMESPACE}'"""))18 print("rows after re-attach:", sql_rows(con, f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.domains")[0][0])
python attach-ducklake.pyrows written: 4
tables in the catalog:
wiki domains
rows after re-attach: 4
Se escriben 4 filas de wiki.domains, y al volver a adjuntar se leen 4 filas. La lista de tablas muestra una tabla en el esquema wiki, domains. La segunda vez que se adjuntó no hizo falta ninguna ruta de datos, porque el archivo ya la contenía. El listado procede del catálogo, no de la carpeta de datos. El archivo del catálogo guarda la lista de tablas, y la carpeta de datos guarda los bytes. Si se pierde el primero, se pierden los nombres aunque el segundo esté intacto, como muestra la sección sobre fallos.
La misma página de conexión indica que DuckLake incluye las inserciones pequeñas directamente en la base de datos del catálogo, con un límite predeterminado de 10 filas. El asistente que usa este capítulo establece el límite de inclusión en 0, de modo que cada inserción en estos ejemplos se convierte en un archivo Parquet en la carpeta de datos, configuración que explica el capítulo 1. Sin esa configuración, una tabla pequeña vive en el archivo del catálogo, y una copia de la carpeta de datos no contendría sus filas. Esa es una de las razones por las que el archivo del catálogo necesita una copia de seguridad propia.
Regla práctica: Haz una copia de seguridad de un archivo de catálogo de DuckLake junto con la carpeta de datos, y copia el archivo mientras ninguna sesión lo tenga adjuntado. Indica la ruta de datos al crear un catálogo, y adjúntalo más adelante usando solo el archivo del catálogo.
Buscar una tabla por su ruta, sin catálogo
Una tabla de Delta Lake en este libro es una carpeta. No tiene catálogo, y nada en la configuración de este libro la nombra aparte de su ruta. El paquete deltalake abre la carpeta con DeltaTable(path), y toda lectura pasa por esa ruta. Las tres anexiones de datos del siguiente ejemplo son las versiones 0, 1 y 2.
1"""Open a Delta Lake table by its path, with no catalog, and read its first version and its current one. The point2rests on the 'rows at that version' and 'rows at version 0' lines, and the missing-path line shows the error."""34from deltalake import DeltaTable, write_deltalake56from lib.lakehouse import new_warehouse, read_cut_hour, read_delta78with new_warehouse() as wh:9 path = str(wh.root / "delta" / "pageviews_hourly")10 for hour in range(3):11 write_deltalake(path, read_cut_hour(hour), mode="append") # each append is one version, counted from 01213 table = DeltaTable(path)14 print("delta version:", table.version())15 print("rows at that version:", read_delta(path).num_rows)16 print("rows at version 0:", read_delta(path, version=0).num_rows)1718 # The path is the only name a Delta table has here: a wrong path is a missing table.19 try:20 DeltaTable(str(wh.root / "delta" / "pageviews_typo")) # a path never written, so no log to open21 print("missing path: opened")22 except Exception as exc:23 print("missing path:", type(exc).__name__)
python open-delta-by-path.pydelta version: 2
rows at that version: 1499
rows at version 0: 499
missing path: TableNotFoundError
La versión actual de la tabla es 2, y lee 1499 filas. La versión 0 contiene 499 filas, solo la primera hora. Las filas se obtienen mediante read_delta, que devuelve una tabla de Arrow. Las decisiones al final de este capítulo explican por qué el libro lee las tablas Delta de esa manera.
La ruta es el nombre completo, así que un error de escritura en ella equivale a una tabla inexistente. El ejemplo abre una carpeta que no existe, y DeltaTable lanza TableNotFoundError. El error indica la ruta que intentó usar, pero solo después de haber usado la ruta incorrecta, por lo que la comprobación debe ir en el código que construye la ruta.
Una ruta es un buen nombre para una tabla que escribe un solo trabajo y leen algunos pocos. No necesita ningún servicio ni configuración. Sin embargo, tiene costos. Una ruta no indica en qué espacio de nombres está una tabla, así que dos tablas con el mismo nombre de carpeta en lugares distintos se ven idénticas para quien lee. Un motor que quiera encontrar la tabla por su nombre no tiene nada que consultar. Las tablas Delta de este libro son pequeñas y locales, y la ruta basta para ellas. Un lago compartido que leen varios motores necesita un catálogo para sus tablas de Delta Lake, y este libro no enseña uno.
Regla práctica: Guarda la ruta de cada tabla Delta en un único lugar que tu código lea, como un valor de configuración, y abre la tabla una vez al inicio de un trabajo para confirmar la ruta. Una ruta que no existe es un error, no una tabla vacía.
Unir tablas de dos catálogos
DuckDB puede consultar una tabla Arrow que una biblioteca le entrega, y una tabla DuckLake que está adjunta a la misma sesión, en una sola sentencia. La tabla Iceberg sale de pyiceberg como tabla Arrow mediante scan_arrow. DuckDB registra esa tabla con un nombre, y la unión lee wiki.domains a través del catálogo adjunto. El libro no carga la extensión iceberg de DuckDB para esto, así que el lado Iceberg es la tabla Arrow y nada más.
1"""Join an Iceberg table, read through Arrow, with a DuckLake table in one DuckDB statement. The point rests on the2'rows with no language' line, and the top-three block shows which rows the join returns first."""34from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_iceberg_table,5 create_ducklake_domains, new_warehouse, print_rows, read_cut_hour,6 scan_arrow, sql_rows)78with new_warehouse() as wh:9 table = create_iceberg_table(wh)10 for hour in range(3): # hours 0, 1 and 2 of the cut11 table.append(read_cut_hour(hour))12 con = connect_ducklake(wh.con)13 create_ducklake_domains(con, wh.root)1415 pageviews = scan_arrow(table) # read now: the join sees the table as it is at this line16 # sql_rows registers pageviews under that keyword name, so the SQL can refer to it as pageviews17 joined = f"FROM pageviews p JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code"18 print("joined rows:", sql_rows(con, f"SELECT count(*) {joined}", pageviews=pageviews)[0][0])19 # the left join keeps every pageview, and this condition counts the ones that found no domain row20 print("rows with no language:", sql_rows(con, f"""SELECT count(*) FROM pageviews p21 LEFT JOIN {DUCKLAKE_ALIAS}.{NAMESPACE}.domains d ON p.domain_code = d.domain_code22 WHERE d.domain_code IS NULL""", pageviews=pageviews)[0][0])23 print("top three by views:")24 print_rows(sql_rows(con, f"""SELECT p.domain_code, d.language, p.page_title, p.views {joined}25 ORDER BY p.views DESC, p.domain_code, p.page_title, p.hour_utc LIMIT 3""", pageviews=pageviews, keep_order=True),26 keep_order=True)
python join-pageviews-and-domains.pyjoined 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
Todo código de dominio de las vistas de página está en la dimensión de 4 filas. La unión asigna 1499 filas de vistas de página a un idioma y deja 0 sin uno. Los tres primeros por visitas son la misma página, Main_Page en el dominio inglés.
La clave de unión es domain_code, una cadena en ambos lados. Una unión sobre una clave que difiere en mayúsculas o en espacios finales no encuentra coincidencias: el recuento de filas unidas bajaría a 0, y el recuento de filas sin idioma igualaría el número de filas de la tabla. Revisa la clave en ambos lados, dentro de la misma sesión, antes de fiarte de una unión.
La consulta funciona porque ambos lados se encuentran en una sola sesión de DuckDB. No convierte las dos tablas en una sola. Cada una conserva sus propias confirmaciones, y la tabla Arrow es una instantánea de la tabla Iceberg en el momento en que scan_arrow se ejecutó. Una unión sobre una tabla que otro escritor está modificando lee el estado que estaba vigente en ese momento.
Recomendamos una unión entre catálogos para búsquedas como esta: una tabla de dimensiones pequeña que permanece en su propio catálogo, leída por una consulta sobre una tabla grande. Cuando una tabla aparece en casi todas las consultas que leen otra, cópiala al catálogo que usan esas consultas. El capítulo 9 copia una tabla entre formatos y verifica cada copia, y esa verificación es el paso que conviene dar antes de mover una tabla a cualquier parte.
Regla práctica: Une tablas de catálogos distintos en una sola sesión solo cuando el lado que lees como Arrow cabe en memoria. Elige su estado antes de leerlo, y cuenta las filas que no encuentran pareja, que deben ser cero.
Qué sale mal en producción
Los síntomas suelen ser pequeños: un conteo que deja de cambiar, un espacio de nombres que falta o un error de lectura en una tabla que antes se leía bien. Cada caso aquí parte de uno de ellos.
Solo el último fallo de abajo no tiene ejemplo.
El nombre de catálogo equivocado. La última línea de register-iceberg-table abre el mismo archivo con el nombre other. Al listar el espacio de nombres, falla con NoSuchNamespaceError: Namespace does not exist: wiki. La tabla sigue en el archivo. El catálogo SQL delimita sus tablas por el nombre del catálogo, así que el segundo nombre ve un catálogo vacío. El mensaje nombra el espacio de nombres, no el nombre, por lo que el error parece un esquema que falta. Un trabajo que construye el nombre del catálogo a partir de la configuración puede fallar así tras una pequeña modificación. Lo notas en la primera lectura, no en la escritura, así que registra el nombre del catálogo al inicio del trabajo.
El puntero desactualizado. Un proceso que carga una tabla y la lee mucho después lee el estado del momento en que la cargó. register-iceberg-table mostró 1499 filas en el objeto cargado, donde una recarga muestra 1999. Nada falla. El trabajo se ejecuta y comunica menos filas de las que tiene la tabla. Lo notas cuando dos trabajos no coinciden en un conteo, así que mantén la carga junto a la lectura.
El archivo de catálogo reemplazado por uno vacío. El siguiente ejemplo adjunta un archivo de catálogo nuevo y vacío a la carpeta de datos de un catálogo activo, y después ejecuta ducklake_delete_orphaned_files con cleanup_all => true. La página de limpieza de DuckLake muestra que cleanup_all elimina todos los archivos huérfanos, y que dry_run solo los lista. Define un huérfano como un archivo que el catálogo con el que lo ejecutas no registra. Un catálogo nuevo no registra nada, así que cada archivo Parquet de la carpeta es un huérfano para él.
1"""Run cleanup_all against a fresh, empty DuckLake catalog that shares a data folder with a live one. The point rests2on the 'parquet files after cleanup_all' line and the 'reading the live catalog' line."""34from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, connect_ducklake, create_ducklake_domains,5 new_warehouse, sql_rows)67# One statement, run twice: first with dry_run => true, then for real. {dry} holds the dry-run argument or nothing.8CLEANUP = "CALL ducklake_delete_orphaned_files('fresh', cleanup_all => true{dry})"910def parquet_count(root):11 # the data folder that attach_ducklake gives the catalog with the live alias; rglob searches it at any depth12 return len(list((root / f"{DUCKLAKE_ALIAS}_data").rglob("*.parquet")))1314with new_warehouse() as wh:15 con = connect_ducklake(wh.con)16 create_ducklake_domains(con, wh.root)17 print("parquet files, live catalog:", parquet_count(wh.root))1819 # A replacement catalog: a new, empty file that points at the same data folder.20 con.execute(f"DETACH {DUCKLAKE_ALIAS}")21 # Attached by hand: attach_ducklake would give fresh its own data folder, not the live one.22 con.execute(f"ATTACH 'ducklake:{wh.root}/fresh.ducklake' AS fresh (DATA_PATH '{wh.root}/{DUCKLAKE_ALIAS}_data/')")23 print("files the dry run lists:", len(sql_rows(con, CLEANUP.format(dry=", dry_run => true"))))24 con.execute(CLEANUP.format(dry=""))25 print("parquet files after cleanup_all:", parquet_count(wh.root))2627 # The live catalog still names the table, and its data files are gone.28 con.execute(f"ATTACH 'ducklake:{wh.root}/{DUCKLAKE_ALIAS}.ducklake' AS live")29 print("count through the live catalog:", sql_rows(con, f"SELECT count(*) FROM live.{NAMESPACE}.domains")[0][0])30 try:31 print("reading the live catalog:", len(sql_rows(con, f"SELECT domain_code, language FROM live.{NAMESPACE}.domains")))32 except Exception as exc:33 print("reading the live catalog:", type(exc).__name__)
python ducklake-orphan-cleanup-hazard.pyparquet 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
Basta un catálogo nuevo para borrar los datos activos. Antes de la limpieza, los datos del catálogo activo están en 1 archivo Parquet. La ejecución en seco con cleanup_all lista 1 archivo, que la ejecución real borra, y después la carpeta contiene 0 archivos Parquet.
Una comprobación de conteo pasa aquí, y ahí está la trampa: no muestra los archivos que faltan. El catálogo activo sigue nombrando la tabla y responde count(*) con 4, a partir de las estadísticas del catálogo. Leer sus columnas falla con IOException.
El orden seguro empieza por lo que el ejemplo omitió. Primero haz una copia de seguridad del archivo de catálogo. Ejecuta la limpieza con dry_run => true contra el catálogo que es dueño de la carpeta de datos, y lee la lista. Ejecútala de verdad solo cuando sepas que cada archivo listado es un huérfano. Nunca ejecutes cleanup_all => true contra un catálogo que no hayas confirmado.
Dos escritores en un mismo catálogo SQLite. La documentación de pyiceberg indica que SQLite no está pensado para la concurrencia. Este capítulo no muestra qué les ocurre a dos escritores sobre el catálogo SQL, así que el libro no afirma que sean seguros. El ejemplo del puntero desactualizado es el caso más cercano que sí muestra: un objeto cargado antes de una confirmación lee el estado anterior, y no se genera ningún error. Un escritor que conserva un objeto antiguo no escribe contra ese estado antiguo. En la versión fijada de pyiceberg, un append a través de ese objeto se reintenta contra los metadatos nuevos y se confirma sobre el estado más reciente. El libro no hace afirmaciones sobre otras operaciones, ni sobre dos procesos en un mismo catálogo SQLite. La regla de recarga de la sección del catálogo SQL se aplica a las lecturas.
Regla práctica: Ejecuta una limpieza de huérfanos con dry_run => true primero, contra el catálogo que es dueño de la carpeta de datos, y lee la lista antes de cualquier ejecución real. Si el archivo de catálogo falta o está vacío, restáuralo antes de ejecutar algo que borre archivos.
Decisiones que tomó este capítulo
- Iceberg se registra en un catálogo SQL de pyiceberg sobre SQLite, con un almacén local. El libro tiene un único nombre de catálogo,
local, y todos los ejemplos lo usan. La documentación de pyiceberg describe SQLite para desarrollo, y los ejemplos son ejemplos de desarrollo. - Las tablas de Iceberg llegan a DuckDB como tablas de Arrow. El libro no usa la extensión
icebergde DuckDB, así que los ejemplos leen los datos de Iceberg mediantescan_arrow. - Las tablas de Delta Lake se localizan por ruta, y el libro no enseña ningún catálogo de Delta. Cada ejemplo de Delta abre una carpeta, y una carpeta que falta es un error.
- Las tablas de Delta se leen solo mediante
QueryBuilder. Esta es una medición de la compilación del libro, no una fuente primaria. Con las versiones fijadas, los otros métodos de conversión a Arrow interrumpieron el proceso al salir en unas 17 de 20 ejecuciones. La víaQueryBuilderno se interrumpió en ninguna de 24 ejecuciones, incluidas las lecturas de versiones anteriores. - DuckLake se carga mediante
connect_ducklake, con las descargas desactivadas. Todos los ejemplos se ejecutan sin conexión con la versión fijada de DuckDB. - El riesgo de limpieza se ejecuta en una carpeta temporal e imprime solo recuentos. El libro muestra el fallo para que quede claro el orden de los pasos seguros. No imprime nombres de archivo, que cambian en cada ejecución.
- Cada ejemplo imprime solo recuentos y valores etiquetados, por la razón expuesta en el capítulo 1: así la salida se lee igual en cada ejecución y en cada máquina.
- Los catálogos REST no tienen un ejemplo ejecutable. Necesitan red, así que el capítulo describe el protocolo a partir de su página y no hace afirmaciones sobre ningún producto.
Este capítulo, en esta edición
Edición 2026.11.10Ejemplos verificados el 20 de nov de 2026Superan la prueba 5 de 5 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.10.