Lee una tabla tal como estaba en una instantánea anterior

Unos 18 minutos de lectura, con 3 ejemplos en 7 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

Este capítulo te enseña a leer una tabla tal como estaba después de un commit anterior, en cada uno de los tres formatos: listar sus commits, leer uno por el número que usa su formato, y comparar esos números entre formatos sin confundirlos.

Supón que un total del panel para wiki.pageviews_hourly, que suma views por hora, cambia después de que llegue la tercera hora, y su responsable hace dos preguntas. ¿Cuál era el total antes de ese commit? ¿Cambió la tabla, o solo la consulta? Responderlas requiere el historial de la tabla y una forma de leer un estado antiguo de la tabla. La tabla tiene cinco columnas: hour_utc, domain_code, page_title, views y response_bytes. Cada ejemplo de este capítulo crea su propia copia de la tabla, como lo hace el capítulo 1: crea la tabla y añade las horas 00, 01 y 02 como tres commits. La hora 00 tiene 499 filas, y cada una de las otras dos horas tiene 500.

Cada commit es una snapshot

Último cambio en la edición 2026.11.10

Capítulo 1 registra las tres horas como tres commits. Cada commit deja una snapshot tras de sí, y es lo que lees más adelante.

Un commit cambia los metadatos de la tabla en un solo paso atómico, de modo que un lector ve la tabla antes del commit o después de él, nunca en un estado intermedio. En Apache Iceberg, cada commit crea una snapshot. La especificación de Iceberg define una snapshot como "el estado de una tabla en algún momento", usada para acceder al conjunto completo de archivos de datos de la tabla, y describe cada cambio como un intercambio atómico de archivos de metadatos. Una snapshot tiene un ID único, una hora de creación y un resumen. El resumen de una snapshot tiene un campo obligatorio, operation, que es uno de append, replace, overwrite o delete. Un append añade archivos de datos y no elimina ninguno. Un commit posterior añade una snapshot y deja intactas las anteriores, lo que permite al responsable del panel preguntar por un estado que ya no es el más reciente.

Antes de cualquier escaneo, lee el historial: el ejemplo enumera los tres commits en orden, cada uno con su operación y las filas que añadió, primero para Iceberg y después para Delta Lake.

snapshot-history.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Commit three hours to an Iceberg table and a Delta Lake table, then list each commit with its operation and rows added.The prose's point that all three Iceberg commits are appends rests on the operation lines for the snapshots."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import ICEBERG_ID, PAGEVIEWS_SCHEMA, new_warehouse, read_cut_hour, snapshot_labelsdef main():    with new_warehouse() as wh:        table = wh.catalog.create_table(ICEBERG_ID, schema=PAGEVIEWS_SCHEMA)        delta_path = str(wh.root / "delta" / "pageviews_hourly")        for hour in range(3):                       # hours 00, 01 and 02: one commit to each table per hour            batch = read_cut_hour(hour)            table.append(batch)            write_deltalake(delta_path, batch, mode="append")        # sequence_number counts commits, so sorting by it puts the labels in commit order.        snapshots = sorted(table.snapshots(), key=lambda snapshot: snapshot.sequence_number)        labels = snapshot_labels([snapshot.snapshot_id for snapshot in snapshots])        for snapshot in snapshots:            label = labels[snapshot.snapshot_id]            operation = snapshot.summary.operation.value            print(f"{label} operation: {operation}")            # added-records counts only this commit's rows, not the table's running total.            print(f"{label} rows added: {snapshot.summary['added-records']}")        # Sorted by version, so the lines follow Delta's own numbering whatever order history returns.        history = sorted(DeltaTable(delta_path).history(), key=lambda entry: entry["version"])        for entry in history:            rows = entry["operationMetrics"]["num_added_rows"]      # Delta's count of the rows this WRITE added            print(f"version {entry['version']} operation: {entry['operation']}")            print(f"version {entry['version']} rows added: {rows}")if __name__ == "__main__":    main()
Salidapython snapshot-history.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
version 0 operation: WRITE
version 0 rows added: 499
version 1 operation: WRITE
version 1 rows added: 500
version 2 operation: WRITE
version 2 rows added: 500

Los tres commits usaron append, así que ninguno reescribió ni eliminó un archivo. La hora 00 añadió 499 filas, una menos que las otras porque el corte de datos eliminó una fila de ella, como explica el README de datos. Las horas 01 y 02 añadieron cada una 500. La pregunta del responsable empieza aquí: la tabla tiene tres estados entre los que elegir, y el historial los nombra.

pyiceberg asigna a cada snapshot un ID entero largo. No imprimimos esos IDs. En su lugar, snapshot_labels asigna, en orden de commit, las etiquetas "snapshot 1", "snapshot 2" y "snapshot 3", y la salida imprime solo las etiquetas.

Las mismas tres horas se escribieron en una tabla de Delta Lake mediante write_deltalake, una escritura por hora. Delta Lake llama versión a cada commit, y su historial enumera la operación y las filas escritas para cada una. Delta numera sus versiones desde 0, así que la primera escritura es la versión 0. El libro imprime los números propios de Delta, así que el ejemplo ordena el historial por versión e imprime "version 0", "version 1" y "version 2". Cada escritura de Delta es una operación WRITE que añade las mismas filas que la snapshot de Iceberg correspondiente: 499 filas para la versión 0, y luego 500 y 500.

El historial responde a la primera mitad de la pregunta del responsable. Dice qué commit cambió la tabla y cuántas filas añadió ese commit. Un append solo añade filas, así que no puede cambiar un total de horas que ya están en la tabla. Si el total de una hora cambió, el historial debe nombrar como causa un overwrite, un delete o un replace, y entonces lees las snapshots a ambos lados de ese cambio. El historial no dice qué hizo una consulta, y esa parte de la pregunta requiere las lecturas de la siguiente sección.

Regla práctica: Antes de leer o cambiar una tabla, enumera su historial en el formato que utilices, y usa esa lista como única fuente de números de commit. Ordena la lista por orden de commit, etiqueta las snapshots de Iceberg con snapshot_labels antes de imprimirlas, e imprime las versiones de Delta tal como Delta las numera. Lee la operación junto con cada commit. Un append solo añade archivos, así que no puede haber eliminado filas, mientras que un overwrite o un delete sí puede hacerlo.

Qué apunta una instantánea

Último cambio en la edición 2026.11.10

Una instantánea no contiene filas. Apunta a los archivos que las contienen. En las versiones de formato 2 y 3, una instantánea registra una lista de manifiestos, y ahí es donde se encuentran sus archivos. La definición de la sección anterior convierte a la instantánea en la vía de acceso al conjunto completo de archivos de datos, así que un lector parte de la instantánea y la sigue hasta los archivos.

Eso hace de una instantánea un conjunto de punteros, y la consecuencia importa para cada sección que sigue. Una instantánea se puede leer solo mientras existan los archivos que nombra. Por tanto, viajar en el tiempo no es una copia de seguridad. Solo lee los archivos que la tabla todavía conserva, y la tabla conserva un archivo solo mientras alguna instantánea lo nombre. El capítulo 7 elimina las instantáneas antiguas y los archivos que solo ellas nombraban, lo que pone fin a los viajes en el tiempo a esos estados.

La operación de la confirmación muestra qué compartición es posible. La especificación define append como la operación en la que "solo se añadieron archivos de datos y no se eliminó ningún archivo". Así, la instantánea 3 vuelve a nombrar los archivos de la hora 00, porque la tercera confirmación no los reescribió. Varias instantáneas pueden nombrar el mismo archivo, y una confirmación cuesta solo los archivos que escribió más los punteros hacia ellos.

Los recuentos de filas en Instantáneas en pyiceberg muestran los punteros en acción. La instantánea 2 devuelve 999 filas, que son las 499 filas de la hora 00 más las 500 de la hora 01, y nada de la hora 02. La instantánea 3 lee las tres horas. Cada instantánea lee las filas que sus confirmaciones habían hecho visibles hasta ese momento, y no más. La diferencia entre los dos recuentos son las filas que añadió la tercera confirmación, 500 en total, de modo que el historial y las lecturas coinciden.

Regla práctica: Considera que una instantánea antigua se puede leer solo mientras existan sus archivos. Antes de eliminar archivos, decide qué instantáneas conservas y caduca primero las demás. Una consulta sobre una instantánea antigua que falla tras una limpieza indica un archivo desaparecido. La solución es encontrar ese archivo en una copia de la tabla, no leer otra instantánea en su lugar.

Leer una instantánea anterior

Leer una instantánea anterior significa nombrarla al escanear la tabla. Cada formato tiene su propia manera de nombrarla. Iceberg recibe un ID de instantánea. DuckLake recibe un número de instantánea en AT (VERSION => n). Delta Lake recibe un número de versión. Los tres números no cuentan las mismas cosas.

La primera pregunta del propietario es cuál era el total antes de que se registrara la tercera hora. La respuesta es el estado después del segundo commit, la instantánea 2.

Snapshots en pyiceberg

Último cambio en la edición 2026.11.7

En pyiceberg 0.12.0, scan(snapshot_id=...) lee la tabla tal como estaba en esa snapshot, y un scan sin ID de snapshot lee la snapshot actual. Dos scans por ID responden la primera pregunta del propietario a partir del propio historial de la tabla, y el ejemplo además lee la tabla actual y la compara con la snapshot 3.

read-as-of-snapshot.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Read an Iceberg table as of snapshot 2 and snapshot 3, by ID, then compare the current table with snapshot 3.The prose's answer to the owner's first question rests on the snapshot 2 views line, and the failed read on the last line."""from lib.lakehouse import (    ICEBERG_ID, PAGEVIEWS_SCHEMA, new_warehouse, read_cut_hour, safe_error, scan_arrow, snapshot_labels, sql_rows,)def main():    with new_warehouse() as wh:        table = wh.catalog.create_table(ICEBERG_ID, schema=PAGEVIEWS_SCHEMA)        for hour in range(3):            table.append(read_cut_hour(hour))        snapshots = sorted(table.snapshots(), key=lambda snapshot: snapshot.sequence_number)        ids = [snapshot.snapshot_id for snapshot in snapshots]        labels = snapshot_labels(ids)        # ids[1] is snapshot 2 and ids[2] is snapshot 3: the list is in commit order, counted from 0.        for snapshot_id in (ids[1], ids[2]):            arrow = scan_arrow(table, snapshot_id=snapshot_id)            # The scan is registered in DuckDB as t, so the SQL can count and sum its rows.            rows, views = sql_rows(wh.con, "SELECT count(*), sum(views) FROM t", t=arrow)[0]            print(f"{labels[snapshot_id]} rows: {rows}")            print(f"{labels[snapshot_id]} views: {views}")        current = scan_arrow(table)                  # no snapshot_id, so this reads the current snapshot        last = scan_arrow(table, snapshot_id=ids[2])        print(f"current rows: {current.num_rows}")        # equals compares every row and column, in order; scan_arrow sorts both tables by every column, so row order cannot differ.        assert current.equals(last)        try:            scan_arrow(table, snapshot_id=2)         # 2 is the label's number, not an ID, so this fails on purpose        except Exception as exc:            print(f"read by label: {safe_error(exc, wh)}")if __name__ == "__main__":    main()
Salidapython read-as-of-snapshot.py
snapshot 2 rows: 999
snapshot 2 views: 580963
snapshot 3 rows: 1499
snapshot 3 views: 899451
current rows: 1499
read by label: ValueError: Snapshot not found: 2

La snapshot 2 responde la primera pregunta del propietario. Antes del tercer commit, la tabla contenía 580963 vistas en total, y la snapshot 3, después de él, contiene 899451. Leer la tabla sin ID da las mismas filas que la snapshot 3, y la comprobación compara las filas en sí, no solo su cantidad.

La columna de vistas responde la segunda pregunta del propietario. La snapshot 3 tiene más vistas que la snapshot 2, y la diferencia son las vistas que añadió la hora 02. El total cambió porque el tercer commit añadió filas, no porque cambiara la consulta del panel. Dos lecturas de la misma tabla lo muestran sin ningún cambio en la consulta.

Un lector que tenga en mente la etiqueta "snapshot 2" podría pasar el número 2 como ID. Esa llamada falla, y el fallo es el resultado seguro:

ValueError: Snapshot not found: 2

El error nombra el número que recibió, que no es un ID de snapshot, y nada en la tabla cambió. El lector sabe entonces que debe buscar el ID. El propio ejemplo busca cada ID en table.snapshots() y nunca lo calcula a partir de un conteo. Las etiquetas existen para la prosa, y los IDs para el scan.

Regla práctica: Obtén los IDs de snapshot de table.snapshots() y pasa el ID que buscaste, nunca el número de una etiqueta. Asocia los IDs con las etiquetas en orden de commit antes de imprimir nada. Cuando la pregunta sea el estado después de un commit, encuentra primero ese commit en el historial y lee la snapshot que creó.

Lee una confirmación por su número en cada formato

Último cambio en la edición 2026.11.10

Delta Lake lee una versión anterior con DeltaTable(path, version=n). La versión es la posición de la confirmación en el historial de la tabla, contada desde 0, de modo que la versión 0 es la primera escritura. El auxiliar read_delta recibe la ruta y una versión opcional, y devuelve las filas como una tabla Arrow ordenada. En este libro, cada lectura de Delta pasa por QueryBuilder de deltalake, que el auxiliar llama por ti. La sección de decisiones explica el motivo.

DuckLake guarda una instantánea por cada cambio en el catálogo, y el cambio incluye crear un esquema y crear una tabla. DuckLake también numera sus instantáneas desde 0, así que la primera inserción en un catálogo nuevo no es la número 1. La página de viaje en el tiempo de DuckLake muestra la cláusula para leer una, SELECT * FROM tbl AT (VERSION => 3);, y dice que la instantánea a consultar puede indicarse por marca de tiempo o "explícitamente mediante un identificador de instantánea". El libro usa el identificador. Tú lees el número desde ducklake_snapshots, no desde tu propio recuento de inserciones.

El ejemplo de tres versiones hace que los números diverjan mientras los recuentos de filas coinciden: escribe las mismas tres horas en una tabla Delta y en una tabla DuckLake, con una confirmación por hora en cada formato. Lee cada confirmación por su número, imprime ambos recuentos de filas, cuenta las instantáneas de DuckLake anteriores a la primera inserción y muestra un fallo.

three-version-numbers.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Commit the same three hours to Delta Lake and DuckLake, then read each commit back by its own number.The prose's point that each hour gives the same row count in both formats rests on the paired row-count lines."""from deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, TABLE, attach_ducklake, connect_ducklake, new_warehouse,                           read_cut_hour, read_delta, safe_error, snapshot_labels, sql_rows)LAKE_TABLE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"CATALOG_SNAPSHOTS = f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}')"# Fetches snapshot_time, which turns into Python values through pytz; the pins do not install pytz, so this fails on purpose.TIME_COLUMN = f"SELECT snapshot_time FROM ducklake_snapshots('{DUCKLAKE_ALIAS}')"def main():    with new_warehouse() as wh:        delta_path = str(wh.root / "delta" / TABLE)        connect_ducklake(wh.con)        attach_ducklake(wh.con, DUCKLAKE_ALIAS, wh.root)        wh.con.execute(f"CREATE SCHEMA {DUCKLAKE_ALIAS}.{NAMESPACE}")        # A zero-row slice of hour 00: it gives the table its columns and types, and no rows.        sql_rows(wh.con, f"CREATE TABLE {LAKE_TABLE} AS SELECT * FROM empty", empty=read_cut_hour(0).slice(0, 0))        for hour in range(3):                        # hours 00, 01 and 02, one commit to each table per hour            batch = read_cut_hour(hour)            write_deltalake(delta_path, batch, mode="append")            sql_rows(wh.con, f"INSERT INTO {LAKE_TABLE} SELECT * FROM batch", batch=batch)        # Keeps only the snapshots that inserted rows, so the schema and table creations are left out.        inserts = sorted(row[0] for row in sql_rows(wh.con, CATALOG_SNAPSHOTS + " WHERE map_contains(changes, 'tables_inserted_into')"))        # Snapshot IDs count up with each change, so these are the snapshots made before the first insert.        before = sql_rows(wh.con, CATALOG_SNAPSHOTS + f" WHERE snapshot_id < {inserts[0]}")        print(f"snapshots before the first insert: {len(before)}")        # Labels count every DuckLake snapshot from 1, setup snapshots included, not DuckLake's own numbers.        lake_labels = snapshot_labels(sorted(row[0] for row in sql_rows(wh.con, CATALOG_SNAPSHOTS)))        delta_versions = list(range(DeltaTable(delta_path).version() + 1))     # Delta versions run from 0 to the latest        # zip pairs each hour's Delta version with its DuckLake insert, in order; strict fails if the counts differ.        for hour, (delta_version, snapshot) in enumerate(zip(delta_versions, inserts, strict=True)):            # DuckLake reads by the snapshot ID from ducklake_snapshots, never by counting the inserts.            lake = sql_rows(wh.con, f"SELECT count(*) FROM {LAKE_TABLE} AT (VERSION => {snapshot})")[0][0]            rows = len(read_delta(delta_path, version=delta_version))     # read_delta goes through QueryBuilder, because to_pyarrow_table() aborted at exit in some test runs at these pins.            print(f"after hour {hour:02d}, Delta version {delta_version} rows: {rows}")            print(f"after hour {hour:02d}, DuckLake {lake_labels[snapshot]} rows: {lake}")        try:            wh.con.execute(TIME_COLUMN).fetchall()        except Exception as exc:            print(f"select time: {safe_error(exc, wh)}")if __name__ == "__main__":    main()
Salidapython three-version-numbers.py
snapshots before the first insert: 3
after hour 00, Delta version 0 rows: 499
after hour 00, DuckLake snapshot 4 rows: 499
after hour 01, Delta version 1 rows: 999
after hour 01, DuckLake snapshot 5 rows: 999
after hour 02, Delta version 2 rows: 1499
after hour 02, DuckLake snapshot 6 rows: 1499
select time: InvalidInputException: Invalid Input Error: Required module 'pytz' failed to import, due to the following Python exception:
ModuleNotFoundError: No module named 'pytz'

La primera inserción es "instantánea 4", no "instantánea 1", porque el catálogo de DuckLake ya contiene 3 instantáneas antes de ella: el esquema predeterminado que DuckLake crea al conectarse, el esquema wiki y la tabla. Este libro etiqueta las instantáneas de DuckLake desde 1, incluida la configuración inicial, así que "instantánea 4" es el número propio de DuckLake, 3, más uno. Un lector que cuente las inserciones desde 1 obtendrá la etiqueta equivocada.

Tras cada hora, los dos formatos tienen el mismo número de filas, aunque numeren sus confirmaciones de forma distinta. La hora es la clave que los alinea, porque los formatos no comparten numeración. Tras la hora 02, que es la tabla completa, la versión 2 de Delta tiene 1499 filas y la instantánea 6 de DuckLake tiene 1499, y las horas anteriores coinciden de la misma manera.

La tabla siguiente sitúa los tres números uno junto a otro.

Formato Número que identifica una confirmación Qué cambios cuenta Cómo lo lees
Iceberg ID de instantánea, un entero largo Cada confirmación en la tabla scan(snapshot_id=...)
Delta Lake Versión, contada desde 0 Cada confirmación en la tabla DeltaTable(path, version=n)
DuckLake Número de instantánea, contado desde 0 (la etiqueta del libro es uno más) Todo cambio en el catálogo, incluida la creación de esquemas y tablas AT (VERSION => n)

Regla práctica: Compara los formatos por la hora que cargó cada confirmación, nunca por el número bruto. Imprime las instantáneas de Iceberg y DuckLake con sus etiquetas, imprime las versiones de Delta tal como Delta las numera, y vincula los recuentos a ellas. Lee Delta solo a través de read_delta, y lee DuckLake solo con números que provengan de ducklake_snapshots. Si una tabla en un formato recibe confirmaciones que el otro no recibe, las etiquetas dejan de alinearse, y el historial de cada formato se convierte en el único registro fiable.

Qué sale mal en producción

Último cambio en la edición 2026.11.7

Los fallos de este capítulo son los que un lector probablemente encontrará primero. Los dos primeros aparecen en los ejemplos de este capítulo. El tercero y el cuarto se argumentan a partir de la documentación y de las reglas del libro, y el quinto y el sexto se apoyan en el capítulo 1 y en el capítulo 7. El primero es el número que no es un ID. Un escaneo fallido es un fallo seguro, porque el error indica qué estaba mal. Los fallos peores vienen de leer un número que es válido en un formato y significa otra cosa en otro, o de una consulta que se ejecuta y devuelve algo inesperado. El ejemplo de lectura por snapshot muestra el primer tipo: la suposición del ID falla de forma ruidosa, y el texto del error nombra el valor que se pasó.

Obtener una columna de tiempo falla por otra razón, un módulo que falta. El ejemplo de las tres versiones incluye una selección de snapshot_time desde ducklake_snapshots, y la llamada falla:

InvalidInputException: Invalid Input Error: Required module 'pytz' failed to import, due to the following Python exception:

El mensaje indica que falta el módulo pytz. El entorno fijado no lo instala. El cliente de Python de DuckDB necesita pytz para convertir una columna TIMESTAMPTZ, como snapshot_time, en valores de Python. El ejemplo de las tres versiones evita el problema seleccionando solo snapshot_id y filtrando por changes, de modo que nunca obtiene snapshot_time. Para leer la hora de todos modos, conviértela con snapshot_time::VARCHAR. Omite la columna o conviértela; preferimos no añadir un paquete que el libro no fija.

Leer por marca de tiempo es la tercera trampa. DuckLake acepta una marca de tiempo en AT (TIMESTAMP => ...), y los snapshots de Iceberg tienen una hora de creación. Una marca de tiempo elige un estado según el reloj, y el reloj es la hora en que se ejecutó cada commit. En producción, eso es una buena forma de pedir "la tabla tal como estaba a las nueve de la mañana". Un ejemplo tendría que tomar una hora de reloj de la ejecución, que cambia en cada ejecución, por eso el libro usa IDs y números de versión. Elige la forma de marca de tiempo cuando necesites un punto en la hora de reloj y tengas un registro de cuándo se ejecutó cada commit. Elige la forma numérica cuando necesites la misma respuesta siempre.

Los números divergen entre formatos. Dos formatos pueden contener la misma tabla, y la misma etiqueta puede entonces nombrar estados distintos. El ejemplo del libro confirma las mismas horas en el mismo orden, así que las etiquetas coinciden. Una tabla de producción que recibe una reparación en un formato y no en el otro no coincidirá. Incluso con historiales idénticos, los números brutos no se alinean entre formatos, porque los números de snapshot de DuckLake también cuentan la creación de esquemas y tablas. Un panel que lea "versión 4" de ambos formatos mostrará totales distintos, así que compara los commits por sus etiquetas. La comprobación consiste en comparar los recuentos de filas de la etiqueta en ambos formatos antes de confiar en cualquiera de los dos números. El ejemplo de las tres versiones hace eso.

Un recuento de archivos también puede salir bajo, porque DuckLake puede conservar una inserción pequeña en el catálogo en lugar de escribir un archivo Parquet, con el valor predeterminado que nombra el capítulo 1. El primer lote horario del ejemplo, por sí solo, contiene 499 filas, muy por encima de ese límite, así que con ese valor predeterminado cada una de sus inserciones se escribe como un archivo. Un recuento de archivos de datos solo tiene sentido una vez que conoces el límite de filas.

El fallo sobre el que más advierte este capítulo llega después, en una lectura tras una limpieza. Lo que apunta un snapshot explica la razón: el error aparece solo cuando un lector pide un snapshot cuyos archivos ya no existen. Nada falla en la propia limpieza. El capítulo 7 muestra qué archivos elimina una limpieza.

Regla práctica: Lee el texto del error antes de cambiar la consulta. Nombra el valor, el módulo o la versión que falló, y esa es la ruta más rápida hacia la solución. Compara cada recuento en un formato con la misma etiqueta en el otro formato antes de confiar en cualquiera de los dos. Mantén legible el snapshot que necesita tu pregunta hasta que la pregunta quede respondida, y expira solo los snapshots que ya ninguna pregunta necesita. Registra la etiqueta y el nombre del formato junto con cada número que informes, para que quien lea el informe pueda reproducirlo.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.7
  • Etiquetas, no IDs. Las líneas impresas llevan etiquetas como "snapshot 2" para Iceberg y DuckLake, contadas desde 1 sobre todos los snapshots que registra el formato. En DuckLake eso incluye los tres snapshots de configuración, así que el número propio de DuckLake es uno menos. Los IDs de Iceberg y los números de snapshot de DuckLake nunca llegan a la salida. Delta imprime sus números de versión, que empiezan en 0 y son los números que tú pasas a DeltaTable. Puedes volver a ejecutar un ejemplo y comparar su texto línea por línea, y un diff muestra un cambio en los datos o en la biblioteca, nunca un cambio en un ID aleatorio. Las etiquetas se asignan en orden de commit, así que conservan su significado aunque una biblioteca devuelva el historial en otro orden.
  • IDs y números de versión, no marcas de tiempo. Una lectura por marca de tiempo depende del reloj y del momento en que se ejecutó cada commit. Leemos por ID o número, de modo que el lector obtenga las mismas filas del mismo commit cada vez que se ejecute el ejemplo. Si en producción necesitas la hora real, usa la forma con marca de tiempo y guardar un registro de cuándo se ejecutó cada commit.
  • Delta lee solo a través de read_delta. El helper lee a través de QueryBuilder de deltalake. Con estas versiones fijadas, la ruta to_pyarrow_table() aborta al salir en algunas ejecuciones, como mide el capítulo 8. Corregimos la ruta de lectura en lugar de esquivar el aborto, así que ningún ejemplo llama a os._exit ni oculta el código de salida.
  • DuckLake solo a través de los helpers. Cada ejecución de DuckLake carga DuckLake con connect_ducklake y lo adjunta con attach_ducklake. Nunca activamos allow_unsigned_extensions. Las ejecuciones del libro cargan la extensión oficial y firmada de DuckLake de DuckDB desde el archivo incluido en el repositorio, después de que el helper compruebe ambos hashes contra SOURCE.toml, así que una ejecución sin conexión no necesita descargar nada. Solo en tu propia máquina, cuando ese archivo incluido no está presente, connect_ducklake ejecuta INSTALL ducklake.
  • Consultas acotadas sobre el catálogo. Las consultas sobre ducklake_snapshots nombran sus columnas y omiten snapshot_time, porque esa columna necesita un módulo que las versiones fijadas no instalan. Preferimos nombrar las columnas que necesitamos antes que añadir una dependencia que las versiones fijadas no registran.
  • Delta conserva sus propios números. Delta imprime su versión real, contada desde 0. Cada etiqueta indica solo qué commit es dentro de su propia tabla, y nunca que dos formatos contienen el mismo estado. Comparar el número de filas de cada etiqueta es lo que lo comprueba.
  • Fallos impresos, no lanzados. Dos ejemplos terminan con una llamada que falla a propósito, y cada uno captura el error y lo imprime. El fallo se muestra porque es algo con lo que te encontrarás, y el texto del error se imprime completo para que puedas compararlo con tu propia salida.
  • Leer el historial antes que el estado. El código lista los commits de cada formato, y solo después lee un commit por su número. Quien lee el capítulo ve la operación y el número de filas de cada commit antes de cualquier escaneo, así que un recuento que parezca incorrecto puede verificarse contra el commit que lo produjo.

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 2 de 10: Lee una tabla tal como estaba en una instantánea anterior

  1. Cada commit es una snapshot
  2. Qué apunta una instantánea
  3. Leer una instantánea anterior
  4. Snapshots en pyiceberg
  5. Lee una confirmación por su número en cada formato
  6. Qué sale mal en producción
  7. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos