Construye una primera tabla, de principio a fin

Unos 20 minutos de lectura, con 3 ejemplos en 10 secciones.

Edición 2026.11.10 Ejemplos verificados el 20 de nov de 2026 39 de 39 ejemplos pasan Qué ha cambiado

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

Al final de este capítulo podrás confirmar lotes de filas en una tabla, leer la tabla de nuevo en DuckDB y comprobar los totales. Este libro está pensado para ingenieros de datos y de analítica que escriben SQL y Python y tienen que decidir cómo se almacenan, cambian, limpian, comparten y mueven entre formatos las tablas de su lakehouse. Construye un único resultado: una tabla de pageviews que almacenas, cambias, lees tal como estaba en una instantánea anterior, limpias, registras en un catálogo y mueves entre formatos.

Seis horas de visitas a páginas de Wikimedia guardadas en una carpeta todavía no son una tabla. La carpeta no indica qué archivos pertenecen a la tabla, y una carga que se detiene a mitad deja un archivo que parece igual a los demás. La tabla que construye este libro es horaria: cada fila indica cuántas veces se vio un artículo público de Wikipedia en una hora, en una edición de idioma de Wikipedia. La llamamos la tabla de pageviews.

Este capítulo construye una versión sencilla de esa tabla. La escribe en tres formatos (Apache Iceberg, Delta Lake y DuckLake) y la lee de nuevo en DuckDB, para que puedas comparar los totales. Cada capítulo posterior hace sólido un paso:

  • El capítulo 2 lee la tabla tal como estaba en una instantánea anterior.
  • El capítulo 3 añade y renombra columnas sin reescribir archivos.
  • El capítulo 4 cambia el particionado sin reescribir los archivos antiguos.
  • El capítulo 5 corrige filas con borrados, actualizaciones y merges.
  • El capítulo 6 compacta los archivos pequeños que dejan las adiciones horarias.
  • El capítulo 7 caduca instantáneas y elimina los archivos que ninguna instantánea alcanza.
  • El capítulo 8 registra tablas en un catálogo y las consulta desde DuckDB.
  • El capítulo 9 mueve una tabla entre formatos y comprueba la copia.
  • El capítulo 10 elige un formato según lo que admiten tus herramientas.

Conoces SQL, Python y Parquet, y sabes qué es una partición. Este capítulo no los explica.

Las filas de la tabla de pageviews cubren seis horas del 3 de junio de 2024, de 00:00 a 05:59 UTC. Proceden de los volcados de pageviews de Wikimedia, que el proyecto Wikimedia publica bajo CC0. El libro conserva los 500 títulos más vistos en cada hora, en las ediciones en inglés, alemán, francés y japonés, tras eliminar las páginas especiales. El día está fijado y es pasado, así que los volcados de ese día no cambiarán, y los datos del repositorio no quedarán desactualizados. El README de la carpeta de datos indica la fuente, la licencia y el recorte exacto.

Los datos son deliberadamente desordenados. Los títulos contienen guiones bajos y escrituras no latinas, y los recuentos están muy sesgados: el título principal de la hora 00 tiene muchas más visitas que el título en la posición 500. Cada fila del recorte tiene un response_bytes de 0, como registra el README de la carpeta de datos. El libro conserva la columna tal como la entrega el recorte, así que es 0 en todas las filas. Estos valores permanecen en los datos, porque un formato de tabla debe almacenarlos tal cual.

Lo que un formato de tabla añade a los archivos

Último cambio en la edición 2026.11.10

Cualquier cosa que lea la carpeta ve todos los archivos que hay en ella. Un formato de tabla responde a eso con metadatos. Los metadatos de una tabla son un registro del esquema de la tabla y de los archivos de datos que forman la tabla en cada momento de su historia. Un cambio en la tabla es un commit, que escribe nuevos metadatos en un solo paso. Ese paso es el único cambio que mueve la tabla de un estado al siguiente.

Cada formato de tabla tiene sus propios metadatos y sus propias palabras para estas ideas. Iceberg llama al estado posterior a un commit un snapshot. Delta Lake numera sus versiones. DuckLake registra sus snapshots en un archivo de catálogo. Este capítulo escribe los tres, para que veas las mismas filas en cada uno.

Dónde están los metadatos también difiere. Una tabla de Iceberg conserva un archivo de metadatos que nombra su snapshot actual. En la versión 2 del formato, que escribe pyiceberg, cada snapshot apunta a una manifest list, la manifest list nombra los manifests, y cada manifest nombra los archivos de datos junto con sus estadísticas. La Iceberg spec define cada una de esas capas. Una tabla de Delta Lake conserva un registro ordenado de archivos de commit en una carpeta _delta_log junto a sus datos, como describe el Delta Lake protocol. Una tabla de DuckLake conserva sus metadatos en el catalog file que adjuntas, y escribe sus archivos de datos en una carpeta junto a ese archivo.

Se insertan seis horas una a una en los tres formatos; después se lee de nuevo cada tabla y se comparan sus totales.

rough-lakehouse.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Load six hours into Iceberg, Delta Lake and DuckLake, then read each table back.The rows and views lines print each format's totals, and the assert after them checks that the three agree.The titles at the end come from the Iceberg table alone."""from lib.lakehouse import (    format_report,    load_three_formats,    new_warehouse,    print_rows,    safe_error,    sql_rows,    scan_arrow,)# page_title breaks ties in views, so titles with equal views always print in the same order.TOP_THREE = """    SELECT sum(views) AS views, page_title FROM pageviews    GROUP BY page_title ORDER BY views DESC, page_title LIMIT 3"""def main():    try:        with new_warehouse() as wh:            # range(6) is hours 0 to 5, the six hours of the cut, one commit per hour in each format.            iceberg, delta_path, lake = load_three_formats(wh, range(6))            report = format_report(wh, iceberg, delta_path, lake)            for name, (rows, views, files) in report.items():                print(f"{name} rows: {rows}")                print(f"{name} views: {views}")                print(f"{name} data files: {files}")            # A set of (rows, views) pairs has one entry only when all three formats agree.            totals = {(rows, views) for rows, views, _ in report.values()}            assert len(totals) == 1, "the three formats disagree on rows or views"            print("top three page titles over six hours (views, page_title):")            # pageviews names the Arrow table for the SQL; keep_order prints the rows in the SQL's order, not re-sorted.            print_rows(sql_rows(wh.con, TOP_THREE, keep_order=True, pageviews=scan_arrow(iceberg)), keep_order=True)    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython rough-lakehouse.py
iceberg 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

Los tres formatos informan el mismo número de filas y el mismo total de vistas, y cada uno escribió un archivo de datos por hora:

  • Iceberg: 2999 filas, 1807299 vistas, 6 archivos de datos.
  • Delta Lake: 2999 filas, 1807299 vistas, 6 archivos de datos.
  • DuckLake: 2999 filas, 1807299 vistas, 6 archivos de datos.

Un assert detiene la ejecución si los totales de filas o de vistas de los tres formatos llegan a diferir. La salida enumera entonces los tres títulos más vistos durante las seis horas, leídos solo de la tabla de Iceberg: Main_Page, メインページ y Wikipedia:Hauptseite, las páginas principales de las ediciones en inglés, japonés y alemán.

La salida no incluye IDs de snapshot, números de versión ni nombres de archivo, porque cambian de una ejecución a otra; en su lugar, añadir cada hora muestra cómo se etiquetan los snapshots.

DuckLake requiere un paso adicional en tu propia máquina. Ejecuta INSTALL ducklake y después LOAD ducklake en DuckDB. Las ejecuciones del libro cargan en su lugar una copia de la extensión oficial y firmada ducklake de DuckDB desde un archivo del repositorio, de modo que funcionan sin conexión a la red. DuckLake también tiene un valor predeterminado de inlining que importa para el recuento de archivos: por defecto, guarda en su catálogo las inserciones de 10 filas o menos en lugar de en un archivo Parquet. La página de data inlining de DuckLake indica el valor predeterminado: "Data inlining is enabled by default with a row limit of 10." El ejemplo fija el límite en 0, de modo que cada inserción escribe un archivo, y los recuentos de archivos significan lo mismo en todos los capítulos.

Un bucle de carga, tres estilos de confirmación

Último cambio en la edición 2026.11.7

La función auxiliar load_three_formats() en examples/lib/lakehouse.py contiene el bucle que llama rough-lakehouse. El bucle escribe cada hora en las tres tablas, y cada línea que escribe es una confirmación (commit) en un formato distinto:

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 devuelve una hora del corte como una tabla de Arrow, con las mismas cinco columnas en cada formato. La adición de Iceberg crea una instantánea. La adición de Delta crea una nueva versión, y crea la tabla en la primera llamada, cuando la ruta todavía no contiene una. La inserción de DuckLake escribe un archivo Parquet y registra una instantánea en el archivo de catálogo. Las tres llamadas difieren, pero la tabla que escribe cada una es la misma: las seis horas de filas. El propio bucle no comprueba nada. Ejecuta las seis cargas en orden y se detiene si alguna de ellas lanza un error. Las comprobaciones llegan después de que las seis horas estén cargadas, cuando rough-lakehouse lee los totales de cada formato y los compara.

Un commit nombra los archivos de la tabla

Último cambio en la edición 2026.11.10

La especificación de Apache Iceberg define un snapshot como el estado de una tabla en un momento dado, que un lector usa para encontrar todos los archivos de datos de la tabla. Por tanto, un snapshot hace dos cosas. Nombra los archivos de datos que la tabla contiene en ese punto, y registra la operación que lo produjo. La especificación enumera los tipos de operación. Para un append, la operación es append, que la especificación de Iceberg describe como "Solo se añadieron archivos de datos y no se quitó ningún archivo."

La tabla pageviews lo hace concreto. Cada hora que cargas se convierte en un archivo de datos, y cada carga es un commit. Tras el primer commit, la tabla contiene solo el archivo de la hora 00. Tras el segundo commit, contiene dos archivos, y así sucesivamente. Un archivo de datos nunca se edita. Un commit añade archivos, y el nuevo snapshot nombra los archivos que la tabla contiene después del commit.

El recuento de archivos de datos de la tabla procede de su snapshot, no de su carpeta. rough-lakehouse muestra el número de archivos de datos que informa cada formato para la tabla. Ese número es lo que la tabla dice que contiene, y un listado de la carpeta puede mostrar otro número.

Regla práctica: Pregunta a la tabla qué contiene, a través de su snapshot actual, y no listando su carpeta. La carpeta contiene todos los archivos que un escritor colocó allí, y el snapshot indica cuáles de esos archivos lee la tabla.

Por qué se enseña cada formato a través de una biblioteca de Python

Último cambio en la edición 2026.11.10

El ejemplo rough-lakehouse escribía cada formato con una biblioteca distinta, y esta sección explica por qué. El libro escribe Apache Iceberg y Delta Lake con las bibliotecas de Python que vas a usar para ejecutarlos: pyiceberg, en la versión 0.12.0, y deltalake, en la versión 1.6.6. DuckDB, en la versión 2.0.0, lee lo que esas bibliotecas escriben. Lee una tabla Iceberg como una tabla Arrow a partir de un scan, y lee una tabla Delta como una tabla Arrow a partir de una consulta que ejecuta deltalake. DuckLake es la excepción. DuckDB ejecuta DuckLake por sí mismo, a través de su extensión ducklake, y adjunta el archivo de catálogo de la tabla. El libro no usa las extensiones iceberg o delta de DuckDB, y ningún ejemplo las ejecuta.

Formato Escrito por Leído por DuckDB a través de
Apache Iceberg pyiceberg, 0.12.0 Tabla Arrow a partir de un scan
Delta Lake deltalake, 1.6.6 Tabla Arrow a partir de QueryBuilder de deltalake
DuckLake Extensión ducklake de DuckDB, en DuckDB 2.0.0 ATTACH a un archivo de catálogo

La elección tiene un coste. Si ejecutas Iceberg con Spark o Trino, encontrarás allí más del formato, con funciones que este libro no cubre. El libro nombra esos lugares y no enseña esos motores. La ganancia son menos piezas móviles: la biblioteca propia de cada formato lo escribe, y DuckDB lee el resultado. La versión de cada biblioteca está fijada, y los capítulos nombran la versión fijada de la biblioteca, no la versión de la especificación del formato. Las versiones fijadas están en examples/requirements.txt, que enumera cada paquete con una versión exacta por línea. Si instalas desde ese archivo, obtienes las bibliotecas con las que se ejecutó este capítulo. Usa la versión de Python que indica examples/.python-version, porque pip no la selecciona.

Regla práctica: Escribe y lee cada tabla con la biblioteca cuya versión fijas, y di qué versión usan tus lecturas. Recurre a la extensión propia de un motor solo cuando hayas medido lo que la biblioteca no puede hacer por ti.

Cargar tres horas en una tabla

Último cambio en la edición 2026.11.7

El ejemplo rough-lakehouse mostró el ciclo completo, así que esta sección lo explica con más calma en una sola tabla. Cargar un lote lleva dos pasos: crear la tabla y confirmar cada lote en ella. La tabla pageviews se carga primero con las horas 00, 01 y 02, de modo que cada hora es una confirmación. Ese mismo ejemplo carga después las horas 03 a 05 de la misma forma, una vez cargadas las tres primeras. El resto de esta sección trabaja solo con la tabla Iceberg, porque es la que más tiene que mostrar.

Crear la tabla en un catálogo

Último cambio en la edición 2026.11.10

Una tabla de Iceberg necesita un catálogo, que es el registro que asocia un nombre de tabla con los metadatos actuales de la tabla. Una tabla de Delta Lake se encuentra por su ruta, sin catálogo, y una tabla de DuckLake vive en su archivo de catálogo. El libro usa el catálogo SQL de pyiceberg sobre SQLite para la tabla de Iceberg. El catálogo es un solo archivo, y los archivos de datos de la tabla van en una carpeta de almacenamiento junto a él. El catálogo guarda punteros y metadatos, no filas. Dentro del archivo de catálogo, un nombre de tabla como wiki.pageviews_hourly se asocia con la ubicación del archivo de metadatos actual de la tabla. Cada confirmación escribe un nuevo archivo de metadatos y mueve esa asociación, de modo que quien pida la tabla al catálogo obtiene los metadatos que escribió la confirmación más reciente. El auxiliar new_warehouse() en examples/lib/lakehouse.py crea un catálogo y un almacenamiento temporales para cada ejecución, y los elimina cuando la ejecución termina. Como SQLite es un archivo y no necesita servidor, todo el catálogo funciona en un portátil con la red desconectada.

La tabla tiene cinco columnas, y su esquema indica qué contiene cada una:

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),
)

La columna hour_utc contiene una marca de tiempo sin zona horaria, en UTC, y los dos conteos son enteros de 64 bits. El auxiliar create_iceberg_table() crea la tabla en el catálogo, sin particiones. El capítulo 4 le añade una especificación de partición.

Regla práctica: Escribe el esquema en código, con el tipo que realmente tiene cada columna, antes de la primera confirmación. Así los tipos se deciden a propósito, y no según el primer lote que llegue.

Añade cada hora como una confirmación

Último cambio en la edición 2026.11.10

Una adición (append) es una sola confirmación. A continuación, pyiceberg crea la tabla, añade las horas 00, 01 y 02 en orden y luego enumera las instantáneas (snapshots) en orden de confirmación, con su operación y las filas que añadió cada confirmación:

append-hours.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Create the Iceberg table, append hours 00 to 02 as three commits, then repeat hour 00.The 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."""from lib.lakehouse import (    create_iceberg_table,    iceberg_file_count,    new_warehouse,    read_cut_hour,    safe_error,    scan_arrow,    snapshot_labels,)def main():    try:        with new_warehouse() as wh:            table = create_iceberg_table(wh)            for hour in range(3):                table.append(read_cut_hour(hour))            # pyiceberg returns the snapshots in commit order, which the labels below depend on.            snapshots = table.snapshots()            # Snapshot IDs change from run to run, so each one prints as its position in commit order.            labels = snapshot_labels([snap.snapshot_id for snap in snapshots])            for snap in snapshots:                label = labels[snap.snapshot_id]                print(f"{label} operation: {snap.summary.operation.value}")                # The commit's own summary holds the rows it added, not a count of the whole table.                print(f"{label} rows added: {snap.summary['added-records']}")            print(f"rows in table: {scan_arrow(table).num_rows}")            # Counted from the current snapshot, not from the folder.            print(f"data files: {iceberg_file_count(table)}")            # Hour 00 again.            table.append(read_cut_hour(0))            repeat = table.current_snapshot()            print(f"repeat of hour 00 operation: {repeat.summary.operation.value}")            print(f"repeat of hour 00 rows added: {repeat.summary['added-records']}")            print(f"rows in table after the repeat: {scan_arrow(table).num_rows}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython append-hours.py
snapshot 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

La hora 00 tiene una fila menos: la primera confirmación añade 499 filas, y las dos siguientes añaden 500 cada una. La comprobación de privacidad eliminó una fila de la hora 00, como explica el README de datos. Las tres confirmaciones dejan 1499 filas en 3 archivos de datos, uno por cada confirmación.

Cada confirmación también escribe un resumen, y pyiceberg devuelve las instantáneas en orden de confirmación, que es de donde salen la operación y las filas añadidas. La operación de cada confirmación es append, la operación de adición que define la especificación. El resumen de la instantánea es lo que la tabla registra sobre sus propias confirmaciones, así que es el primer lugar al que debes mirar cuando un recuento sea incorrecto.

Las etiquetas impresas, snapshot 1, snapshot 2 y snapshot 3, sustituyen a los ID de las instantáneas. Un ID de instantánea de Iceberg es un entero largo que la especificación exige que sea único, y pyiceberg lo elige en el momento en que se realiza la confirmación, por lo que cambia de una ejecución a otra. Asignar cada ID a su posición en el orden de confirmación mantiene la salida impresa igual en cada ejecución.

Regla práctica: Haz una confirmación por cada lote que puedas nombrar, y compara las filas que añadió cada confirmación con el recuento que esperas según su origen antes de hacer la siguiente. Un recuento incorrecto es más sencillo de rastrear mientras su confirmación sea la más reciente, y más difícil cuando hay más confirmaciones encima de ella.

Consulta la tabla con DuckDB

Último cambio en la edición 2026.11.10

Con la tabla ya creada, quieres hacerle preguntas. DuckDB ejecuta SQL, pero una tabla Iceberg no es una tabla de DuckDB. El libro lee la instantánea actual de la tabla como una tabla Arrow, que pyiceberg devuelve desde un escaneo, y registra esa tabla Arrow en DuckDB con el nombre pageviews. Después DuckDB ejecuta SQL común sobre ella, sin ninguna extensión de Iceberg. Un escaneo es la lectura que la tabla hace de una instantánea. Enumera los archivos de datos que la instantánea nombra, los lee y entrega solo las filas que contienen. DuckDB ve exactamente esas filas y nada más que la instantánea no nombre.

El siguiente ejemplo añade las horas 00 a 02 a una tabla nueva y le hace dos preguntas: cuáles son los cinco títulos con más visualizaciones en la hora 00, y cuántas visualizaciones suman en total las tres horas. Comprueba ese total frente a la suma que da el propio escaneo.

scan-into-duckdb.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Read the current Iceberg snapshot into DuckDB and check the totals.The point that DuckDB received every row rests on the two total views lines, which the assert compares."""from lib.lakehouse import (    create_iceberg_table,    new_warehouse,    print_rows,    read_cut_hour,    safe_error,    scan_arrow,    sql_rows,)def main():    try:        with new_warehouse() as wh:            table = create_iceberg_table(wh)            for hour in range(3):                table.append(read_cut_hour(hour))            # The current snapshot's rows as one Arrow table, sorted by every column.            arrow = scan_arrow(table)            top = sql_rows(                wh.con,                # hour_utc is UTC, so this is hour 00 of 3 June 2024; page_title breaks ties in views.                """                SELECT views, page_title FROM pageviews                WHERE hour_utc = TIMESTAMP '2024-06-03 00:00:00'                ORDER BY views DESC, page_title LIMIT 5                """,                # keep_order returns the rows in the order the SQL sorted them, not sorted again.                keep_order=True,                pageviews=arrow,            )            print("top five pages for hour 00 (views, page_title):")            print_rows(top, keep_order=True)            # One row with one column: the sum.            duckdb_total = sql_rows(wh.con, "SELECT sum(views) FROM pageviews", pageviews=arrow)[0][0]            # A second route to the same total, summed in Python from the scan's own rows.            pyiceberg_total = sum(arrow["views"].to_pylist())            print(f"total views in DuckDB: {duckdb_total}")            print(f"total views in the scan: {pyiceberg_total}")            assert duckdb_total == pyiceberg_total, "DuckDB and the scan disagree on the total"    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython scan-into-duckdb.py
top 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

La lista contiene los cinco títulos con más visualizaciones en la hora 00, del mayor al menor, usando el título como criterio de desempate, y cada línea muestra las visualizaciones, un tabulador y luego el título. El total en DuckDB es de 899451 visualizaciones, igual que la suma propia del escaneo, que es 899451, y una aserción detiene la ejecución si alguna vez ambos valores difieren.

Un total que coincide con la suma del escaneo demuestra que DuckDB recibió todas las filas que devolvió el escaneo. No comprueba las filas en sí ni la consulta de los cinco primeros. Comprobar un total cuesta una línea, así que conviene ejecutarlo después de cada cambio en una consulta. Comprobar las filas frente a su origen es tarea de los capítulos siguientes, que comparan cada cambio con los datos de los que procede.

Regla práctica: Lee una tabla Iceberg en DuckDB como la tabla Arrow de un escaneo, y compara un total con la suma propia del escaneo, para confirmar que DuckDB recibió todas las filas. Después comprueba el resultado de cada consulta frente a una fuente con la que puedas compararlo.

Qué sale mal en producción

Último cambio en la edición 2026.11.10

El camino del primer capítulo es corto, y oculta cuatro problemas que encontrarás en producción.

Una carga repetida añade las mismas filas otra vez. Una adición (append) agrega los archivos de datos que recibe y no elimina ninguno, como dice la definición de la operación en la especificación. Nada en la tabla impide que una segunda copia de la hora 00 entre. Una confirmación (commit) que lleva una segunda copia de la hora 00 se ve igual que cualquier otra. append-hours lo muestra: la operación de la confirmación repetida es append, añade 499 filas, el mismo número que la primera copia, y la tabla tiene entonces 1998 filas, sin ningún error. El único registro de que la carga debía ejecutarse una vez es el recuento que anotaste antes de ejecutarla. El capítulo 5 muestra cómo corregir las filas que se cargaron mal.

La carpeta contiene más que la tabla. Un recuento de los archivos de la carpeta del almacén responde a una pregunta distinta del recuento de los archivos de la tabla. La carpeta contiene todos los archivos que un escritor dejó allí, y una instantánea (snapshot) define lo que contiene la tabla. Una herramienta que cuenta los archivos Parquet de la carpeta informa un número que la tabla nunca prometió. Los capítulos 6 y 7 tratan de archivos que la tabla ya no alcanza.

Los identificadores de instantánea, las versiones y los números de instantánea son tipos de número distintos. Los identificadores de Iceberg son valores de 64 bits. Delta Lake cuenta las versiones desde 0 en orden de confirmación. DuckLake también numera sus instantáneas, y registra una instantánea cada vez que crea un esquema o una tabla, además de cada vez que inserta filas. Un script que guarda el número de un formato y lo lee como la versión de otro formato lee un estado equivocado.

Una inserción pequeña en DuckLake no escribe ningún archivo. De forma predeterminada, DuckLake guarda en su catálogo las inserciones de 10 filas o menos, así que un recuento de cero archivos después de una inserción pequeña es el resultado esperado, no un fallo. Los ejemplos de DuckLake de este libro fijan el límite de filas en 0, salvo ducklake-inlined-delete en el capítulo 10, que conserva el valor predeterminado para mostrar que un borrado pequeño no escribe un archivo de borrado. Si copias una inserción en tu propio catálogo, conoce antes ese valor predeterminado.

Regla práctica: Anota el número de filas que debe añadir cada confirmación, junto a la carga que la produce, y compara ese número con el resumen de la confirmación después de cada carga. La tabla no detecta una carga repetida. La comprobación que sí lo detecta es un recuento que anotaste de antemano.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.8
  • Tres ejemplos en este capítulo. rough-lakehouse calcula el resultado completo en tres formatos, de modo que cada capítulo posterior cambia una parte de un resultado que ya has ejecutado. Los otros dos, append-hours y scan-into-duckdb, construyen la tabla Iceberg una confirmación a la vez y la leen en DuckDB.
  • Primero las horas 00 a 02, luego 03 a 05. Los ejemplos de Iceberg aportan tres horas y el ejemplo rough aporta seis. Solo rough-lakehouse totaliza las seis horas.
  • Tablas sin particionar. El capítulo 1 crea tablas sin especificación de partición. El capítulo 4 cambia la partición. El paquete pyiceberg-core está fijado junto a pyiceberg, porque las transformaciones por día y por hora del capítulo 4 lo necesitan.
  • Inserción en línea (inlining) desactivada en los ejemplos. Los ejemplos de DuckLake establecen DATA_INLINING_ROW_LIMIT en 0, de modo que cada inserción escribe un archivo Parquet y los conteos de archivos significan lo mismo dondequiera que el libro los imprima. El ducklake-inlined-delete del capítulo 10 conserva el valor predeterminado, porque su objetivo es que un borrado pequeño no escriba un archivo de borrado.
  • Las tablas Delta se leen solo mediante QueryBuilder de deltalake. El auxiliar de lectura en examples/lib/lakehouse.py sigue esa ruta, y cada capítulo posterior que lee una tabla Delta usa el mismo auxiliar.
  • Datos reales, no un sustituto. Cada ejemplo de este capítulo lee el recorte de los seis volcados públicos que describe el README de datos. El libro no incluye datos generados para este capítulo.
  • SQLite para el catálogo de Iceberg. Un archivo SQLite no necesita servidor, así que los ejemplos de Iceberg se ejecutan en un portátil sin red. Esas ejecuciones también desactivan la descarga automática de extensiones de DuckDB, de modo que una ejecución que necesite la red falla en lugar de descargar nada.
  • Las etiquetas sustituyen a los IDs. Las etiquetas snapshot 1, snapshot 2 y similares que se imprimen sustituyen a los identificadores de instantánea, de modo que la salida no cambia de una ejecución a otra.

Este capítulo, en esta edición

Edición 2026.11.10Ejemplos verificados el 20 de nov de 2026Superan la prueba 3 de 3 ejemplos ejemplos de este capítulo

Traducido del libro en inglés, edición 2026.11.10.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 1 de 10: Construye una primera tabla, de principio a fin

  1. Lo que un formato de tabla añade a los archivos
  2. Un bucle de carga, tres estilos de confirmación
  3. Un commit nombra los archivos de la tabla
  4. Por qué se enseña cada formato a través de una biblioteca de Python
  5. Cargar tres horas en una tabla
  6. Crear la tabla en un catálogo
  7. Añade cada hora como una confirmación
  8. Consulta la tabla con DuckDB
  9. Qué sale mal en producción
  10. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos