Expirar snapshots y eliminar archivos no referenciados

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

Después de este capítulo podrás expirar snapshots antiguos en cada uno de los tres formatos, eliminar los archivos de datos que solo esos snapshots seguían listando, y demostrar que una lectura de un snapshot expirado falla.

La compactación deja el mismo tipo de archivo antiguo: las reescrituras dejaron en disco los archivos reemplazados, porque los snapshots anteriores todavía los listan. Este capítulo expira los snapshots antiguos de wiki.pageviews_hourly, y después elimina los archivos que ningún snapshot lista ya. Todos los ejemplos de aquí usan la corrección de la hora 02 del capítulo de correcciones, escrita como una sobrescritura de esa hora en lugar del upsert de su sección posterior, porque la sobrescritura deja exactamente un archivo antiguo por formato. Esos archivos antiguos permanecen hasta que sus snapshots se expiren y sus archivos se eliminen. Ambos pasos se ejecutan en cada formato, y cada paso se comprueba con un recuento en lugar de con un listado en el que tengas que confiar.

Las instantáneas mantienen vivos los archivos

Último cambio en la edición 2026.11.10

Cada instantánea registra qué archivos de datos forman la tabla en ese commit. Lo que apunta una instantánea explica cómo cada formato almacena esa lista. El punto de este capítulo es que un commit que reemplaza filas no elimina los archivos que reemplaza. Escribe archivos para las filas de reemplazo, y las instantáneas anteriores al commit siguen listando los archivos antiguos, de modo que el viaje en el tiempo sigue funcionando. Un archivo de datos se convierte en un huérfano solo cuando ninguna instantánea que conservas lo lista.

Eliminar un archivo requiere dos pasos en todos los formatos: primero la expiración y luego la limpieza. La página de mantenimiento de Iceberg indica el mismo orden: la expiración elimina las instantáneas de los metadatos, de modo que el viaje en el tiempo no puede alcanzarlas, y "los archivos de datos no se eliminan hasta que ya no los referencie una instantánea que pueda usarse para viajar en el tiempo o para revertir" (Apache Iceberg, mantenimiento). Después de la expiración, la limpieza elimina los archivos que ninguna instantánea restante lista.

wiki.pageviews_hourly recibe tres adiciones por hora, y luego la hora 02 se corrige mediante una sobrescritura de esa hora. Cada adición escribe un archivo. La sobrescritura escribe un archivo con las filas corregidas de la hora 02, y elimina el archivo antiguo de la instantánea actual. La instantánea que añadió el archivo antiguo sigue listándolo. Mientras esa instantánea no expire, el archivo antiguo no puede eliminarse sin romper el viaje en el tiempo hacia ella. Actualizar una hora corregida muestra la otra forma de escribir la misma corrección, y deja tras de sí el mismo tipo de archivo antiguo.

Cada formato tiene su propia llamada de expiración y su propia llamada de limpieza. La tabla las enumera, y el resto del capítulo sigue el mismo orden para cada formato.

Formato Llamada de expiración ¿La expiración elimina archivos? Llamada de limpieza
Iceberg (pyiceberg) expire_snapshots().by_ids(...) No Ninguna en la biblioteca: cuenta y elimina los archivos por tu cuenta
Delta Lake (deltalake) Retención de versiones en vacuum Sí, mediante vacuum vacuum
DuckLake ducklake_expire_snapshots No ducklake_cleanup_old_files, y después ducklake_delete_orphaned_files

Regla práctica: Decide qué instantáneas o versiones podría necesitar aún un lector, y expira las demás antes de eliminar cualquier archivo. Nunca elimines un archivo que una instantánea que conservas todavía liste, y verifica esa afirmación con un recuento antes de borrar.

Expirar snapshots con pyiceberg

Último cambio en la edición 2026.11.7

En pyiceberg 0.12.0, table.maintenance.expire_snapshots() recibe IDs de snapshot, con by_ids para una lista o by_id para uno, o una marca de tiempo older_than. No tiene ningún argumento que conserve los últimos N snapshots. Este capítulo elige los IDs a partir del orden de confirmación, tal como lo hace el caso: los tres appends por hora son los primeros tres snapshots. Los IDs en sí son números aleatorios de 64 bits, así que el ejemplo imprime las etiquetas "snapshot 1", "snapshot 2" y así sucesivamente, en el mismo orden.

La sobrescritura añade dos snapshots, no uno. pyiceberg escribe un snapshot de borrado que elimina el archivo antiguo, y después un snapshot de append que añade las filas corregidas. El snapshot 4 es el borrado y el snapshot 5 es el append. Expirar los tres appends, por tanto, deja la sobrescritura en su lugar, y ese es el estado que comprueba el ejemplo.

La llamada de expiración no borra archivos de datos, así que el ejemplo los cuenta por su cuenta, antes y después: los archivos distintos que listan los snapshots, y los archivos en disco que ninguno de ellos lista. Fíjate en el último recuento, que es donde aparece el archivo reemplazado:

expire-iceberg-snapshots.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Expire the three append snapshots by ID, then count what the snapshots still reference. The point rests on theline that counts unreferenced data files on disk: expiry removes metadata, and the file the overwrite replaced stays."""from lib.lakehouse import (    ICEBERG_ID,    create_iceberg_table,    hour_corrections,    hour_filter,    new_warehouse,    orphan_data_files,    read_cut_hour,    scan_arrow,    snapshot_labels,)def referenced_files(table):    """Distinct data files that some retained snapshot lists. Count them; do not print them."""    # all_files() can list one file from several manifests, so the set counts each file once    return len(set(table.inspect.all_files()["file_path"].to_pylist()))with new_warehouse() as wh:    table = create_iceberg_table(wh)    for hour in (0, 1, 2):        table.append(read_cut_hour(hour))    # hour_filter(2) matches only hour 02's rows, so the overwrite replaces that hour and leaves hours 00 and 01 alone    table.overwrite(hour_corrections(read_cut_hour(2)), overwrite_filter=hour_filter(2))    ids = [snapshot.snapshot_id for snapshot in table.metadata.snapshots]  # metadata lists snapshots in commit order    labels = snapshot_labels(ids)    print("snapshots before expiry:", len(ids))    print("data files referenced before expiry:", referenced_files(table))    print("data files in the current snapshot:", len(table.inspect.files()))  # files() reads the current snapshot only    expired = ids[:3]  # the three hourly appends, by commit order    table.maintenance.expire_snapshots().by_ids(expired).commit()    table = wh.catalog.load_table(ICEBERG_ID)    print("remaining snapshots:", ", ".join(labels[s.snapshot_id] for s in table.metadata.snapshots))    print("data files referenced after expiry:", referenced_files(table))    # files under the table location that no remaining snapshot lists; a file a writer has not committed counts too    print("unreferenced data files left on disk:", len(orphan_data_files(table)))    print("rows in the current snapshot:", scan_arrow(table).num_rows)    try:        scan_arrow(table, snapshot_id=expired[-1])    except ValueError as exc:        print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
Salidapython expire-iceberg-snapshots.py
snapshots before expiry: 5
data files referenced before expiry: 4
data files in the current snapshot: 3
remaining snapshots: snapshot 4, snapshot 5
data files referenced after expiry: 3
unreferenced data files left on disk: 1
rows in the current snapshot: 1499
read snapshot 3: ValueError

Antes de la expiración, la tabla tiene 5 snapshots, y 4 archivos de datos son listados por al menos uno de ellos. El snapshot actual lista solo 3 de esos archivos. El que queda es el antiguo archivo de la hora 02, que el snapshot 3 todavía lista. Leer los recuentos de esta manera muestra lo que hizo la sobrescritura: la tabla actual está completa, y el historial conserva el archivo que la sobrescritura reemplazó.

Luego el ejemplo expira los snapshots 1 a 3, los tres appends. Los snapshots que quedan son snapshot 4, snapshot 5, el borrado de la sobrescritura y su append. Después, 3 archivos de datos aparecen listados, y el antiguo archivo de la hora 02 ya no lo lista ningún snapshot. Sigue en disco: el ejemplo informa de 1 archivo sin referencia. La tabla actual todavía devuelve 1499 filas, así que la expiración no cambió ningún dato que vea un lector de la tabla actual.

La última lectura falla. Un escaneo del snapshot 3 después de la expiración lanza ValueError, que la salida muestra como "read snapshot 3: ValueError". Un lector que fijó el snapshot 3 antes de la expiración recibe un error, no las filas antiguas. El error, Snapshot not found, nombra el ID del snapshot, pero no dice que una expiración eliminó el snapshot. Tus propios registros deben anotar qué expiración se ejecutó y qué snapshot usó el informe.

Regla práctica: Expira los snapshots de Iceberg por ID, elegidos a partir del orden de confirmación, y cuenta los archivos que lista cada snapshot restante antes y después. No esperes recuperar espacio en disco con la expiración. pyiceberg elimina solo los metadatos, así que los archivos que deja atrás permanecen en disco hasta que los elimines tú mismo.

Encontrar archivos huérfanos después de la expiración

Último cambio en la edición 2026.11.8

Un archivo que ninguna instantánea enumera es un huérfano. Spark y Java ofrecen una acción deleteOrphanFiles: enumera la ubicación de la tabla, compara los archivos con los metadatos y elimina la diferencia, y su intervalo de antigüedad predeterminado es de 3 días (Apache Iceberg, mantenimiento). La página de la API de pyiceberg no enumera ningún paso para archivos huérfanos, y el paquete 0.12.0 tampoco tiene ninguno. Sus métodos de mantenimiento expiran instantáneas (API de PyIceberg).

Un auxiliar del módulo compartido del libro, examples/lib/lakehouse.py, orphan_data_files, realiza la comparación a mano. Enumera los archivos Parquet bajo la ubicación de la tabla, resta los archivos que enumera cualquier instantánea restante y devuelve el resto. La salida muestra solo el recuento, porque los nombres de archivo contienen UUID. Ese recuento es la línea que muestra que el archivo expirado sigue en el disco.

Un listado no puede distinguir un huérfano de un archivo que un escritor ha escrito y aún no ha confirmado. La confirmación vincula el archivo a la tabla, y hasta entonces el archivo parece sin referencia. Por eso importan las protecciones por antigüedad. ducklake_delete_orphaned_files de DuckLake conserva los archivos recientes de forma predeterminada, y la acción de Spark toma un intervalo de antigüedad por el mismo motivo. pyiceberg no tiene intervalo, así que esa comprobación corre por tu cuenta. Eliminar un huérfano es una decisión aparte, y corresponde hacerla después de que los escritores que podrían confirmarlo se hayan detenido.

Regla práctica: Cuenta los huérfanos listando, y elimínalos solo después de confirmar que ningún escritor puede aún confirmarlos y que ningún lector sigue usando una instantánea que los enumere. En pyiceberg, ninguna parte de la biblioteca hace esa comprobación por ti.

Limpiar una tabla con deltalake

Último cambio en la edición 2026.11.10

Delta Lake no elimina un archivo cuando una confirmación lo reemplaza. Una confirmación de Delta que reemplaza un archivo añade al registro una acción remove, una lápida que indica que el archivo ya no forma parte de la tabla, y el archivo permanece en disco. El protocolo establece que dichos archivos "pueden eliminarse de forma diferida mediante el comando vacuum después de un período de retención especificado por el usuario (por defecto 7 días)" (Delta transaction log protocol, v4.4.1). La salida de esta sección usa los números de versión propios de Delta, que empiezan en 0.

Vacuum elimina los archivos cuyas lápidas son más antiguas que la retención. Hasta entonces, se puede leer cada versión, porque todos los archivos que lista todavía existen. La página de utilidades de Delta describe el costo: "La posibilidad de viajar en el tiempo a una versión más antigua que el período de retención se pierde después de ejecutar vacuum" (Delta Lake, VACUUM).

El caso tiene tres inserciones, que forman las versiones 0 a 2, y después la corrección de la hora 02. La corrección es un borrado de esa hora, que es la versión 3, seguido de una inserción de las filas corregidas, que es la versión 4. La versión 2 todavía lista el archivo antiguo de la hora 02, y la versión 3 no. Todavía no se ha eliminado nada, y ese es el estado desde el que comienza la siguiente sección.

La retención por defecto en deltalake es de 168 horas, siete días. Una tabla puede definir la suya en la propiedad delta.deletedFileRetentionDuration, y vacuum usa esa propiedad cuando no pasas retention_hours. Esa propiedad es la configuración de producción. La biblioteca rechaza una retención más corta que el valor de la propiedad a menos que desactives enforce_retention_duration. Una retención más larga no necesita ninguna marca. La retención que elijas es una promesa sobre hasta dónde llega el historial. Cada lector que abre una versión anterior depende de ella, y la siguiente sección muestra el rechazo y por qué la ejecución de enseñanza de este capítulo desactiva la comprobación.

Regla práctica: Mantén la retención por defecto de vacuum, o define una más larga en delta.deletedFileRetentionDuration, de modo que cada versión que un lector pueda pedir siga siendo legible durante ese tiempo después de dejar de ser la actual. Usa una más corta solo después de haber revisado la lectura más larga y la escritura más larga de tu sistema, y solo desactivando enforce_retention_duration como una decisión deliberada y registrada.

Primero, una simulación

Último cambio en la edición 2026.11.7

Una simulación lista los archivos que un vacuum real eliminaría y no elimina ninguno. Ejecútala antes de cada vacuum, y compara su conteo con el historial de la tabla. El caso consta de tres añadidos, un borrado en la versión 3 y un añadido en la versión 4. Una lista corta puede comprobarse a mano: aquí, cada archivo de la lista es uno que un borrado eliminó, y el que importa es el borrado de la versión 3. Dos simulaciones sobre ese historial preguntan a vacuum, con dos retenciones, qué eliminaría:

vacuum-delta-dry-run.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Show that vacuum's default retention keeps a file that a delete has just removed, and that a read of an older versionfails once a teaching-only run removes that file. The point rests on the default-retention line and the read of version 2."""import pyarrow as pafrom deltalake import DeltaTable, write_deltalakefrom deltalake.exceptions import DeltaErrorfrom lib.lakehouse import new_warehouse, read_cut_hour, read_delta, hour_correctionswith new_warehouse() as wh:    path = str(wh.root / "delta" / "pageviews_hourly")    for hour in (0, 1, 2):        write_deltalake(path, read_cut_hour(hour), mode="append")    dt = DeltaTable(path)    dt.delete("hour_utc = '2024-06-03T02:00:00'")  # hour 02, matched by its exact timestamp    # hour_corrections halves the views of some page titles in hour 02, so this append holds the corrected rows    write_deltalake(path, hour_corrections(read_cut_hour(2)), mode="append")    dt = DeltaTable(path)    print("current version:", dt.version())    # the delete was seconds ago, so the default retention still keeps its file    print("default retention, dry run lists:", len(dt.vacuum(dry_run=True)))    try:        dt.vacuum(retention_hours=0, dry_run=True)  # a retention below the table's minimum: refused without the flag    except DeltaError as exc:        print("zero retention without the flag:", type(exc).__name__)    # Teaching run only: a zero-hour retention removes files at once. Production keeps the 168-hour default.    print("zero retention, dry run lists:", len(dt.vacuum(retention_hours=0, dry_run=True, enforce_retention_duration=False)))    print("zero retention, removed:", len(dt.vacuum(retention_hours=0, dry_run=False, enforce_retention_duration=False)))    print("rows in version 0:", read_delta(path, version=0).num_rows)  # version 0 reads files the vacuum left alone    try:        read_delta(path, version=2)  # version 2 still lists the hour-02 file that the vacuum removed    except pa.ArrowInvalid as exc:        print("read version 2:", type(exc).__name__)
Salidapython vacuum-delta-dry-run.py
current version: 4
default retention, dry run lists: 0
zero retention without the flag: DeltaError
zero retention, dry run lists: 1
zero retention, removed: 1
rows in version 0: 499
read version 2: ArrowInvalid

La tabla está en la versión 4. Con la retención predeterminada, la simulación lista 0 archivos. El archivo que eliminó la versión 3 es demasiado reciente para aparecer en la lista, y vacuum lo conserva.

La siguiente llamada fija la retención en cero, y deltalake la rechaza con DeltaError. El propio mensaje de la biblioteca indica que la retención mínima es de 168 horas, de modo que la comprobación protege el valor predeterminado.

La ejecución didáctica desactiva esa comprobación con enforce_retention_duration=False. El código la marca como solo para enseñanza, y la producción no la usa. Con la comprobación desactivada, la simulación lista 1 archivo, y el vacuum real elimina 1 archivo, el antiguo archivo de la hora 02. Una retención de cero es el ajuste correcto para una demostración, porque elimina el archivo de inmediato. En producción es incorrecto: cualquier lector que haya empezado antes del vacuum, o que haya fijado una versión anterior, pierde los archivos que lee en mitad de una consulta. Una retención corta también elimina los archivos de un escritor que ha escrito pero aún no ha confirmado. La página de utilidades de Delta advierte que "las tablas pueden corromperse cuando VACUUM elimina archivos que aún no han sido confirmados" (Delta Lake, VACUUM). El daño afecta a la tabla, no solo a una lectura.

La lectura del final muestra lo que costó el vacuum. La versión 0 todavía se lee, con 499 filas, porque cada archivo que enumera sigue existiendo. La versión 2 falla con ArrowInvalid, mostrado como "read version 2: ArrowInvalid". Esa clase es la que el motor de consultas lanza cuando falla una lectura de Parquet, y el mensaje indica el objeto que falta. La lectura solo muestra la clase. Lee el mensaje completo en tus propios registros antes de concluir que la tabla está dañada: indica qué objeto falta, y por tanto si un vacuum lo eliminó.

Una simulación no es una garantía sobre la ejecución real. Un escritor que confirme cambios entre las dos llamadas modifica la tabla, y la ejecución real trabaja con el estado que encuentre. Trata el conteo de la simulación como una comprobación de lo que esperas, y lee el conteo real junto a él.

Regla práctica: Ejecuta vacuum primero como simulación y lee el conteo. Elimina archivos con una ejecución real solo cuando el conteo coincida con lo que esperabas según el historial de la tabla, y mantén la retención predeterminada salvo que hayas comprobado la lectura más larga de tu sistema.

Expirar y limpiar en DuckLake

Último cambio en la edición 2026.11.7

DuckLake conserva los archivos físicos de una instantánea hasta que esa instantánea expira. La documentación de DuckLake lo expresa así: "Los datos solo pueden eliminarse físicamente de DuckLake expirando las instantáneas que hacen referencia a los datos antiguos" (DuckLake, expirar instantáneas). La misma página indica que la expiración no elimina de inmediato los archivos que deja sin referencia, y la página de limpieza describe la segunda llamada (DuckLake, limpieza de archivos).

Así, el mantenimiento de DuckLake tiene dos pasos, y el ejemplo siguiente ejecuta ambos. ducklake_expire_snapshots toma una lista de números de instantánea en versions, o una marca de tiempo older_than, pero no ambos. ducklake_cleanup_old_files elimina los archivos que la expiración programó. Con older_than, elimina solo los archivos programados antes de un momento dado. Con cleanup_all => true, elimina todos los archivos programados, sin comprobar la antigüedad. Ambos pasos admiten dry_run.

Una tercera llamada, ducklake_delete_orphaned_files, se ocupa de los archivos que ninguna instantánea enumera y que la limpieza nunca programó, como un archivo que un escritor dejó tras una confirmación fallida. Su valor por defecto conserva un archivo que todavía es reciente, porque un escritor podría estar a punto de confirmarlo. Su opción cleanup_all elimina esos archivos sin importar su antigüedad. El capítulo del catálogo muestra qué hace esa opción cuando un segundo catálogo comparte la carpeta de datos.

Adjuntar el catálogo y crear el esquema y la tabla mediante los auxiliares genera tres instantáneas antes de cualquier fila: el adjuntado crea la instantánea 1, y las dos sentencias CREATE crean las instantáneas 2 y 3, numeradas desde 1 con la preparación incluida, como hace el capítulo 2. Después, el auxiliar de carga inserta las horas 00 a 02, elimina la hora 02 e inserta la hora 02 corregida. Eso produce 8 instantáneas, que el ejemplo etiqueta como "instantánea 1" hasta la última. La última es la inserción corregida. La anterior es la eliminación, que quita el archivo antiguo de la hora 02. La inserción previa a esta, la instantánea 6, es la última instantánea que lo enumera.

ducklake-expire-cleanup.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Expire every snapshot before the correction, clean up what expiry released, and run the orphan check as a dry run. Thepoint rests on the cleanup lines and on the orphan line, which shows that the default age check spares the stray copy."""import shutilfrom pathlib import Pathimport duckdbfrom lib.lakehouse import (    DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table,    ducklake_file_count, ducklake_file_paths, load_ducklake_with_correction, new_warehouse,    version_labels,)LAKE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"def listed(con, call):    """Run a DuckLake procedure and return how many rows it lists."""    return con.sql(f"CALL {call}").to_arrow_table().num_rowswith new_warehouse() as wh:    con = connect_ducklake(wh.con)    create_ducklake_table(con, wh.root)    load_ducklake_with_correction(con)  # lib inserts hours 00 to 02, deletes hour 02, then inserts the corrected hour 02    # ORDER BY 1 sorts by snapshot_id, which grows with each commit, so the labels number the snapshots in commit order    ids = [r[0] for r in con.execute(f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}') ORDER BY 1").fetchall()]    labels = version_labels(ids, word="snapshot")    print("snapshots before expiry:", len(ids))    print("data files in the current snapshot:", ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE))    stray = Path(sorted(ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE))[0])  # sorted, so every run copies the same file    shutil.copy(stray, stray.with_name("stray.parquet"))  # written, but no snapshot lists it    expired = ids[:-1]  # all but the last snapshot, which is the corrected insert and stays    # versions takes DuckLake's snapshot numbers, not the labels    expire = f"ducklake_expire_snapshots('{DUCKLAKE_ALIAS}', versions => {expired}"    print("expiry dry run lists:", listed(con, f"{expire}, dry_run => true)"))    con.execute(f"CALL {expire})")    print("remaining snapshots:", labels[ids[-1]])    # no age check, so this is safe only because one catalog owns the folder and no reader is running    cleanup = f"ducklake_cleanup_old_files('{DUCKLAKE_ALIAS}', cleanup_all => true"    print("cleanup dry run lists:", listed(con, f"{cleanup}, dry_run => true)"))    print("cleanup removed:", listed(con, f"{cleanup})"))    # no cleanup_all, so the default age check spares the stray copy, which was written seconds ago    orphans = f"ducklake_delete_orphaned_files('{DUCKLAKE_ALIAS}', dry_run => true)"    print("orphans listed without cleanup_all:", listed(con, orphans))    print("rows in the current snapshot:", con.sql(f"SELECT count(*) FROM {LAKE}").fetchall()[0][0])    try:        # the newest expired snapshot, the delete; reading it now fails        con.sql(f"SELECT count(*) FROM {LAKE} AT (VERSION => {expired[-1]})").fetchall()    except duckdb.InvalidInputException as exc:        print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
Salidapython ducklake-expire-cleanup.py
snapshots before expiry: 8
data files in the current snapshot: 3
expiry dry run lists: 7
remaining snapshots: snapshot 8
cleanup dry run lists: 1
cleanup removed: 1
orphans listed without cleanup_all: 0
rows in the current snapshot: 1499
read snapshot 7: InvalidInputException

La instantánea actual enumera 3 archivos de datos, y uno de ellos se copia con otro nombre en la misma carpeta, para simular un archivo que un escritor ha escrito pero no confirmado, como describe Buscar archivos huérfanos. Luego, los pasos se ejecutan en orden.

La simulación de expiración lista 7 instantáneas, es decir, todas excepto la inserción corregida. Como esa inserción permanece, el estado actual de la tabla no cambia. La expiración real deja snapshot 8. El archivo antiguo de la hora 02 se libera en este paso, porque la instantánea 6, la última que lo enumeraba, expira.

La simulación de limpieza lista 1 archivo, el archivo antiguo de la hora 02. El DELETE afectó a todas las filas de ese archivo, y ningún archivo de eliminación está programado junto con él, así que el archivo antiguo es el único que queda por quitar. La limpieza real elimina 1 archivo.

La comprobación de huérfanos enumera 0 huérfanos. La copia extraviada sigue en la carpeta, porque la comprobación de antigüedad por defecto la conservó: el archivo tiene solo unos segundos. La tabla todavía devuelve 1499 filas.

Por último, la lectura de la eliminación, la instantánea 7, falla: "read snapshot 7: InvalidInputException". La clase es la que DuckLake lanza para una versión que ya no tiene.

cleanup_all => true aparece aquí porque hay un único catálogo y ningún lector. En producción se usa older_than en su lugar, con una antigüedad mayor que la lectura más larga, para que la limpieza elimine solo los archivos que llevan programados el tiempo suficiente.

Regla práctica: Expira primero las instantáneas de DuckLake y, después, ejecuta cada llamada de limpieza primero como simulación y luego de verdad, en ese orden. Conserva la comprobación de huérfanos por defecto. Usa cleanup_all solo cuando un catálogo sea el único propietario de la carpeta de datos y ningún lector siga usando los archivos que se eliminan, y usa older_than en los demás casos.

Qué sale mal en producción

Último cambio en la edición 2026.11.7

Eliminar un archivo que un lector todavía usa. Una consulta que empezó antes de una limpieza o de un vacuum lee un archivo que después desaparece, y la lectura falla a mitad de camino. Lo verás como un error de lectura que nombra un objeto inexistente, en un trabajo que se ejecutó durante una ventana de mantenimiento. Programa el mantenimiento fuera de las lecturas largas y mantén una retención mayor que la de la lectura más larga. Una retención corta también puede eliminar un archivo que un escritor ya escribió y todavía no confirmó, lo que corrompe la tabla en lugar de hacer fallar una sola lectura, así que mantén la retención también más larga que la escritura en curso más larga.

Retención más corta que la consulta más larga. El valor por defecto de siete días en Delta Lake es un margen, no una medida. Un panel que lee una versión de hace un mes queda fuera de él. Si un lector necesita ver una versión anterior, la retención tiene que cubrirla, o el lector tiene que copiar primero los datos.

Viaje en el tiempo que falla después del mantenimiento. La instantánea expirada y la versión limpiada fallan con ValueError, ArrowInvalid o InvalidInputException, según el formato. Iceberg lanza ValueError, y Delta lanza ArrowInvalid. DuckLake lanza InvalidInputException. Cualquier trabajo que registre un ID de instantánea o un número de versión para leerlo después falla de la misma manera una vez que esa instantánea expira. Lleva un registro propio de qué instantánea usó cada informe, para que una reconstrucción parta de los datos y no dependa de leer la instantánea antigua.

Una simulación que difiere de la ejecución real. Dos llamadas pueden no coincidir si un escritor confirma entre ellas. El recuento de la simulación es el que esperabas, no el que la ejecución real eliminará. Lee el recuento real junto al de la simulación y detente si difieren en más de lo que puedas explicar.

Una auditoría que necesita una instantánea anterior. Algunos informes deben reproducir una cifra de meses antes. La expiración elimina esa posibilidad para siempre, así que decide la ventana de auditoría antes de expirar, y conserva las instantáneas o los datos copiados que la auditoría necesite. La expiración no sustituye a una copia.

Una limpieza que elimina un archivo que otro catálogo necesita. cleanup_all y la comprobación de huérfanos con cleanup_all eliminan archivos por ruta. Si un segundo catálogo apunta a la misma carpeta de datos, sus archivos vivos parecen huérfanos para el primer catálogo. El capítulo del catálogo muestra ese fallo en un directorio temporal.

Regla práctica: Antes de expirar o limpiar, enumera los lectores, informes y auditorías que puedan abrir una instantánea o versión anterior, y fija la retención para cubrir la más larga de ellas. Ejecuta cada llamada como simulación, compara su recuento con el que esperabas, y ejecuta la llamada real solo cuando ambos coincidan.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.7
  • Las instantáneas de Iceberg se expiran por ID, elegidos a partir del orden de confirmación. El capítulo no expira por antigüedad, de modo que el resultado no depende del reloj de la máquina, y pyiceberg 0.12.0 no tiene un argumento de conservar-últimas-N.
  • pyiceberg no elimina ningún archivo, así que expire-iceberg-snapshots cuenta los archivos alcanzables e inalcanzables y deja la eliminación en manos del lector.
  • La ejecución con retención cero en vacuum-delta-dry-run es solo para enseñanza. Está marcada en el código, y la producción mantiene la retención predeterminada.
  • La expiración y la limpieza de DuckLake son llamadas separadas, y cada una se ejecuta primero como simulacro antes de la llamada real.
  • cleanup_all aparece solo en ejemplos de un solo catálogo. El capítulo sobre catálogos cubre el caso en que elimina archivos activos.
  • Cada ejemplo imprime conteos, etiquetas estables y nombres de clases de error, y no IDs, marcas de tiempo, nombres de archivo ni rutas (capítulo 1 explica el motivo), y cada número del texto proviene de una línea de salida enlazada o de la construcción propia del ejemplo.
  • Cada ejemplo conserva la tabla que construyeron los capítulos anteriores, de modo que cada conteo puede verificarse frente al historial que el lector ya ha visto.
  • Cada ejemplo construye su propio almacén temporal, así que ninguna salida depende de un ejemplo anterior ni de la máquina que lo ejecuta.
  • La copia suelta en ducklake-expire-cleanup representa un archivo que un escritor no ha confirmado, tal como describe Buscar archivos huérfanos. Eso muestra la regla de los huérfanos sin esperar a que un archivo envejezca, porque la ejecución tarda segundos.

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 7 de 10: Expirar snapshots y eliminar archivos no referenciados

  1. Las instantáneas mantienen vivos los archivos
  2. Expirar snapshots con pyiceberg
  3. Encontrar archivos huérfanos después de la expiración
  4. Limpiar una tabla con deltalake
  5. Primero, una simulación
  6. Expirar y limpiar en DuckLake
  7. Qué sale mal en producción
  8. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos