Retención, consentimiento y borrado
Unos 39 minutos de lectura, con 11 ejemplos en 13 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.31. Lee el original
En esta página
- Guarda las reglas de retención en un archivo revisado
- Elimina las filas vencidas con borrados por fila
- Leer el consentimiento donde se ejecuta la consulta
- Planifica un borrado a partir del linaje
- Borra las filas que indica el plan
- Expirar snapshots según la configuración propia de la tabla
- Elimina los archivos que ningún snapshot referencia
- Mantén los valores personales fuera de los manifiestos
- Demuestra el borrado leyendo cada archivo
- Qué sale mal en producción
- Un alumno borrado vuelve
- Otros fallos
- Lo que decidió este capítulo
Al terminar este capítulo podrás mantener las reglas de retención como configuración revisada, hacer que una retirada de consentimiento cambie la siguiente consulta y borrar los datos de una persona de cada tabla a la que llegaron. Aplicarás las reglas sobre una fecha que tú indiques, encontrarás esas tablas a partir del linaje y conservarás solo lo que tu equipo jurídico haya registrado como excepción. También eliminarás lo que un borrado de filas deja en una tabla Iceberg: las instantáneas antiguas, los archivos sin referencia y las estadísticas de columna. Terminarás con un escaneo que lee todos los archivos restantes y muestra que ninguno contiene a la persona.
La plataforma de aprendizaje en línea cuya gobernanza trata este libro ha conservado todo desde su primer registro en enero de 2024 en un único catálogo Iceberg: cada ticket de soporte y cada evento de aprendizaje con la dirección IP desde la que se originó. Nada indica cuánto tiempo debería conservarse cada uno. El estudiante 3590 retira su consentimiento para el correo de marketing y, unas semanas después, pide a la plataforma que borre sus datos. Lo primero debería cambiar lo que ve marketing desde la siguiente consulta. Lo segundo no debería dejar copia del estudiante en ningún sitio: ni en las tablas construidas a partir de las suyas, ni en las versiones antiguas de cada tabla que Iceberg conserva a propósito.
Tres términos nombran los temas del capítulo. Retención es el tiempo que la plataforma conserva cada tipo de dato. Consentimiento es el acuerdo de una persona a un uso concreto de sus datos, como el correo de marketing, que puede retirar. Borrado (erasure) es eliminar los datos de una persona a petición suya. El capítulo añade dos cosas al código compartido del libro: las reglas de retención de la plataforma, en governance/retention.toml, y el módulo lib.retention, que las aplica, planifica y ejecuta un borrado, limpia y comprueba los archivos después, y mantiene el registro de borrados. Usa lib.lineage del capítulo 4 para encontrar adónde fueron los datos de un estudiante, y las clasificaciones de lib.metadata del capítulo 2. Cada ejemplo ejecuta PyIceberg 0.12.0 sobre un catálogo local.
Guarda las reglas de retención en un archivo revisado
Una regla de retención indica cuánto tiempo se conserva un tipo de dato, desde qué fecha empieza a contar el plazo y a qué filas se aplica. El Reglamento General de Protección de Datos (RGPD) de la UE establece el principio como limitación del plazo de conservación: los datos personales deben mantenerse "de forma que se permita identificar a los interesados durante no más tiempo del necesario para los fines del tratamiento" (artículo 5, apartado 1, letra e). Su considerando 39 pide al responsable que fije plazos para la supresión o para una revisión periódica (RGPD). El catálogo de controles de seguridad y privacidad del NIST describe la misma tarea, pidiendo que la información se elimine, destruya o borre una vez vencido su periodo de retención (control SI-12(3)) (NIST SP 800-53 Rev. 5). Los responsables de la plataforma y sus abogados deciden cuánto tiempo es necesario; el código aplica lo que ellos deciden, siempre.
Eso aconseja tratar las reglas como configuración, revisadas igual que las políticas de acceso, y escribir código que las aplique a un día que se le proporciona, no al reloj. Un trabajo que consulta el reloj borra filas distintas según cuándo se ejecute: una prueba no puede fijar su resultado, y volver a ejecutarlo tras un fallo puede borrar más que la ejecución que sustituye.
Las reglas de la plataforma están en governance/retention.toml. Los periodos son decisiones propias de la plataforma para el caso de este libro, no asesoramiento jurídico:
[tables."support.tickets"]
keep_days = 730
counted_from = "opened_at" # tickets record when they were opened, not when they were closed
only_when = { column = "status", equals = "closed" }
[tables."learning.events"]
keep_days = 365
counted_from = "occurred_at"
[tables."billing.payments"]
keep_days = 3650 # a placeholder for the period the platform's legal team sets for payment records
counted_from = "paid_at"
Los tickets cerrados se conservan dos años, los eventos un año y los pagos 3,650 días, un valor provisional en el que se basa el plan de borrado. La regla de tickets debería contar desde el cierre del ticket, pero la tabla solo registra opened_at, así que un ticket abierto hace 25 meses y cerrado la semana pasada se borra de inmediato. La plataforma lo acepta porque añadir una columna closed_at es un cambio del equipo de soporte, no del equipo de la plataforma; hasta que la añadan, la regla se equivoca en el sentido de borrar antes de tiempo. lib.retention.due convierte una regla y un día en un filtro de Iceberg. Contadas desde el "hoy" del libro, 1 de octubre de 2026, y 90 días después, las filas que selecciona cada regla quedan así:
1"""The rows each retention rule makes due on the book's today and 90 days later, counted against the day the job is given.2The `rows due` lines are the counts the prose gives."""3from datetime import timedelta45from lib import retention6from lib.catalog import open_catalog7from lib.platform import TODAY89rules = retention.rules()["tables"]10catalog = open_catalog(sorted(rules))11for name, rule in sorted(rules.items()):12 state = rule.get("only_when")13 print(f"{name}: kept {rule['keep_days']} days from {rule['counted_from']}"14 + (f", once {state['column']} is {state['equals']}" if state else ""))1516# the book's today, then 90 days later: the day is passed in, never read from the clock17for day in (TODAY, TODAY + timedelta(days=90)):18 for name, rule in sorted(rules.items()):19 table = catalog.load_table(name)20 # the earliest date kept: keep_days before the day21 print(f"{name} on {day}, kept from:", retention.cutoff(rule, day))22 print(f"{name} on {day}, rows due:", f"{retention.count(table, retention.due(rule, day)):,}")23 print(f"{name} on {day}, rows in the table:", f"{retention.count(table):,}")
python retention-rules-due.pybilling.payments: kept 3650 days from paid_at
learning.events: kept 365 days from occurred_at
support.tickets: kept 730 days from opened_at, once status is closed
billing.payments on 2026-10-01, kept from: 2016-10-03
billing.payments on 2026-10-01, rows due: 0
billing.payments on 2026-10-01, rows in the table: 17,562
learning.events on 2026-10-01, kept from: 2025-10-01
learning.events on 2026-10-01, rows due: 9,060
learning.events on 2026-10-01, rows in the table: 100,000
support.tickets on 2026-10-01, kept from: 2024-10-01
support.tickets on 2026-10-01, rows due: 58
support.tickets on 2026-10-01, rows in the table: 2,000
billing.payments on 2026-12-30, kept from: 2017-01-01
billing.payments on 2026-12-30, rows due: 0
billing.payments on 2026-12-30, rows in the table: 17,562
learning.events on 2026-12-30, kept from: 2025-12-30
learning.events on 2026-12-30, rows due: 15,545
learning.events on 2026-12-30, rows in the table: 100,000
support.tickets on 2026-12-30, kept from: 2024-12-30
support.tickets on 2026-12-30, rows due: 111
support.tickets on 2026-12-30, rows in the table: 2,000
Las filas vencidas dependen del día que se pase y de los datos, y de nada más. El 1 de octubre de 2026, la regla de eventos conserva los eventos desde 2025-10-01, así que 9,060 de los 100,000 eventos vencen, y el 30 de diciembre, 90 días después, son 15,545. La regla de tickets hace vencer 58 de los 2,000 tickets el 1 de octubre, todos cerrados y abiertos hace más de dos años. El 30 de diciembre hace vencer 111. La regla de pagos hace vencer 0 de los 17,562 pagos el 1 de octubre y 0 el 30 de diciembre.
Regla práctica: Guarda el periodo de retención de cada tabla, la columna desde la que se cuenta y el estado que debe tener una fila, en un archivo revisado, y aplícalos a un día que le pase el planificador, nunca contra el reloj. Cuenta desde la fecha que la regla quiere decir. Cuando la tabla no registra esa fecha, como los tickets de la plataforma, que no registran cuándo se cerraron, pide al responsable de la tabla que añada la columna en lugar de dejar que la regla cuente desde otra fecha de forma permanente, y deja escrito en el archivo de la regla en qué sentido se equivoca hasta entonces.
Elimina las filas vencidas con borrados por fila
Con las reglas en un archivo, el trabajo de retención borra lo que ellas indican. Los escritores de Iceberg borran filas de una de dos maneras, según la propiedad de tabla write.delete.mode, que por defecto es copy-on-write (configuración de Iceberg). Copy-on-write reescribe cada archivo de datos afectado sin las filas borradas. Merge-on-read deja el archivo de datos intacto y escribe un archivo de borrado junto a él. La especificación tiene dos tipos de archivo de borrado: los de posición, que marcan una fila por su archivo de datos y su posición (un vector de eliminación, en tablas de versión 3 o superior), y los de igualdad, que la marcan por los valores de una o más columnas (especificación de tablas de Iceberg). Table.delete de PyIceberg 0.12.0 siempre copia al escribir: con merge-on-read activado, advierte que merge-on-read aún no está soportado y reescribe los archivos de todos modos (código fuente). En cualquiera de los dos casos, un borrado es un commit, una nueva instantánea, y la instantánea anterior sigue existiendo.
lib.retention.apply borra, para cada regla, las filas que due devuelve para el día que recibe, y registra la tabla de la regla y el día en el resumen de la instantánea del commit, de modo que el propio historial de la tabla indica por qué desaparecieron las filas. Dos ejecuciones para el 1 de octubre de 2026, leídas ahora y mediante viaje en el tiempo, muestran lo que deja un borrado, y al final se expiran por antigüedad las instantáneas antiguas:
1"""Applies the retention rules for the book's today as Iceberg row deletes, which leave the old rows in older snapshots.2The rerun line is zero, and the time-travel lines show the rows the snapshot before each delete still returns."""3from datetime import datetime, timedelta, timezone45from lib import retention6from lib.catalog import open_catalog7from lib.platform import TODAY89rules = retention.rules()["tables"]10catalog = open_catalog(sorted(rules))11# each table's snapshot from before the deletes, which the time-travel lines read12before = {name: catalog.load_table(name).current_snapshot().snapshot_id for name in rules}1314deleted = retention.apply(catalog, TODAY)15for name, rows in deleted.items():16 print(f"{name}, rows deleted:", f"{rows:,}")17print("rows deleted by running again for the same day:", sum(retention.apply(catalog, TODAY).values()))1819for name in (name for name, rows in deleted.items() if rows):20 rule, table = rules[name], catalog.load_table(name)21 summary = table.current_snapshot().summary22 print(f"{name}, snapshots:", " then ".join(s.summary.operation.value for s in table.snapshots()))23 # copy-on-write writes the rows it keeps again as new records, which is what this line counts24 print(f"{name}, rows written again to delete the others:", f"{int(summary['added-records']):,}")25 print(f"{name}, the commit records:", summary["retention-rule"], "on", summary["retention-day"])26 rows_due = retention.due(rule, TODAY)27 print(f"{name}, rows due, read now:", f"{retention.count(table, rows_due):,}")28 print(f"{name}, rows due, read by time travel:", f"{retention.count(table, rows_due, before[name]):,}")29 # Snapshots carry real commit times, so their age is measured on the clock, by the table's own setting.30 print(f"{name}, snapshots expired by age today:", retention.expire_by_age(table))31 # six days on, the snapshot from before the delete is older than the table's five-day setting32 later = datetime.now(timezone.utc) + timedelta(days=6)33 print(f"{name}, snapshots expired by age six days later:", retention.expire_by_age(table, later))
python apply-retention.pybilling.payments, rows deleted: 0
learning.events, rows deleted: 9,060
support.tickets, rows deleted: 58
rows deleted by running again for the same day: 0
learning.events, snapshots: append then overwrite
learning.events, rows written again to delete the others: 90,940
learning.events, the commit records: learning.events on 2026-10-01
learning.events, rows due, read now: 0
learning.events, rows due, read by time travel: 9,060
learning.events, snapshots expired by age today: 0
learning.events, snapshots expired by age six days later: 1
support.tickets, snapshots: append then overwrite
support.tickets, rows written again to delete the others: 1,942
support.tickets, the commit records: support.tickets on 2026-10-01
support.tickets, rows due, read now: 0
support.tickets, rows due, read by time travel: 58
support.tickets, snapshots expired by age today: 0
support.tickets, snapshots expired by age six days later: 1
Reintentar una ejecución no es perjudicial: una segunda ejecución para el mismo día borró 0 filas y no hizo ningún commit. La primera ejecución borró 9,060 eventos, 58 tickets y 0 pagos. Cada tabla que cambió pasó de una instantánea append a una overwrite, y el resumen muestra el coste de copy-on-write: para borrar los eventos antiguos, PyIceberg volvió a escribir las otras 90,940, porque la tabla es un único archivo sin particiones. Si la tabla estuviera particionada por mes de occurred_at, el mismo borrado eliminaría archivos completos, lo que Table.delete hace cuando todas las filas de un archivo coinciden. En PyIceberg 0.12.0, escribir una tabla particionada por mes requiere el extra pyiceberg-core, que los ejemplos de este libro no instalan.
Un borrado no elimina las filas de las instantáneas anteriores de la tabla. Leída tal como está ahora, learning.events contiene 0 filas más allá de su retención, pero leída mediante viaje en el tiempo, la instantánea anterior al borrado sigue devolviendo las 9,060, incluidas las direcciones IP, y el archivo Parquet que las contiene sigue en disco. lib.retention.expire_by_age expira las instantáneas más antiguas que la propia history.expire.max-snapshot-age-ms de la tabla, cinco días aquí, medidos con el reloj. Expira 0 instantáneas de learning.events justo después del borrado, y 1 seis días después. El trabajo de retención no termina hasta que las instantáneas antiguas están expiradas y los archivos que ninguna instantánea referencia se eliminan: la misma limpieza que necesita una solicitud de supresión de datos.
Regla práctica: Aplica la retención como borrados de filas de Iceberg, una regla cada vez, y registra la regla y el día en el resumen de instantánea de cada commit. Haz que el trabajo sea idempotente para un día dado. Particiona las tablas grandes por la columna desde la que cuenta una regla, de modo que sus borrados eliminen archivos completos en lugar de reescribirlos; en PyIceberg, instala su extra pyiceberg-core para escribir tablas particionadas. Da el trabajo por terminado solo cuando las instantáneas antiguas estén expiradas y sus archivos eliminados.
Leer el consentimiento donde se ejecuta la consulta
Retención elimina filas según su antigüedad. El consentimiento cambia quién puede usarlas, y retirarlo no es lo mismo que pedir la supresión, así que el código de la plataforma los trata como dos caminos. El artículo 7(3) del Reglamento General de Protección de Datos (RGPD) de la UE dice: "El interesado tendrá derecho a retirar su consentimiento en cualquier momento. La retirada del consentimiento no afectará a la licitud del tratamiento basada en el consentimiento previo a su retirada" (RGPD). El artículo 17(1)(b) del mismo reglamento convierte la retirada en un motivo de supresión, pero solo cuando no queda otra base jurídica para el tratamiento. En el código, una retirada cambia un atributo; una supresión elimina filas.
En la plataforma, el consentimiento es un atributo de los datos que lee la política de acceso, tal como lo configuró el capítulo 5: el filtro de filas de marketing conserva solo a los estudiantes cuyo marketing_consent es verdadero, y el del asistente del curso conserva solo las reseñas cuyos autores tienen ai_training_consent verdadero. Por tanto, una retirada no requiere cambiar la política. El CRM, la aplicación donde los estudiantes gestionan sus cuentas, sincroniza el nuevo valor en crm.learners, y la siguiente consulta que ejecute marketing, a través de la capa de cumplimiento que el capítulo 6 construye para reescribir cada consulta, devuelve un estudiante menos.
Retira el consentimiento de marketing del estudiante 3590 y, después, lee lo que ve marketing y lo que contienen las tablas antes de la retirada, después de ella y una vez que la canalización de marketing se ha ejecutado de nuevo.
1"""A learner withdraws marketing consent: one attribute changes, so marketing's next query returns one learner fewer and2no row is deleted. The table built with the consent filter keeps the learner until its pipeline runs again, as the audience lines show."""3import json45import pyarrow as pa6from pyiceberg.expressions import EqualTo78from lib import pipelines, policy, retention9from lib.catalog import open_catalog10from lib.enforce import Enforcer1112LEARNER = 359013catalog = open_catalog(["crm.learners", "learning.enrollments", "learning.courses"])14# the audience is built with the consent filter applied at build time, as the nightly job builds it15pipelines.run(catalog, "marketing_audience")16decision = policy.decide(policy.request("marketing-1", "crm.learners", ["learner_id"]))17print("marketing's row filters on crm.learners:", json.dumps(decision["row_filters"]))181920def report(when: str) -> list[int]:21 # marketing's query runs through the enforcement layer, which applies its row filters22 seen = [row[0] for row in Enforcer(catalog).sql("select learner_id from crm.learners", "marketing-1").fetchall()]23 print(f"{when}, learners marketing sees:", f"{len(seen):,}")24 print(f"{when}, marketing sees learner {LEARNER}:", LEARNER in seen)25 print(f"{when}, rows stored in crm.learners:", f"{retention.count(catalog.load_table('crm.learners')):,}")26 audience = retention.count(catalog.load_table("marketing.audience"), EqualTo("learner_id", LEARNER))27 print(f"{when}, learner {LEARNER}'s rows in marketing.audience:", audience)28 return seen293031before = report("before")32assert LEARNER in before # marketing's query returns the learner before the withdrawal33learners = catalog.load_table("crm.learners")34row = learners.scan(row_filter=EqualTo("learner_id", LEARNER)).to_arrow()35row = row.set_column(row.schema.get_field_index("marketing_consent"), "marketing_consent", pa.array([False]))36learners.overwrite(row, overwrite_filter=EqualTo("learner_id", LEARNER)) # what the CRM's sync writes37after = report("after the withdrawal")38assert LEARNER not in after # the next query, through the consent filter, drops the learner39pipelines.run(catalog, "marketing_audience")40report("after the audience is built again")
python consent-withdrawal.pymarketing's row filters on crm.learners: [{"column": "marketing_consent", "equals": true}, {"column": "status", "equals": "active"}]
before, learners marketing sees: 1,861
before, marketing sees learner 3590: True
before, rows stored in crm.learners: 5,000
before, learner 3590's rows in marketing.audience: 1
after the withdrawal, learners marketing sees: 1,860
after the withdrawal, marketing sees learner 3590: False
after the withdrawal, rows stored in crm.learners: 5,000
after the withdrawal, learner 3590's rows in marketing.audience: 1
after the audience is built again, learners marketing sees: 1,860
after the audience is built again, marketing sees learner 3590: False
after the audience is built again, rows stored in crm.learners: 5,000
after the audience is built again, learner 3590's rows in marketing.audience: 0
La retirada surtió efecto en la siguiente consulta y no eliminó nada: marketing ve 1,861 estudiantes antes, entre ellos el 3590, y 1,860 después, sin el 3590. Los filtros de filas de marketing siguen siendo [{"column": "marketing_consent", "equals": true}, {"column": "status", "equals": "active"}], y crm.learners sigue almacenando 5,000 filas. Nada se borró; la cuenta, las inscripciones y el historial del estudiante siguen como estaban.
El problema es la copia. marketing.audience, la lista que una canalización de marketing construye cada noche, aplica el filtro de consentimiento en el momento de construirla, y la política entrega a marketing esa tabla sin un filtro de consentimiento propio. Tras la retirada, sigue conteniendo 1 fila para el estudiante 3590. Mientras nadie clasifique las columnas de la tabla, la política las oculta para todos los lectores; en cuanto alguien lo haga, como propone el capítulo 4, una campaña enviada desde la tabla antes de su siguiente construcción llegará a alguien que dijo que no. Solo cuando la canalización vuelve a ejecutarse el recuento baja a 0. Un corpus de entrenamiento también se construye con un filtro de consentimiento, y el capítulo 9 comprueba cada construcción contra el consentimiento vigente antes de entrenar con ella.
Una columna de verdadero o falso también dice muy poco: ai_training_consent es nulo para todos los que se registraron antes de que la plataforma lo preguntara, y falso puede significar rechazado o retirado. El Data Privacy Vocabulary, un informe del Community Group del W3C y no un estándar, nombra los estados en que puede encontrarse un consentimiento: otorgado, rechazado, retirado, caducado y desconocido, entre otros (DPV 2.3).
Regla práctica: Mantén el consentimiento donde se ejecuta la consulta: en una sola tabla que el sistema que usa el estudiante mantiene actualizada, que la política lee como filtro de filas, de modo que una retirada cambie la siguiente consulta y no elimine nada. Cuando los abogados de la plataforma decidan que una retirada también es motivo de supresión, envíala también por la vía de supresión. Reconstruye cada tabla creada con un filtro de consentimiento cada vez que cambie el consentimiento, o da a sus lectores el mismo filtro. Registra cada consentimiento como un estado y el momento en que cambió, y deriva de él el atributo de verdadero o falso que lee la política, tratando lo desconocido como no otorgado.
Planifica un borrado a partir del linaje
Una retirada cambia un solo atributo; un borrado tiene que encontrar a la persona en todas partes. El artículo 17, apartado 1, del RGPD reconoce a una persona el derecho a que sus datos se supriman sin dilación indebida, por los motivos que enumera (RGPD). La plataforma trata una solicitud como algo que alcanza cada copia, así que su primera tarea, una cuestión de ingeniería, es una lista en dos mitades de dónde están los datos de la persona. Las tablas de origen que contienen el ID de un alumno provienen del catálogo: el capítulo 2 decidió que toda tabla con una learner_id forma parte de cada borrado, sea cual sea su clasificación. Las tablas construidas a partir de ellas provienen del linaje: el recorrido del grafo de columnas del capítulo 4, partiendo de cada tabla de origen, alcanza todas las tablas a las que sus filas dieron forma.
Algunos datos se conservan. El artículo 17, apartado 3, del mismo reglamento establece en qué casos el borrado no se aplica, en la medida en que el tratamiento sea necesario: entre sus cinco puntos, para el cumplimiento de una obligación legal exigida por el Derecho de la Unión o de los Estados miembros que se aplique al responsable del tratamiento (RGPD). Si una excepción se aplica, a qué tabla y durante cuánto tiempo, es decisión del equipo jurídico, nunca del código. El código concentra esa decisión en un solo lugar, governance/retention.toml, donde el equipo jurídico escribe cada excepción con su motivo. El motivo de este libro es un marcador de posición, porque aquí no decidimos ninguna cuestión jurídica:
[erasure.exceptions."billing.payments"]
reason = "PLACEHOLDER: a legal obligation to keep payment records, such as tax records. The legal team replaces this with the obligation and the law it comes from."
decided_by = "legal team" # a role, never a person's name
erase_columns = ["card_number"] # what the obligation doesn't need; an empty list keeps the whole row
Un borrado conserva las filas de una tabla exceptuada hasta que la regla de retención de esa tabla las elimine, y borra de inmediato las columnas que erase_columns indica: aquí, el número completo de la tarjeta, que los metadatos de la plataforma describen como «No debería almacenarse en absoluto». lib.retention.exceptions rechaza una excepción sin motivo, o una que se refiera a una tabla que ninguna regla termina.
Encontrar una tabla derivada no equivale a encontrar en ella las filas del alumno. lib.retention.plan examina las aristas de linaje que llegan a cada tabla alcanzada por el recorrido, buscando una columna copiada sin cambios, una arista IDENTITY en los términos de OpenLineage, a partir del ID del alumno o del ID de una de sus filas, como una reseña. Si existe, el plan borra por esa columna. Si no existe, las filas del alumno solo dieron forma a la tabla, y el plan vuelve a ejecutar el trabajo de la tabla una vez borradas las fuentes. El plan lee la plataforma tal como la encuentra la solicitud, semanas después de la retirada: crm.learners guarda el consentimiento retirado del alumno 3590, y los cuatro pipelines del capítulo 4, que construyen las tablas de analítica, marketing e IA, se han ejecutado desde entonces, con su linaje registrado.
El plan para el alumno 3590 imprime una línea por paso, cada tabla con lo que hace allí:
1"""The steps that erase one learner: the tables with their learner_id column, then the tables lineage says their rows reach,2with the exception the legal team recorded. The counts show how many steps each route found; the last two lines are the text the scan searches for and the rows that name the learner."""3from lib import pii, retention45LEARNER = 35906catalog, graph = retention.open_platform() # weeks after the learner withdrew marketing consent7steps = retention.plan(catalog, graph, LEARNER)8for step in steps:9 # no column is copied from the learner here: the table's own job runs again once its sources are erased10 if step.column is None:11 print(f"{step.table}: run {retention.job_for(step.table)} again")12 elif step.kept:13 print(f"{step.table}: keep, under an exception, and erase {', '.join(step.cleared)}")14 else:15 print(f"{step.table}: delete where {step.column} in {list(step.values)}"16 + (f", a copy of {step.via}" if step.via else ""))1718print("tables in the plan:", len(steps))19# a step with a column and no lineage edge came from the table's own learner_id column20print("tables found by their learner_id column:", sum(1 for step in steps if step.column and not step.via))21# found by lineage: a copy of another table's ID, or a rebuild, because the learner's rows only shaped the table22print("tables found by lineage:", sum(1 for step in steps if step.via or step.column is None))23for step in (step for step in steps if step.kept):24 print(f"the reason recorded for {step.table}:", step.kept)25theirs = retention.rows_of([LEARNER])26for name in ("billing.payments", "marketing.audience"):27 print(f"the learner's rows in {name}:", retention.count(catalog.load_table(name), theirs))28# the values the scan will search for, noted before any row is deleted29found = retention.traces(catalog, steps, LEARNER)30# The phone number is printed through lib.pii.masked, which keeps its shape and its last four digits.31print("the learner's identifying values, as the scan searches for them:", pii.masked(", ".join(found.texts)))32# rows the plan keeps, in any string column, whose text holds one of those values33named = retention.mentions(catalog, steps, found)34print("rows the plan doesn't delete whose text names the learner:", sum(named.values()))
python erasure-plan.pybilling.payments: keep, under an exception, and erase card_number
crm.learners: delete where learner_id in [3590]
learning.enrollments: delete where learner_id in [3590]
learning.events: delete where learner_id in [3590]
learning.reviews: delete where learner_id in [3590]
support.tickets: delete where learner_id in [3590]
analytics.course_performance: run course_performance again
analytics.learner_activity: delete where learner_id in [3590], a copy of crm.learners.learner_id
marketing.audience: delete where learner_id in [3590], a copy of crm.learners.learner_id
ai.review_corpus: delete where review_id in [1199], a copy of learning.reviews.review_id
tables in the plan: 10
tables found by their learner_id column: 6
tables found by lineage: 4
the reason recorded for billing.payments: PLACEHOLDER: a legal obligation to keep payment records, such as tax records. The legal team replaces this with the obligation and the law it comes from.
the learner's rows in billing.payments: 2
the learner's rows in marketing.audience: 0
the learner's identifying values, as the scan searches for them: •••-•••-5880 x•, 87199 jacob rad, alexa reed, alexa590@post.e
rows the plan doesn't delete whose text names the learner: 0
El plan visita 10 tablas: 6 tablas de origen con una columna learner_id, y 4 que añade el linaje. Conserva los 2 pagos del alumno bajo la excepción. Los pasos se deciden por columnas y linaje, no por filas, así que el plan enumera dos tablas que no contienen ninguna fila del alumno: support.tickets, ya que el alumno 3590 nunca abrió un ticket, y marketing.audience, que contiene 0 filas porque el pipeline la reconstruyó después de la retirada. ai.review_corpus no tiene ninguna learner_id, pero el linaje indica que su review_id es una copia IDENTITY de learning.reviews.review_id, así que el plan borra la reseña del alumno por ese ID. analytics.course_performance solo contiene recuentos y medias por curso, así que el plan la reconstruye a partir de las fuentes borradas. Reconstruirla cuesta una ejecución del pipeline, así que el código no necesita decidir si una media que en su día contó al alumno sigue siendo dato suyo.
Un texto puede nombrar a una persona en filas que el plan no borra, como el ticket de otro alumno. El ejemplo busca en cada columna de cadenas los valores identificativos que governance/retention.toml enumera, y encuentra 0 filas de este tipo. La búsqueda coincide con los primeros 15 caracteres de cada valor, en minúsculas, en cualquier parte del texto: aquí •••-•••-5880 x•, 87199 jacob rad, alexa reed, alexa590@post.e, impreso con el número de teléfono enmascarado, recortado a 15 por el motivo que explica el escaneo final. Un nombre escrito de otra forma o un número de teléfono sin separadores requiere los detectores del capítulo 3.
Regla práctica: Planifica cada borrado a partir del catálogo y del grafo de linaje, no de una lista que alguien mantiene: cada tabla con la columna de ID de la persona, y después cada tabla a la que el linaje indica que llegan sus filas. Borra de una tabla derivada por una columna que el linaje muestra como copia sin cambios de un ID, y reconstruye las tablas derivadas a las que las filas de la persona solo dieron forma. Guarda las excepciones en la configuración, escritas por tu equipo jurídico con sus motivos, y deja que el plan las lea y las muestre; nunca dejes que el código decida una. Ejecuta primero la comprobación del capítulo 4 de tablas que ningún linaje de trabajo explica, porque el plan no puede alcanzar una copia que el linaje no muestra.
Borra las filas que indica el plan
El plan indica dónde están los datos del alumno 3590, y lib.retention.erase los ejecuta en el orden del plan. Borra las filas de cada paso con Table.delete, primero las fuentes, vuelve a escribir las filas que conserva una excepción con las columnas de la excepción vacías, y ejecuta el trabajo de cada tabla que el plan reconstruye una vez terminadas las fuentes. Cada confirmación registra el ID de la solicitud, erasure-0001, en el resumen de su snapshot. Iceberg conserva un resumen en los archivos de metadatos de la tabla después de que expire su snapshot, en todos ellos por defecto, o solo en los últimos write.metadata.previous-versions-max (100 por defecto) una vez que se define write.metadata.delete-after-commit.enabled (Mantenimiento de Iceberg, Configuración de Iceberg). Por eso el resumen solo contiene el ID de la solicitud, que el registro de borrados asocia con un hash con clave del ID del alumno, y nunca el correo electrónico del alumno.
El borrado se ejecuta sobre el plan del alumno 3590 bajo un único ID de solicitud; leer crm.learners y learning.events ahora y mediante viaje en el tiempo muestra lo que deja:
1"""Carries out the erasure plan with Iceberg row deletes. The current snapshots no longer hold the learner, but the snapshots2before them still do, and the `read by time travel` lines show it."""3from lib import retention45LEARNER = 35906catalog, graph = retention.open_platform()7steps = retention.plan(catalog, graph, LEARNER)8# each table's snapshot from before the erasure, which the time-travel lines read9before = {step.table: catalog.load_table(step.table).current_snapshot().snapshot_id for step in steps}1011done = retention.erase(catalog, steps, "erasure-0001") # the request's ID goes into every commit's summary12for table, rows in done.items():13 # a rebuilt table reports 'rebuilt' rather than a count of rows14 print(f"{table}, rows deleted:" if rows != "rebuilt" else f"{table}:", rows)15print("tables one row was deleted from:", ", ".join(table for table, rows in done.items() if rows == 1))16theirs = retention.rows_of([LEARNER])17payments = catalog.load_table("billing.payments").scan(row_filter=theirs).to_arrow()18print("billing.payments, the learner's rows kept:", payments.num_rows)19# the exception erases card_number to null, so the values that are not null are the card numbers left20print("billing.payments, card numbers left in them:", payments.num_rows - payments["card_number"].null_count)21for name in ("crm.learners", "learning.events"):22 table = catalog.load_table(name)23 print(f"the learner's rows in {name}, read now:", retention.count(table, theirs))24 print(f"the learner's rows in {name}, read by time travel:", retention.count(table, theirs, before[name]))2526summary = catalog.load_table("crm.learners").current_snapshot().summary27# copy-on-write writes the rows it keeps again as new records, so this counts every other row of the file28print("crm.learners, rows written again to delete one:", f"{int(summary['added-records']):,}")29print("crm.learners, the commit records:", summary["erasure-request"])30# snapshots of tables the plan deleted from (not rebuilt, not kept) that still return a row the erasure deleted31holding = [(table, snapshot) for step in steps if step.column is not None32 for table in [catalog.load_table(step.table)] for snapshot in table.snapshots()33 if not step.kept and retention.count(table, retention.rows(step), snapshot.snapshot_id)]34print("snapshots that still hold the rows the erasure deleted:", len(holding))35print("of them current:", sum(snapshot == table.current_snapshot() for table, snapshot in holding))
python erase-learner.pybilling.payments, rows deleted: 0
crm.learners, rows deleted: 1
learning.enrollments, rows deleted: 2
learning.events, rows deleted: 19
learning.reviews, rows deleted: 1
support.tickets, rows deleted: 0
analytics.course_performance: rebuilt
analytics.learner_activity, rows deleted: 1
marketing.audience, rows deleted: 0
ai.review_corpus, rows deleted: 1
tables one row was deleted from: crm.learners, learning.reviews, analytics.learner_activity, ai.review_corpus
billing.payments, the learner's rows kept: 2
billing.payments, card numbers left in them: 0
the learner's rows in crm.learners, read now: 0
the learner's rows in crm.learners, read by time travel: 1
the learner's rows in learning.events, read now: 0
the learner's rows in learning.events, read by time travel: 19
crm.learners, rows written again to delete one: 4,999
crm.learners, the commit records: erasure-0001
snapshots that still hold the rows the erasure deleted: 6
of them current: 0
El borrado sacó al alumno de todas las tablas del plan que tenían alguno de sus datos. Eliminó 19 de los eventos del alumno, 2 matrículas, y una fila de cada una de crm.learners, learning.reviews, analytics.learner_activity, ai.review_corpus. No borró nada de support.tickets ni de marketing.audience, que no tenían datos del alumno, y reconstruyó analytics.course_performance.
billing.payments conserva los 2 pagos del alumno, con 0 números de tarjeta dentro. Leída ahora, crm.learners devuelve 0 filas del alumno. Leída mediante viaje en el tiempo hasta el snapshot anterior al borrado, devuelve 1, con nombre, correo electrónico, teléfono y dirección, y learning.events devuelve del mismo modo los 19 eventos del alumno.
Para borrar una fila de crm.learners, PyIceberg escribió las otras 4,999 en un archivo nuevo, como hace copy-on-write, y el archivo anterior, con el alumno dentro, pertenece al snapshot anterior.
En las tablas del plan, 6 snapshots siguen conteniendo las filas que borró el borrado, y 0 de ellos son actuales. Para eso sirven los snapshots: un lector puede volver a cualquiera de ellos. En un borrado, esto significa que el borrado sacó al alumno de la tabla, pero no del almacenamiento.
Regla práctica: Ejecuta un borrado como eliminaciones de filas en el orden del plan, y registra solo un ID de solicitud en cada confirmación, nunca un valor de la persona. Trata el borrado como el primero de tres pasos: los snapshots anteriores siguen conteniendo a la persona, y quien pueda viajar en el tiempo puede leerlos hasta que se expiren.
Expirar snapshots según la configuración propia de la tabla
Después de los borrados de la eliminación, las filas de la alumna 3590 siguen viviendo en los snapshots anteriores a ellos. La especificación de Iceberg indica que los snapshots se expiran para que los archivos de datos que eliminaron o reemplazaron puedan borrarse físicamente (especificación de tablas Iceberg). Cada tabla define cómo hacerlo en sus propiedades (configuración de Iceberg): gc.enabled permite la recolección de basura, como expirar snapshots y eliminar archivos huérfanos; history.expire.min-snapshots-to-keep es cuántos snapshots conservar, sin importar su antigüedad; y history.expire.max-snapshot-age-ms es la antigüedad a partir de la cual el resto puede eliminarse. En la biblioteca Java de Iceberg, expirar snapshots periódicamente borra los archivos de datos que ya no se usan (mantenimiento de Iceberg).
PyIceberg 0.12.0 hace menos. Su table.maintenance.expire_snapshots() confirma un solo cambio, que quita los snapshots de los metadatos de la tabla y no borra ningún archivo (código fuente), aunque su documentación lo ofrece para "limpiar los metadatos de la tabla y reducir los costos de almacenamiento" (API de PyIceberg). Nada en él lee gc.enabled, y solo su herramienta de línea de comandos lee las opciones history.expire. Una incidencia pide que la expiración también borre archivos (incidencia 2604). Dos copias de crm.learners tienen cada una 3 snapshots: la carga y dos borrados. Una copia tiene gc.enabled=false y la otra history.expire.min-snapshots-to-keep=3, y cada una se expira de dos formas: por antigüedad con PyIceberg, older_than la hora actual, y con lib.retention.expire, que lee antes las dos configuraciones.
1"""PyIceberg's snapshot expiry ignores two of the table's own settings, gc.enabled and min-snapshots-to-keep, so it expires2snapshots they would keep. The book's expiry reads both first, and the `left by PyIceberg's expiry` lines show the difference."""3from datetime import datetime, timezone45from pyiceberg.expressions import EqualTo67from lib import retention8from lib.catalog import open_catalog91011def learners_with(settings: dict):12 """crm.learners with three snapshots: the load, then two deletes."""13 table = open_catalog(["crm.learners"]).load_table("crm.learners")14 with table.transaction() as transaction:15 transaction.set_properties(settings)16 # two deletes, so there are snapshots from before them for the expiry to consider17 for learner in (3590, 3591):18 table.delete(EqualTo("learner_id", learner))19 return table202122for settings in ({"gc.enabled": "false"}, {"history.expire.min-snapshots-to-keep": "3"}):23 setting = ", ".join(f"{key}={value}" for key, value in settings.items())24 table = learners_with(settings)25 print(f"{setting}, snapshots:", len(table.snapshots()))26 try:27 print(f"{setting}, the book's expiry expires:", retention.expire(table))28 except retention.RetentionError as error:29 print(f"{setting}, the book's expiry refuses:", error)30 # PyIceberg's expiry by age, as of now: it reads neither setting31 table.maintenance.expire_snapshots().older_than(datetime.now(timezone.utc)).commit()32 print(f"{setting}, snapshots left by PyIceberg's expiry:", len(table.snapshots()))
python expiry-ignores-table-settings.pygc.enabled=false, snapshots: 3
gc.enabled=false, the book's expiry refuses: crm.learners has gc.enabled=false, which turns off garbage collection for the table
gc.enabled=false, snapshots left by PyIceberg's expiry: 1
history.expire.min-snapshots-to-keep=3, snapshots: 3
history.expire.min-snapshots-to-keep=3, the book's expiry expires: 0
history.expire.min-snapshots-to-keep=3, snapshots left by PyIceberg's expiry: 1
La expiración de PyIceberg ignora ambas configuraciones. Dejó 1 de los 3 snapshots de la primera tabla, y 1 de los de la segunda. older_than expira todos los snapshots más antiguos que el momento que se le indica, salvo los que apunta una rama o una etiqueta, aquí solo el actual.
La expiración del libro rechazó la primera tabla, crm.learners has gc.enabled=false, which turns off garbage collection for the table, y expiró 0 snapshots de la segunda. Un responsable define estas propiedades por razones que el código de expiración no puede ver, y en PyIceberg solo son un consejo.
En una eliminación, ambas configuraciones impiden que el trabajo termine: una tabla que conserva un snapshot anterior al borrado todavía contiene a la persona. Un trabajo que se detuviera en esa tabla ya habría borrado filas de las tablas anteriores y dejaría las demás sin expirar, así que la comprobación debe hacerse antes del primer borrado. lib.retention.erase_everywhere ejecuta lib.retention.blocked en cada tabla del plan primero: recolección de basura desactivada, más de un snapshot que conservar, o una rama o etiqueta distinta de main. Si alguna tabla falla, el trabajo se niega a empezar y nombra todas esas tablas.
Aquí crm.learners tiene la recolección de basura desactivada, y learning.events conserva tres snapshots. Entonces se ejecutan el trabajo y el escaneo:
1"""The erasure job checks every table in its plan before it changes any, and refuses to start when a table's own settings2would keep the learner. The scan still runs, from the traces the refusal carries, and finds the learner in the files."""3from datetime import timedelta45from lib import retention67LEARNER = 35908catalog, graph = retention.open_platform()9# each setting stops expiry from removing the snapshot from before the delete: garbage collection off, or three snapshots kept10for name, settings in (("crm.learners", {"gc.enabled": "false"}),11 ("learning.events", {"history.expire.min-snapshots-to-keep": "3"})):12 with catalog.load_table(name).transaction() as transaction:13 transaction.set_properties(settings)14# every table's current snapshot, to count the tables the job changes15before = {name: catalog.load_table(name).current_snapshot().snapshot_id for name in retention.tables(catalog)}1617try:18 # min_age of zero: one writer and nothing in flight, so no file needs a minimum age to be safe to sweep19 steps, found, done = retention.erase_everywhere(catalog, graph, LEARNER, "erasure-0001", min_age=timedelta(0))20except retention.ErasureRefused as refusal:21 for name, why in refusal.tables.items():22 print(f"the job refuses, because of {name}:", why)23 found = refusal.found24# a table the job changed has a new current snapshot25print("tables the job changed:", sum(catalog.load_table(name).current_snapshot().snapshot_id != snapshot26 for name, snapshot in before.items()))27report = retention.scan(catalog, found)28print("tables whose files hold the learner:", sum(1 for _, holding in report.values() if holding))29print("files holding the learner:", sum(holding for _, holding in report.values()))
python erasure-refuses-to-start.pythe job refuses, because of crm.learners: gc.enabled=false turns off garbage collection for the table
the job refuses, because of learning.events: history.expire.min-snapshots-to-keep=3 keeps the snapshot from before the delete
tables the job changed: 0
tables whose files hold the learner: 7
files holding the learner: 8
El trabajo se niega. Nombra las dos tablas, crm.learners porque gc.enabled=false turns off garbage collection for the table, y learning.events porque history.expire.min-snapshots-to-keep=3 keeps the snapshot from before the delete, y 0 tablas cambiaron.
El escaneo se ejecuta de todos modos, a partir de los rastros que trae el rechazo, y encuentra a la alumna en 8 archivos repartidos en 7 tablas. Entonces una persona decide junto con los responsables de las tablas, en lugar de que el código anule la configuración de un responsable.
Regla práctica: Expira los snapshots mediante una función propia que lea gc.enabled y las configuraciones history.expire antes de expirar nada, y que se niegue cuando la recolección de basura esté desactivada, porque la expiración de PyIceberg no lee ninguna de las dos; vuelve a comprobarlo en cada versión de PyIceberg. Antes de que una eliminación borre algo, comprueba del mismo modo cada tabla de tu plan, y rechaza toda la eliminación cuando una de ellas conservaría a la persona. En una eliminación, expira todos los snapshots anteriores al borrado. Para la retención, expira por antigüedad, como indica history.expire.max-snapshot-age-ms, medida con el reloj, ya que los snapshots llevan las horas reales de confirmación.
Elimina los archivos que ningún snapshot referencia
Una vez que los snapshots antiguos han expirado, los archivos que solo ellos referenciaban quedan sin referencia. Un archivo sin referencia, que Iceberg llama huérfano, se encuentra bajo la ubicación de la tabla, pero no aparece en los metadatos de ningún snapshot. La biblioteca Java de Iceberg los elimina mediante una acción aparte, y advierte que eliminar archivos huérfanos con un intervalo de retención más corto que el tiempo previsto para que se complete cualquier escritura es peligroso; su intervalo predeterminado es de 3 días (mantenimiento de Iceberg). PyIceberg 0.12.0 no tiene tal acción. Sus notas de versión no incluyen ninguna (notas de versión). La incidencia que pedía una acción así fue cerrada por el bot de inactividad del proyecto, marcada como no planificada (incidencia 1200). Dos solicitudes de cambios que añadían una acción así se cerraron sin fusionarse (1958, 3358). Su única llamada que elimina archivos de datos es purge_table, que elimina la tabla completa (código fuente).
Por tanto, lib.retention los elimina por su cuenta, a partir de lo que las tablas de metadatos que PyIceberg expone como table.inspect indican que referencia una tabla. lib.retention.referenced recoge los archivos de metadatos, actuales y registrados, la lista de manifiestos de cada snapshot, cada manifiesto (un manifiesto enumera los archivos de datos, con las estadísticas de columna de cada archivo), cada archivo de datos y de borrado vivo en cualquier snapshot, y cualquier archivo de estadísticas. Todo otro archivo bajo la ubicación de la tabla no tiene referencia, y lib.retention.sweep elimina los que son más antiguos que la edad mínima que indica quien lo invoca. governance/retention.toml fija esa edad en 72 horas, el valor predeterminado de Java, y lib.retention.min_file_age la lee. Tras el borrado, las tablas del plan se expiran, se barren con esa edad y luego sin ella, y se comprueba cada archivo en busca del alumno:
1"""After the erasure, expire the old snapshots, then remove the files no snapshot references. PyIceberg's expiry deletes no2file and has no orphan-file removal, so lib.retention.sweep does it with the inspect tables; the last lines show the manifest entries still holding the learner's email."""3from datetime import timedelta45from lib import retention67LEARNER = 35908catalog, graph = retention.open_platform()9steps = retention.plan(catalog, graph, LEARNER)10found = retention.traces(catalog, steps, LEARNER)11retention.erase(catalog, steps, "erasure-0001")12tables = [catalog.load_table(step.table) for step in steps]13print("snapshots expired:", sum(retention.expire(table) for table in tables))14print("files under the plan's tables:", sum(len(retention.files_under(table.location())) for table in tables))15print("files no metadata references:", sum(len(retention.unreferenced(table)) for table in tables))16print("files holding the learner, after expiry:", sum(held for _, held in retention.scan(catalog, found).values()))17# the configured minimum age, 72 hours, from governance/retention.toml18print("files swept with the configured minimum age:", sum(retention.sweep(t, retention.min_file_age()) for t in tables))19# One writer, nothing in flight: no file is too young to remove, so the examples sweep with no minimum age.20print("files swept with no minimum age:", sum(retention.sweep(table, timedelta(0)) for table in tables))21print("files holding the learner, after the sweep:", sum(held for _, held in retention.scan(catalog, found).values()))2223for table in tables:24 # every manifest entry, including those of deleted files, with the bounds it keeps for the email column25 entries = table.inspect.entries()26 for status, metrics in zip(entries["status"].to_pylist(), entries["readable_metrics"].to_pylist()):27 bounds = metrics.get("email") or {}28 # bounds are compared lowercased: the learner's email is typed in capitals in the manifest29 kept = (bounds.get("lower_bound"), bounds.get("upper_bound"))30 if any(text in bound.lower() for bound in kept if bound for text in found.texts):31 print(f"{'.'.join(table.name()[-2:])}, manifest entry with status {status}, email bounds:",32 bounds["lower_bound"], "to", bounds["upper_bound"])
python sweep-unreferenced-files.pysnapshots expired: 8
files under the plan's tables: 100
files no metadata references: 28
files holding the learner, after expiry: 9
files swept with the configured minimum age: 0
files swept with no minimum age: 28
files holding the learner, after the sweep: 1
crm.learners, manifest entry with status 2, email bounds: ALEXA590@POST.EX to zofia.haase@exan
La expiración elimina snapshots, no archivos. De los archivos bajo las tablas del plan, 28 no están referenciados por nada, y 9 contienen al alumno. El barrido con las 72 horas configuradas elimina 0 archivos sin referencia, ya que cada archivo se escribió hace segundos. Los ejemplos pasan una edad de cero porque un único proceso escribe en su catálogo. El barrido sin edad mínima elimina todos los archivos sin referencia, y 1 archivo sigue conteniendo al alumno: un manifiesto al que hace referencia el snapshot actual de crm.learners.
La especificación explica por qué: cuando un archivo se reemplaza o se elimina, su entrada en el manifiesto guarda el snapshot en el que se eliminó el archivo y el estado 2 (eliminado) (especificación de tablas de Iceberg), y esa entrada conserva las estadísticas de columna del archivo eliminado. Por defecto, con el modo de métricas truncate(16) (configuración de Iceberg), estas incluyen el valor más pequeño de cada columna de cadena, recortado a 16 caracteres, y el más grande, recortado a 16 con el último carácter incrementado en uno, de modo que siga acotando cada valor del archivo (código fuente). La entrada eliminada en crm.learners conserva los límites de correo ALEXA590@POST.EX to zofia.haase@exan. El primero es el correo del alumno 3590, escrito en mayúsculas, que se ordena antes que cualquier otro correo de la plataforma. El segundo es el del alumno 4998, el mayor de la plataforma, cuyo carácter 16, una m, se convirtió en una n. Ningún alumno está a salvo de esto: la entrada de cada archivo de datos conserva el valor más pequeño y más grande de cada columna, de modo que una tabla de muchos archivos pequeños nombra a muchos alumnos.
Regla práctica: Elimina los archivos sin referencia después de cada expiración, con un barrido propio basado en las tablas de inspección, ya que PyIceberg no tiene ninguno, y mantén en producción una edad mínima de días para que una escritura en curso conserve sus archivos. Usa una edad de cero solo donde un único proceso escribe. No consideres borrada a una persona porque ningún archivo de datos la contenga: los manifiestos pueden seguir conservando sus valores.
Mantén los valores personales fuera de los manifiestos
El barrido dejó el correo electrónico del estudiante en un manifiesto, como límite de una columna. Iceberg permite que una tabla elija, columna por columna, qué conservan sus manifiestos, con la propiedad write.metadata.metrics.column.<name>: none no conserva nada, counts conserva los recuentos de valores y nulos, truncate(n) añade límites recortados a n caracteres, y full añade los límites completos (configuración de Iceberg). PyIceberg 0.12.0 busca la propiedad por el nombre de la columna al escribir un archivo (código fuente).
Escritas a mano, esas propiedades se desviarían de las clasificaciones. lib.retention.properties las genera a partir de governance/metadata.toml y de la sección [statistics] de governance/retention.toml: none para cada columna clasificada como personal o sensitive, y para cada columna que nadie ha clasificado, con el mismo valor predeterminado de fallo seguro que usa la política de acceso. Además añade los ajustes de history.expire de la sección [snapshots] de las reglas. lib.retention.apply_properties los establece en todas las tablas y reescribe los datos de cada tabla una vez, porque un modo de métricas solo se aplica a los archivos escritos después de establecerlo; la expiración y una limpieza eliminan después los archivos anteriores. El estudiante 4998, cuyo correo es el límite más grande en el manifiesto de crm.learners, es el caso de prueba: se borra en dos plataformas, una con estadísticas predeterminadas y otra con las propiedades generadas:
1"""Generates each table's properties from the classifications, so manifests keep no bounds on personal columns, then erases2the learner whose email is the platform's largest, on a platform with the properties and on one without. The `files holding` lines are the proof."""3from datetime import timedelta45from lib import retention67LEARNER = 49988for statistics_off in (False, True):9 catalog, graph = retention.open_platform(statistics_off)10 label = "statistics off for protected columns" if statistics_off else "default statistics"11 if statistics_off:12 generated = retention.properties(catalog)13 # the per-column metrics settings; the history.expire settings are not counted here14 turned_off = [key for wanted in generated.values() for key in wanted if key.startswith(retention.METRICS)]15 print("columns with statistics turned off:", len(turned_off))16 # tables with no entry in governance/metadata.toml, which the generated properties still cover17 unclassified = [name for name in generated if name not in retention.metadata.load()]18 print("of them in tables nobody has classified:",19 sum(key.startswith(retention.METRICS) for name in unclassified for key in generated[name]))20 print("crm.learners, properties set:", len(generated["crm.learners"]))21 for key, value in sorted(generated["crm.learners"].items()):22 print(f" {key} = {value}")23 # crm.learners has one data file, so its one manifest entry keeps the table's email bounds24 entry = catalog.load_table("crm.learners").inspect.entries()["readable_metrics"].to_pylist()[0]25 print(f"{label}, crm.learners email bounds:", entry["email"]["lower_bound"], "to", entry["email"]["upper_bound"])26 columns = retention.metadata.load()["crm.learners"].columns.values()27 personal = [column.name for column in columns if column.classification == "personal"]28 print(f"{label}, crm.learners personal columns:", len(personal))29 with_bounds = sum(entry[name]["lower_bound"] is not None for name in personal)30 print(f"{label}, of them with bounds in the manifest:", with_bounds)31 steps, found, _ = retention.erase_everywhere(catalog, graph, LEARNER, "erasure-0002", min_age=timedelta(0))32 print(f"{label}, files holding learner {LEARNER} after erasure, expiry and sweep:",33 sum(held for _, held in retention.scan(catalog, found).values()))
python statistics-off-for-personal-columns.pydefault statistics, crm.learners email bounds: ALEXA590@POST.EX to zofia.haase@exan
default statistics, crm.learners personal columns: 7
default statistics, of them with bounds in the manifest: 7
default statistics, files holding learner 4998 after erasure, expiry and sweep: 1
columns with statistics turned off: 24
of them in tables nobody has classified: 10
crm.learners, properties set: 9
history.expire.max-snapshot-age-ms = 432000000
history.expire.min-snapshots-to-keep = 1
write.metadata.metrics.column.city = none
write.metadata.metrics.column.date_of_birth = none
write.metadata.metrics.column.email = none
write.metadata.metrics.column.full_name = none
write.metadata.metrics.column.notes = none
write.metadata.metrics.column.phone = none
write.metadata.metrics.column.street_address = none
statistics off for protected columns, crm.learners email bounds: None to None
statistics off for protected columns, crm.learners personal columns: 7
statistics off for protected columns, of them with bounds in the manifest: 0
statistics off for protected columns, files holding learner 4998 after erasure, expiry and sweep: 0
Con estadísticas predeterminadas, 1 archivo sigue conteniendo al estudiante 4998 después del borrado, la expiración y la limpieza, a través de un límite superior elevado. El manifiesto conserva límites para 7 de las columnas personales de la tabla, y sus límites de correo son ALEXA590@POST.EX to zofia.haase@exan.
Desactivar las estadísticas de las columnas personales es lo que mantiene al estudiante 4998 fuera de los archivos. Los límites de correo son None to None, el manifiesto conserva límites para 0 de las 7 columnas personales de la tabla, y 0 archivos contienen al estudiante después del borrado, la expiración y la limpieza.
Las propiedades generadas desactivan las estadísticas de 24 columnas, 10 de ellas en marketing.audience y ai.review_corpus, las dos tablas que el capítulo 2 encontró sin metadatos. crm.learners recibe 9 propiedades: los dos ajustes de expiración, y none para cada columna personal.
El costo es la poda. Iceberg usa los límites de los manifiestos para omitir archivos que el filtro de una consulta no puede cumplir (especificación de tablas Iceberg), así que sin ellos, una consulta que filtra por email lee todos los archivos. La plataforma filtra y borra por learner_id, que es internal y mantiene sus estadísticas. counts es la otra opción: conserva los recuentos que ayudan al planificador, y ningún valor. Y como PyIceberg 0.12.0 conserva la propiedad bajo el nombre antiguo de la columna al renombrarla, dejando el nuevo nombre sin ella, las propiedades se vuelven a generar en cada cambio de esquema, como exige el capítulo 2 para toda vista de los metadatos indexada por nombre.
Regla práctica: Genera las propiedades de métricas por columna a partir de tus clasificaciones, none o counts para cada columna personal, sensible o sin clasificar, y aplícalas al crear una tabla o, en una tabla existente, con una reescritura seguida de expiración y limpieza. Mantén las estadísticas en las columnas de ID por las que filtras y borras. Vuelve a generar las propiedades después de cada cambio de esquema.
Demuestra el borrado leyendo cada archivo
Cada paso hasta ahora eliminó algo que el anterior había dejado atrás, y dejó algo propio: el borrado, la expiración, la limpieza y los ajustes de estadísticas. Por eso conviene comprobar el resultado en lugar de confiar en los pasos. El informe del Comité Europeo de Protección de Datos sobre cómo los responsables gestionan el borrado, aprobado en febrero de 2026, identificó entre los puntos débiles las copias de seguridad y la anonimización empleada en lugar del borrado, y recomienda que los responsables «Verifiquen que el borrado se ha llevado a cabo y estén en condiciones de demostrarlo» (EDPB, 2026).
lib.retention.scan lee cada archivo bajo el almacén del catálogo, con el lector de su propio formato, y busca las huellas del alumno. lib.retention.traces anota las huellas antes del borrado: los identificadores de cada fila que el plan elimina, por columna, y los primeros 15 caracteres, en minúsculas, de cada valor identificativo. Son quince porque un manifiesto conserva sin cambios los primeros 15 caracteres del valor más grande y aumenta en uno el decimosexto; buscar con 16 pasaría por alto a una persona cuyo valor es el máximo de un archivo, como el correo electrónico del alumno 4998. Un archivo Parquet se lee como filas. Un manifiesto o una lista de manifiestos, ambos en Avro, se lee registro a registro con el lector Avro de PyIceberg: cada cadena, incluidos los límites, y los límites de cada columna de identificadores, decodificados con el esquema que trae el manifiesto. Un archivo de metadatos se lee como texto. En una tabla que una excepción conserva, se espera encontrar los identificadores del alumno, así que allí la lectura busca solo los valores, incluidos los de las columnas que la excepción borró. lib.retention.erase_everywhere ejecuta el proceso completo: planificar, anotar las huellas, revisar cada tabla, borrar, expirar y limpiar. En la plataforma con las propiedades generadas, el proceso completo se ejecuta y termina con la lectura:
1"""Runs the whole erasure job on the platform with statistics off for protected columns, then scans every file under the2warehouse. The `files holding the learner` line is the proof; the rest is evidence of IDs and counts, never the learner's values."""3from datetime import timedelta45from lib import retention67LEARNER, REQUEST = 3590, "erasure-0001"8catalog, graph = retention.open_platform(statistics_off=True)9# min_age of zero: one writer, so nothing is in flight that a sweep could take10steps, found, done = retention.erase_everywhere(catalog, graph, LEARNER, REQUEST, min_age=timedelta(0))1112report = retention.scan(catalog, found)13for table, (files, holding) in report.items():14 print(f"{table}: {files} files read, {holding} holding the learner")1516print("request:", REQUEST)17print("tables visited:", len(steps))18# each table the job deleted from has a count of rows; the one it reran has 'rebuilt' instead19print("rows deleted:", sum(rows for rows in done.values() if rows != "rebuilt"))20print("tables rebuilt:", ", ".join(table for table, rows in done.items() if rows == "rebuilt"))21print("tables kept under an exception, columns erased:",22 "; ".join(f"{step.table}, {', '.join(step.cleared)}" for step in steps if step.kept))23# every snapshot but the current one: the ones a reader can still time travel to24print("snapshots a reader can still time travel to:",25 sum(len(catalog.load_table(step.table).snapshots()) - 1 for step in steps))26print("files no metadata references:",27 sum(len(retention.unreferenced(catalog.load_table(name))) for name in retention.tables(catalog)))28print("tables missing their generated properties:", ", ".join(retention.missing_properties(catalog)))29print("files read:", sum(files for files, _ in report.values()))30print("files holding the learner:", sum(holding for _, holding in report.values()))
python verify-erasure.pyai.review_corpus: 11 files read, 0 holding the learner
analytics.course_performance: 5 files read, 0 holding the learner
analytics.learner_activity: 11 files read, 0 holding the learner
billing.payments: 12 files read, 0 holding the learner
crm.instructors: 8 files read, 0 holding the learner
crm.learners: 11 files read, 0 holding the learner
learning.courses: 8 files read, 0 holding the learner
learning.enrollments: 11 files read, 0 holding the learner
learning.events: 11 files read, 0 holding the learner
learning.reviews: 11 files read, 0 holding the learner
marketing.audience: 8 files read, 0 holding the learner
support.tickets: 8 files read, 0 holding the learner
request: erasure-0001
tables visited: 10
rows deleted: 25
tables rebuilt: analytics.course_performance
tables kept under an exception, columns erased: billing.payments, card_number
snapshots a reader can still time travel to: 0
files no metadata references: 0
tables missing their generated properties: analytics.course_performance
files read: 115
files holding the learner: 0
La lectura encuentra al alumno en 0 de los 115 archivos que lee, y ningún lector puede viajar en el tiempo hasta el alumno, ya que siguen existiendo 0 instantáneas antiguas y hay 0 archivos sin referencias. Las líneas posteriores a los recuentos por tabla son la evidencia: el identificador de la solicitud, las tablas revisadas, las filas borradas, la tabla que el proceso reconstruyó, la tabla que una excepción conserva y la columna borrada de ella, billing.payments, card_number, con el motivo en governance/retention.toml, y los recuentos de la lectura. No contienen ningún valor del alumno, así que conservarlas no devuelve ninguno, algo en lo que se apoya el capítulo 8 al escribirlas en el registro de auditoría.
Una línea es una advertencia: analytics.course_performance carece de sus propiedades generadas, porque lib.pipelines.run eliminó la tabla y la volvió a crear sin ellas. Esa tabla no tiene columnas personales. La siguiente tabla que una canalización reconstruya podría tenerlas, y la lectura informaría entonces de los límites de sus manifiestos como un borrado fallido, por lo que la comprobación debe hacerse después de cada ejecución de una canalización.
Los identificadores también pueden permanecer en un manifiesto, ya que las columnas de identificadores conservan sus estadísticas. Un identificador borrado que fue el mínimo o el máximo de un archivo, como el del alumno 5000, permanece en los límites de la entrada borrada, y la lectura lo informa. Una confirmación más sobre la tabla, seguida de una expiración y una limpieza, lo elimina, porque la siguiente adición de PyIceberg omite un manifiesto que contiene solo archivos borrados (fuente).
El escaneo cubre solo el almacén. Las exportaciones, las copias de seguridad, los sistemas de origen y los registros fuera de él también pueden contener al alumno, y se pueden buscar las mismas huellas en cada uno de ellos que la plataforma pueda leer.
Regla práctica: Termina cada borrado con una lectura de cada archivo que almacena la plataforma, buscando los identificadores de la persona y sus valores identificativos, leída con el lector propio de cada formato, y conserva su resultado, con recuentos e identificadores únicamente, como evidencia. Busca la parte de cada valor que todos los límites conservan sin cambios, que es un carácter menos que la longitud del truncamiento. Trata cualquier archivo que aún contenga a la persona como un borrado fallido, no como una advertencia. Busca en los almacenamientos externos al almacén que controlas, y anota en el registro los que no puedas revisar.
Qué sale mal en producción
Un borrado que tiene éxito se ve igual tanto si los datos ya no existen como si siguen almacenados, y así es como falla el borrado. El primer fallo de esta sección deshace un borrado ya terminado.
Un alumno borrado vuelve
Además de la sincronización del CRM, el almacén recarga cada noche toda la tabla crm.learners desde la exportación de la aplicación, y el borrado se ejecutó solo en el almacén. Borra al alumno 3590 en todas partes, como indica el plan, y después deja que se ejecuten la recarga nocturna y las canalizaciones que leen la tabla:
1"""An erased learner comes back: the nightly reload of crm.learners from the application's export brings the rows back, and2the pipelines rebuild from them. A check against the erasure register catches the rows."""3from datetime import timedelta45from lib import pipelines, retention67LEARNER, REQUEST = 3590, "erasure-0001"8catalog, graph = retention.open_platform()9retention.erase_everywhere(catalog, graph, LEARNER, REQUEST, min_age=timedelta(0))10register = [retention.register_entry(REQUEST, LEARNER)] # the request's ID and a keyed hash of the learner's ID11print("the erasure register's entry:", register[0]["request"], register[0]["learner"])12learners = catalog.load_table("crm.learners")13print("the learner's rows in crm.learners after the erasure:", retention.count(learners, retention.rows_of([LEARNER])))1415# the nightly reload: the application's export still holds the learner, since nobody erased it there16learners.overwrite(retention.crm_export())17# the pipelines that read crm.learners rebuild from the reloaded table18for name in ("learner_activity", "marketing_audience"):19 pipelines.run(catalog, name)20for table in ("crm.learners", "analytics.learner_activity", "marketing.audience"):21 print(f"the learner's rows in {table} after the nightly run:",22 retention.count(catalog.load_table(table), retention.rows_of([LEARNER])))2324# hashes each learner_id in every table and looks it up in the register, so no learner's ID is printed25for table, rows in retention.erased_rows(catalog, register).items():26 print(f"the check against the register, rows of erased learners in {table}:", rows)
python erased-learner-returns.pythe erasure register's entry: erasure-0001 c25d8a8b12426596f0c0b1ebfb890246b42ea535791f07256efd16fc6c2cb84b
the learner's rows in crm.learners after the erasure: 0
the learner's rows in crm.learners after the nightly run: 1
the learner's rows in analytics.learner_activity after the nightly run: 1
the learner's rows in marketing.audience after the nightly run: 0
the check against the register, rows of erased learners in analytics.learner_activity: 1
the check against the register, rows of erased learners in crm.learners: 1
Un borrado hecho solo en el almacén no dura. Después de él, crm.learners contiene 0 filas del alumno; tras la ejecución nocturna vuelve a tener 1, y analytics.learner_activity, reconstruida a partir de ella, tiene 1. marketing.audience solo se mantiene vacía porque el consentimiento del alumno vuelve retirado y las inscripciones con las que se une fueron borradas.
La comprobación que detecta esto mantiene un registro de borrados: para cada solicitud, su ID y un hash con clave (HMAC-SHA256) del ID del alumno borrado, y nada más. La clave es el secreto del proceso de borrado, guardado como la clave de seudonimización de la capa de cumplimiento en el capítulo 6, pero distinta, porque quien la tenga puede calcular el hash de cualquier ID de alumno y encontrar a quién nombra el registro. Después de cada carga, restauración y reconstrucción, lib.retention.erased_rows calcula el hash de cada learner_id en todas las tablas que tengan esa columna y lo busca, de modo que una restauración o un rellenado se verifica sin que el registro contenga el ID de nadie. Encuentra al alumno en analytics.learner_activity y crm.learners, y deja fuera billing.payments, cuyas filas conserva la excepción. El registro de auditoría del borrado, en el capítulo 8, contiene el mismo ID de solicitud y los mismos recuentos, nunca al alumno, de modo que el registro es el único lugar donde una solicitud se encuentra con un alumno, en forma de hash. Tratamos el hash con clave de un ID como dato seudonimizado, nunca anonimizado.
Regla práctica: Borra primero en el sistema de origen, o en la misma solicitud, y mantén un registro de hashes con clave de los ID borrados contra el que filtre cada carga y que verifique cada ejecución, con la clave guardada como secreto aparte de los datos. Trata una fila con un ID borrado como un incidente, igual que una filtración.
Otros fallos
- Las instantáneas y los archivos antiguos conservan datos "eliminados". Un trabajo de retención o de borrado que se detiene después de su eliminación deja todo legible mediante viaje en el tiempo, y en PyIceberg los archivos también permanecen tras la expiración. Ejecuta la expiración y la limpieza en el mismo trabajo, y después la lectura.
- Otro motor elimina mediante merge-on-read. PyIceberg lee los vectores de eliminación que escriben otros motores (notas de la versión). Las filas eliminadas de esa forma permanecen en sus archivos de datos hasta que la compactación los reescribe, y un archivo de eliminación puede conservar sus valores, ya que ambos tipos de archivo de eliminación pueden codificar los valores de las filas que borran (especificación de tablas Iceberg). Compacta los archivos afectados antes de la expiración y la limpieza, y lee también los archivos de eliminación.
- Las copias de seguridad conservan todo lo que borra la limpieza. Son uno de los puntos débiles que señala el informe del EDPB. Decide junto con quienes responden por las copias de seguridad cómo se borran o caducan, y regístralo con cada solicitud.
- Una tabla derivada que nadie borró. Un trabajo que no envía linaje escribe una copia que el plan no puede ver, como ocurre con la exportación sin instrumentar del capítulo 4. Ejecuta
lib.lineage.unaccountedantes de cada borrado. - Una tabla reconstruida pierde sus propiedades. Una canalización que elimina y vuelve a crear su tabla pierde la configuración de estadísticas generadas, y el siguiente borrado deja valores en sus manifiestos. Aplica las propiedades después de cada ejecución, o crea las tablas con ellas.
- Una columna renombrada pierde su configuración. En PyIceberg, la propiedad de métricas permanece bajo el nombre antiguo de la columna, así que tras un cambio de nombre el nuevo no tiene ninguna. Genera de nuevo las propiedades en cada cambio de esquema.
- Retención contada desde la fecha equivocada. Una regla que significa "después del cierre" pero cuenta desde la apertura borra antes de tiempo, y otra que cuenta desde una fecha de carga borra tarde. Guarda la fecha que la regla significa.
Lo que decidió este capítulo
- Las reglas de retención son configuración, aplicadas respecto de un día que se le indica al trabajo, nunca respecto del reloj. Cada plazo es una decisión propia de la plataforma, guardada en las reglas, y los tickets cerrados cuentan desde su apertura, porque la tabla no tiene
closed_at. - El consentimiento es un atributo que la política lee en el momento de la consulta; una retirada no borra nada, y las tablas construidas con un filtro de consentimiento se reconstruyen.
- Una supresión se planifica a partir del catálogo y del linaje: cada tabla con una columna
learner_id, y después cada tabla a la que llegue el linaje. - Las excepciones a la supresión son competencia del equipo jurídico, y se registran en
governance/retention.tomlcon sus motivos; el código conserva lo que ellos digan hasta que la regla de retención de la tabla le ponga fin. - Los commits registran identificadores de solicitud y nombres de reglas, nunca los valores de una persona.
- La expiración del libro lee la configuración de cada tabla, cosa que la de PyIceberg no hace, y una supresión comprueba cada tabla de su plan antes de borrar nada.
- La limpieza del libro elimina los archivos sin referencias, con una antigüedad mínima de 72 horas en producción.
- Los manifiestos no conservan valores de las columnas protegidas: modo de métricas
none, generado a partir de las clasificaciones. - Cada supresión termina con un escaneo de todos los archivos, en busca de los identificadores y de 15 caracteres de cada valor identificativo; sus recuentos son la prueba.
- El registro de supresiones guarda un hash con clave de cada identificador suprimido, que se comprueba después de cada carga, restauración y reconstrucción. La retención y la supresión se verifican por lo que queda: un escaneo tras cada supresión, un registro de hashes y reglas que cuentan desde el día que se le indica al trabajo. Un escaneo puede dar un resultado correcto mientras los datos sigan en algún lugar que no revisó, por eso el registro se vuelve a comprobar después de cada carga, restauración y reconstrucción.
Este capítulo, en esta edición
Edición 2026.11.31Ejemplos verificados el 19 de nov de 2026Superan la prueba 11 de 11 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.31.