Retenção, consentimento e eliminação

Cerca de 46 minutos min de leitura, com 11 exemplos em 13 seções.

Edição 2026.11.31 Exemplos aprovados em 19 de nov de 2026 108 de 108 exemplos passam O que mudou

Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros

Traduzido do livro em inglês, edição 2026.11.31. Leia o original

Ao final deste capítulo, você poderá manter as regras de retenção como configuração revisada, fazer com que a retirada de um consentimento altere a consulta seguinte e eliminar uma pessoa de todas as tabelas que receberam os dados dela. Você aplicará as regras a um dia que você informar, encontrará essas tabelas a partir da linhagem e manterá apenas o que a sua equipe jurídica tiver registrado como exceção. Você também removerá o que uma exclusão de linhas deixa para trás em uma tabela Iceberg, como snapshots antigos, arquivos não referenciados e estatísticas de colunas, e concluirá com uma varredura que lê todos os arquivos restantes e mostra que nenhum deles contém a pessoa.

A plataforma de aprendizado online que este livro governa mantém tudo desde o primeiro cadastro, em janeiro de 2024, em um único catálogo Iceberg: cada chamado de suporte e cada evento de aprendizado, com o endereço IP de onde ele veio. Nada define por quanto tempo cada um deles deve permanecer. O aluno 3590 retira o consentimento para receber e-mails de marketing e, algumas semanas depois, pede à plataforma que elimine os seus dados. A primeira ação deve alterar o que o marketing vê a partir da consulta seguinte. A segunda não deve deixar nenhuma cópia do aluno em lugar algum: nem nas tabelas construídas a partir dos dados dele, nem nas versões antigas de cada tabela que o Iceberg mantém de propósito.

Três termos nomeiam os assuntos do capítulo. Retenção é por quanto tempo a plataforma mantém cada tipo de dado. Consentimento é a concordância de uma pessoa com um uso específico de seus dados, como o e-mail de marketing, e que ela pode retirar. Eliminação é remover os dados de uma pessoa mediante solicitação. O capítulo acrescenta duas coisas ao código compartilhado do livro: as regras de retenção da plataforma, em governance/retention.toml, e o módulo lib.retention, que aplica essas regras, planeja e executa uma eliminação, limpa e verifica os arquivos depois dela e mantém o registro de eliminações. Ele usa lib.lineage, do capítulo 4, para descobrir para onde foram os dados de um aluno, e as classificações em lib.metadata, do capítulo 2. Cada exemplo roda o PyIceberg 0.12.0 em um catálogo local.

Mantenha as regras de retenção em um arquivo revisado

Última alteração na edição 2026.11.27

Uma regra de retenção indica por quanto tempo um tipo de dado é mantido, a partir de qual data o prazo começa a contar e a quais linhas ela se aplica. O Regulamento Geral de Proteção de Dados (GDPR) da União Europeia enuncia o princípio como limitação de armazenamento: dados pessoais devem ser "mantidos de forma que permita a identificação dos titulares dos dados por não mais tempo do que o necessário para as finalidades para as quais os dados pessoais são tratados" (Artigo 5(1)(e)). Seu Considerando 39 pede ao controlador que estabeleça prazos para a eliminação ou para uma revisão periódica (GDPR). O catálogo de controles de segurança e privacidade do NIST descreve a mesma tarefa, pedindo que as informações sejam descartadas, destruídas ou apagadas quando seu período de retenção terminar (controle SI-12(3)) (NIST SP 800-53 Rev. 5). Os responsáveis pela plataforma e os advogados decidem por quanto tempo é necessário; o código aplica o que eles decidem, sempre.

Isso sugere regras como configuração, revisadas da mesma forma que as políticas de acesso, e um código que as aplique a um dia que lhe é dado, não ao relógio. Um job que lê o relógio apaga linhas diferentes conforme o momento em que é executado: um teste não consegue fixar seu resultado, e uma nova execução após uma falha pode apagar mais do que a execução que substitui.

As regras da plataforma estão em governance/retention.toml. Os períodos são escolhas da própria plataforma para o caso deste livro, não aconselhamento 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"

Tickets fechados são mantidos por dois anos, eventos por um ano e pagamentos por 3,650 dias, um valor provisório no qual o plano de eliminação se apoia. A regra de tickets deveria contar a partir de quando um ticket foi fechado, mas a tabela registra apenas opened_at; assim, um ticket aberto há 25 meses e fechado na semana passada é apagado imediatamente. A plataforma convive com isso porque acrescentar uma coluna closed_at é uma mudança da equipe de suporte, não da equipe da plataforma; até que ela a faça, a regra erra para o lado de apagar cedo. lib.retention.due transforma uma regra e um dia em um filtro Iceberg. Contadas a partir do "hoje" do livro, 1 de outubro de 2026, e 90 dias depois, as linhas selecionadas por cada regra ficam assim:

retention-rules-due.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""The rows each retention rule makes due on the book's today and 90 days later, counted against the day the job is given.The `rows due` lines are the counts the prose gives."""from datetime import timedeltafrom lib import retentionfrom lib.catalog import open_catalogfrom lib.platform import TODAYrules = retention.rules()["tables"]catalog = open_catalog(sorted(rules))for name, rule in sorted(rules.items()):    state = rule.get("only_when")    print(f"{name}: kept {rule['keep_days']} days from {rule['counted_from']}"          + (f", once {state['column']} is {state['equals']}" if state else ""))# the book's today, then 90 days later: the day is passed in, never read from the clockfor day in (TODAY, TODAY + timedelta(days=90)):    for name, rule in sorted(rules.items()):        table = catalog.load_table(name)        # the earliest date kept: keep_days before the day        print(f"{name} on {day}, kept from:", retention.cutoff(rule, day))        print(f"{name} on {day}, rows due:", f"{retention.count(table, retention.due(rule, day)):,}")        print(f"{name} on {day}, rows in the table:", f"{retention.count(table):,}")
Saídapython retention-rules-due.py
billing.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

As linhas vencidas dependem do dia informado e dos dados, e de mais nada. Em 1 de outubro de 2026, a regra de eventos mantém eventos a partir de 2025-10-01, então 9,060 dos 100,000 eventos estão vencidos; em 30 de dezembro, 90 dias depois, são 15,545. A regra de tickets torna 58 dos 2,000 tickets vencidos em 1 de outubro, todos fechados e abertos há mais de dois anos. Em 30 de dezembro, ela torna 111 vencidos. A regra de pagamentos torna 0 dos 17,562 pagamentos vencidos em 1 de outubro e 0 em 30 de dezembro.

Regra prática: Mantenha o período de retenção de cada tabela, a coluna a partir da qual ele conta e o estado em que a linha deve estar, em um arquivo revisado, e aplique-o a um dia que o agendador repassa, nunca ao relógio. Conte a partir da data que a regra pretende. Quando a tabela não registra essa data, como os tickets da plataforma não registram quando foram fechados, peça ao responsável pela tabela que acrescente a coluna, em vez de deixar a regra contar para sempre a partir de outra data, e indique no arquivo da regra para que lado ela erra até lá.

Remova linhas expiradas com deletes de linhas

Última alteração na edição 2026.11.27

Com as regras em um arquivo, o job de retenção remove o que elas determinam. Os escritores do Iceberg removem linhas de uma de duas maneiras, definidas pela propriedade de tabela write.delete.mode, cujo valor padrão é copy-on-write (configuração do Iceberg). Copy-on-write reescreve cada arquivo de dados afetado sem as linhas removidas. Merge-on-read deixa o arquivo de dados intacto e grava um arquivo de delete ao lado dele. A especificação tem dois tipos de arquivo de delete: position deletes, que marcam uma linha pelo seu arquivo de dados e pela sua posição (um deletion vector, em tabelas de versão 3 ou superior), e equality deletes, que a marcam pelos valores de uma ou mais colunas (especificação de tabelas do Iceberg). O PyIceberg 0.12.0 implementa Table.delete sempre com copy-on-write: com merge-on-read definido, ele emite um aviso de que merge-on-read ainda não é suportado e reescreve os arquivos mesmo assim (código-fonte). Em qualquer dos casos, um delete é um commit, um novo snapshot, e o snapshot anterior continua existindo.

lib.retention.apply remove, para cada regra, as linhas que due retorna para o dia recebido, e registra a tabela da regra e o dia no resumo do snapshot do commit, para que o próprio histórico da tabela informe o motivo da remoção. Duas execuções para 1º de outubro de 2026, lidas agora e por viagem no tempo, mostram o que um delete deixa para trás. Em seguida, a expiração dos snapshots antigos por idade fica por último:

apply-retention.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""Applies the retention rules for the book's today as Iceberg row deletes, which leave the old rows in older snapshots.The rerun line is zero, and the time-travel lines show the rows the snapshot before each delete still returns."""from datetime import datetime, timedelta, timezonefrom lib import retentionfrom lib.catalog import open_catalogfrom lib.platform import TODAYrules = retention.rules()["tables"]catalog = open_catalog(sorted(rules))# each table's snapshot from before the deletes, which the time-travel lines readbefore = {name: catalog.load_table(name).current_snapshot().snapshot_id for name in rules}deleted = retention.apply(catalog, TODAY)for name, rows in deleted.items():    print(f"{name}, rows deleted:", f"{rows:,}")print("rows deleted by running again for the same day:", sum(retention.apply(catalog, TODAY).values()))for name in (name for name, rows in deleted.items() if rows):    rule, table = rules[name], catalog.load_table(name)    summary = table.current_snapshot().summary    print(f"{name}, snapshots:", " then ".join(s.summary.operation.value for s in table.snapshots()))    # copy-on-write writes the rows it keeps again as new records, which is what this line counts    print(f"{name}, rows written again to delete the others:", f"{int(summary['added-records']):,}")    print(f"{name}, the commit records:", summary["retention-rule"], "on", summary["retention-day"])    rows_due = retention.due(rule, TODAY)    print(f"{name}, rows due, read now:", f"{retention.count(table, rows_due):,}")    print(f"{name}, rows due, read by time travel:", f"{retention.count(table, rows_due, before[name]):,}")    # Snapshots carry real commit times, so their age is measured on the clock, by the table's own setting.    print(f"{name}, snapshots expired by age today:", retention.expire_by_age(table))    # six days on, the snapshot from before the delete is older than the table's five-day setting    later = datetime.now(timezone.utc) + timedelta(days=6)    print(f"{name}, snapshots expired by age six days later:", retention.expire_by_age(table, later))
Saídapython apply-retention.py
billing.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

Uma nova tentativa de execução é inofensiva: uma segunda execução para o mesmo dia removeu 0 linhas e não fez nenhum commit. A primeira execução removeu 9,060 eventos, 58 chamados e 0 pagamentos. Cada tabela alterada passou de um snapshot de append para um snapshot de overwrite, e o resumo mostra o custo do copy-on-write: para remover os eventos antigos, o PyIceberg regravou as outras 90,940 linhas, porque a tabela é um único arquivo sem partições. Particionada por mês de occurred_at, a tabela permitiria que o mesmo delete descartasse arquivos inteiros, o que Table.delete faz quando todas as linhas de um arquivo correspondem. No PyIceberg 0.12.0, gravar uma tabela particionada por mês exige o extra pyiceberg-core, que os exemplos deste livro não instalam.

Um delete não remove as linhas dos snapshots anteriores da tabela. Lida no estado atual, learning.events contém 0 linhas além da retenção, mas, lida por viagem no tempo, o snapshot anterior ao delete ainda retorna todas as 9,060 linhas, endereços IP incluídos, e o arquivo Parquet que as contém continua no disco. lib.retention.expire_by_age expira snapshots mais antigos que a própria history.expire.max-snapshot-age-ms da tabela, cinco dias aqui, medidos pelo relógio. Ele expira 0 snapshots de learning.events logo após o delete, e 1 seis dias depois. O job de retenção só está concluído quando os snapshots antigos são expirados e os arquivos que nenhum snapshot referencia são removidos: a mesma limpeza que uma eliminação exige.

Regra prática: Aplique a retenção como deletes de linhas do Iceberg, uma regra por vez, e registre a regra e o dia no resumo do snapshot de cada commit. Torne o job idempotente para um determinado dia. Particione as tabelas grandes pela coluna a partir da qual uma regra conta, para que os deletes descartem arquivos inteiros em vez de reescrevê-los; no PyIceberg, instale o extra pyiceberg-core para gravá-las. Dê o job por concluído somente quando os snapshots antigos estiverem expirados e os arquivos deles removidos.

Última alteração na edição 2026.11.27

Retenção remove linhas pela idade. O consentimento altera quem pode usá-las, e retirar o consentimento não é o mesmo evento que pedir o apagamento, por isso o código da plataforma trata os dois como caminhos separados. O Artigo 7(3) do Regulamento Geral sobre a Proteção de Dados (RGPD) da União Europeia diz: "O titular dos dados tem o direito de retirar o seu consentimento a qualquer momento. A retirada do consentimento não compromete a licitude do tratamento efetuado com base no consentimento previamente dado" (RGPD). O Artigo 17(1)(b) do mesmo regulamento torna a retirada um dos fundamentos para o apagamento, mas somente quando não resta nenhum outro fundamento jurídico para o tratamento. No código, a retirada altera um atributo; o apagamento elimina linhas.

Na plataforma, o consentimento é um atributo dos dados que a política de acesso lê, conforme o capítulo 5 configurou: o filtro de linhas do marketing mantém apenas os aprendizes cujo marketing_consent é verdadeiro, e o filtro do assistente do curso mantém apenas as avaliações cujos autores têm ai_training_consent verdadeiro. Assim, a retirada não exige nenhuma mudança na política. O CRM, a aplicação na qual os aprendizes gerenciam suas contas, sincroniza o novo valor em crm.learners, e a próxima consulta que o marketing executar, pela camada de imposição (enforcement) que o capítulo 6 constrói para reescrever cada consulta, retorna um aprendiz a menos.

Retire o consentimento de marketing do aprendiz 3590 e, em seguida, leia o que o marketing vê e o que as tabelas contêm antes da retirada, depois dela e depois que o pipeline de marketing for executado novamente.

A retirada passou a valer na consulta seguinte e não removeu nada: o marketing vê 1,861 aprendizes antes dela, entre eles o aprendiz 3590, e 1,860 depois dela, sem o aprendiz 3590. O filtro de linhas do marketing continua [{"column": "marketing_consent", "equals": true}, {"column": "status", "equals": "active"}], e crm.learners ainda armazena 5,000 linhas. Nada foi apagado; a conta, as matrículas e o histórico do aprendiz permanecem como estavam.

A cópia é o problema. marketing.audience, a lista que um pipeline de marketing monta todas as noites, aplica o filtro de consentimento no momento da construção, e a política dá ao marketing essa tabela sem um filtro de consentimento próprio. Depois da retirada, ela ainda contém 1 linha para o aprendiz 3590. Enquanto alguém não classificar as colunas da tabela, a política as oculta para todos os leitores; quando alguém o fizer, como o capítulo 4 propõe, uma campanha enviada a partir da tabela antes da sua próxima construção alcança alguém que disse não. Somente quando o pipeline for executado novamente a contagem cai para 0. Um corpus de treinamento também é construído com um filtro de consentimento, e o capítulo 9 verifica cada construção contra o consentimento atual antes de treinar com ela.

Uma coluna de verdadeiro ou falso também diz pouco: ai_training_consent é nulo para todos que se cadastraram antes de a plataforma perguntar, e falso pode significar recusado ou retirado. O Data Privacy Vocabulary, um relatório de um Grupo Comunitário do W3C e não um padrão, nomeia os estados em que um consentimento pode estar, entre eles dado, recusado, retirado, expirado e desconhecido (DPV 2.3).

Regra prática: Mantenha o consentimento onde a consulta é executada: em uma tabela única que o sistema usado pelo aprendiz mantém atualizada, lida pela política como filtro de linhas, de modo que uma retirada mude a próxima consulta e não apague nada. Quando os advogados da plataforma decidirem que a retirada também é fundamento para o apagamento, encaminhe-a também pelo caminho de apagamento. Reconstrua toda tabela criada com um filtro de consentimento sempre que o consentimento mudar, ou dê aos seus leitores o mesmo filtro. Registre cada consentimento como um estado e o momento em que ele mudou, e derive do estado o atributo de verdadeiro ou falso que a política lê, considerando desconhecido como não dado.

Planeje um apagamento a partir da linhagem

Última alteração na edição 2026.11.27

Uma retirada define um atributo; um apagamento precisa encontrar a pessoa em todos os lugares. O artigo 17(1) do GDPR dá à pessoa o direito de ter seus dados apagados sem demora injustificada, pelos motivos que ele lista (GDPR). A plataforma trata um pedido como alcançando cada cópia, então sua primeira tarefa, uma questão de engenharia, é uma lista em duas metades de onde estão os dados da pessoa. As tabelas de origem que contêm o ID de um aprendiz vêm do catálogo: o capítulo 2 decidiu que toda tabela com uma coluna learner_id faz parte de todo apagamento, qualquer que seja a sua classificação. As tabelas construídas a partir delas vêm da linhagem: a varredura do grafo de colunas do capítulo 4, executada a partir de cada tabela de origem, alcança cada tabela cujas linhas ela moldou.

Alguns dados permanecem. O artigo 17(3) do mesmo regulamento define onde o apagamento não se aplica, na medida em que o tratamento seja necessário: entre seus cinco pontos, para o cumprimento de uma obrigação legal sob o direito da União ou de um Estado-Membro a que o controlador esteja sujeito (GDPR). Se uma exceção se aplica, a qual tabela e por quanto tempo é decisão da equipe jurídica, nunca do código. O código concentra essa decisão em um único lugar, governance/retention.toml, onde a equipe jurídica registra cada exceção com seu motivo. O motivo do livro é um marcador de posição, porque não decidimos nenhuma questão 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

Um apagamento mantém as linhas de uma tabela excetuada até que a regra de retenção da tabela as apague, e apaga de imediato as colunas que erase_columns lista nelas: aqui, o número completo do cartão, que os metadados da plataforma descrevem como "Should not be stored at all". lib.retention.exceptions recusa uma exceção sem motivo, ou uma para uma tabela que nenhuma regra encerra.

Encontrar uma tabela derivada não é o mesmo que encontrar as linhas do aprendiz nela. lib.retention.plan examina as arestas de linhagem que entram em cada tabela que a varredura alcança, buscando uma coluna copiada sem alteração, uma aresta IDENTITY nos termos do OpenLineage, a partir do ID do aprendiz ou do ID de uma de suas linhas, como uma avaliação. Se houver uma, o plano apaga por essa coluna. Se não houver nenhuma, as linhas do aprendiz apenas moldaram a tabela, e o plano executa de novo o job da tabela depois que as origens forem apagadas. O plano lê a plataforma como o pedido a encontra, semanas depois da retirada: crm.learners guarda o consentimento retirado do aprendiz 3590, e os quatro pipelines do capítulo 4, que constroem as tabelas de analytics, marketing e IA, foram executados desde então, com sua linhagem registrada.

O plano para o aprendiz 3590 imprime uma linha por etapa, cada tabela com o que ela faz ali:

erasure-plan.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · phonenumbers 9.0.43 · presidio-analyzer 2.2.366 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 · tldextract 5.4.0 Aprovado
"""The steps that erase one learner: the tables with their learner_id column, then the tables lineage says their rows reach,with 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."""from lib import pii, retentionLEARNER = 3590catalog, graph = retention.open_platform()           # weeks after the learner withdrew marketing consentsteps = retention.plan(catalog, graph, LEARNER)for step in steps:    # no column is copied from the learner here: the table's own job runs again once its sources are erased    if step.column is None:        print(f"{step.table}: run {retention.job_for(step.table)} again")    elif step.kept:        print(f"{step.table}: keep, under an exception, and erase {', '.join(step.cleared)}")    else:        print(f"{step.table}: delete where {step.column} in {list(step.values)}"              + (f", a copy of {step.via}" if step.via else ""))print("tables in the plan:", len(steps))# a step with a column and no lineage edge came from the table's own learner_id columnprint("tables found by their learner_id column:", sum(1 for step in steps if step.column and not step.via))# found by lineage: a copy of another table's ID, or a rebuild, because the learner's rows only shaped the tableprint("tables found by lineage:", sum(1 for step in steps if step.via or step.column is None))for step in (step for step in steps if step.kept):    print(f"the reason recorded for {step.table}:", step.kept)theirs = retention.rows_of([LEARNER])for name in ("billing.payments", "marketing.audience"):    print(f"the learner's rows in {name}:", retention.count(catalog.load_table(name), theirs))# the values the scan will search for, noted before any row is deletedfound = retention.traces(catalog, steps, LEARNER)# The phone number is printed through lib.pii.masked, which keeps its shape and its last four digits.print("the learner's identifying values, as the scan searches for them:", pii.masked(", ".join(found.texts)))# rows the plan keeps, in any string column, whose text holds one of those valuesnamed = retention.mentions(catalog, steps, found)print("rows the plan doesn't delete whose text names the learner:", sum(named.values()))
Saídapython erasure-plan.py
billing.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

O plano visita 10 tabelas: 6 tabelas de origem com uma coluna learner_id, e 4 que a linhagem acrescenta. Ele mantém os pagamentos do aprendiz (2) sob a exceção. Os passos são decididos por colunas e linhagem, não por linhas, então o plano lista duas tabelas que não guardam nenhuma linha do aprendiz: support.tickets, já que o aprendiz 3590 nunca abriu um chamado, e marketing.audience, que contém 0, porque o pipeline a reconstruiu depois da retirada. ai.review_corpus não tem nenhuma coluna learner_id, mas a linhagem diz que sua coluna review_id é uma cópia IDENTITY de learning.reviews.review_id, então o plano apaga a avaliação do aprendiz por esse ID. analytics.course_performance guarda apenas contagens e médias por curso, então o plano a reconstrói a partir das origens apagadas. Reconstruir custa uma execução de pipeline, então o código não precisa decidir se uma média que um dia contou o aprendiz ainda é dado dele.

Um texto pode nomear uma pessoa em linhas que o plano não apaga, como o chamado de outro aprendiz. O exemplo busca em cada coluna de texto os valores identificadores que governance/retention.toml lista, e encontra 0 dessas linhas. A busca casa os primeiros 15 caracteres de cada valor, em minúsculas, em qualquer posição do texto: aqui •••-•••-5880 x•, 87199 jacob rad, alexa reed, alexa590@post.e, impresso com o número de telefone mascarado, cortado em 15 pelo motivo que a verificação final explica. Um nome digitado de outra forma, ou um número de telefone sem separadores, exige os detectores do capítulo 3.

Regra prática: Planeje todo apagamento a partir do catálogo e do grafo de linhagem, não de uma lista mantida por alguém: toda tabela com a coluna de ID da pessoa, depois toda tabela que a linhagem diz que as linhas dela alcançam. Apague de uma tabela derivada por uma coluna que a linhagem mostra ser cópia sem alteração de um ID, e reconstrua as tabelas derivadas que as linhas da pessoa apenas moldaram. Guarde as exceções em configuração, escritas pela equipe jurídica com seus motivos, e deixe o plano lê-las e mostrá-las; nunca deixe o código decidir uma. Execute primeiro a verificação de tabelas que nenhum job de linhagem explica, do capítulo 4, porque o plano não consegue alcançar uma cópia que a linhagem não mostra.

Apague as linhas que o plano lista

Última alteração na edição 2026.11.27

O plano indica onde estão os dados do aprendiz 3590, e lib.retention.erase os executa na ordem do plano. Ele apaga as linhas de cada etapa com Table.delete, começando pelas fontes, grava novamente as linhas que uma exceção mantém, com as colunas dela vazias, e executa o job de cada tabela que o plano reconstrói depois que as fontes estão prontas. Cada commit registra o ID da requisição, erasure-0001, no resumo do snapshot. O Iceberg mantém um resumo nos arquivos de metadados da tabela depois que o snapshot expira, em todos eles por padrão, ou apenas os últimos write.metadata.previous-versions-max (100 por padrão) quando write.metadata.delete-after-commit.enabled está definido (Manutenção do Iceberg, Configuração do Iceberg). Por isso, o resumo guarda apenas o ID da requisição, que o registro de apagamentos associa a um hash com chave do ID do aprendiz, e nunca o e-mail do aprendiz.

O apagamento é executado sobre o plano do aprendiz 3590 sob um único ID de requisição. Ler crm.learners e learning.events agora e por viagem no tempo mostra o que ele deixa:

erase-learner.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""Carries out the erasure plan with Iceberg row deletes. The current snapshots no longer hold the learner, but the snapshotsbefore them still do, and the `read by time travel` lines show it."""from lib import retentionLEARNER = 3590catalog, graph = retention.open_platform()steps = retention.plan(catalog, graph, LEARNER)# each table's snapshot from before the erasure, which the time-travel lines readbefore = {step.table: catalog.load_table(step.table).current_snapshot().snapshot_id for step in steps}done = retention.erase(catalog, steps, "erasure-0001")       # the request's ID goes into every commit's summaryfor table, rows in done.items():    # a rebuilt table reports 'rebuilt' rather than a count of rows    print(f"{table}, rows deleted:" if rows != "rebuilt" else f"{table}:", rows)print("tables one row was deleted from:", ", ".join(table for table, rows in done.items() if rows == 1))theirs = retention.rows_of([LEARNER])payments = catalog.load_table("billing.payments").scan(row_filter=theirs).to_arrow()print("billing.payments, the learner's rows kept:", payments.num_rows)# the exception erases card_number to null, so the values that are not null are the card numbers leftprint("billing.payments, card numbers left in them:", payments.num_rows - payments["card_number"].null_count)for name in ("crm.learners", "learning.events"):    table = catalog.load_table(name)    print(f"the learner's rows in {name}, read now:", retention.count(table, theirs))    print(f"the learner's rows in {name}, read by time travel:", retention.count(table, theirs, before[name]))summary = catalog.load_table("crm.learners").current_snapshot().summary# copy-on-write writes the rows it keeps again as new records, so this counts every other row of the fileprint("crm.learners, rows written again to delete one:", f"{int(summary['added-records']):,}")print("crm.learners, the commit records:", summary["erasure-request"])# snapshots of tables the plan deleted from (not rebuilt, not kept) that still return a row the erasure deletedholding = [(table, snapshot) for step in steps if step.column is not None           for table in [catalog.load_table(step.table)] for snapshot in table.snapshots()           if not step.kept and retention.count(table, retention.rows(step), snapshot.snapshot_id)]print("snapshots that still hold the rows the erasure deleted:", len(holding))print("of them current:", sum(snapshot == table.current_snapshot() for table, snapshot in holding))
Saídapython erase-learner.py
billing.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

O apagamento retirou o aprendiz de todas as tabelas do plano que tinham algum dado dele. Ele apagou 19 eventos do aprendiz, 2 matrículas, e uma linha de cada uma de crm.learners, learning.reviews, analytics.learner_activity, ai.review_corpus. Não apagou nada de support.tickets e marketing.audience, que não tinham dados dele, e reconstruiu analytics.course_performance.

billing.payments mantém 2 pagamentos do aprendiz, com 0 números de cartão deixados neles. Lidas agora, crm.learners tem 0 linhas do aprendiz. Lida por viagem no tempo até o snapshot anterior ao apagamento, a tabela retorna 1, com nome, e-mail, telefone e endereço, e learning.events retorna da mesma forma todos os 19 eventos do aprendiz.

Para apagar uma linha de crm.learners, o PyIceberg gravou as outras 4,999 em um novo arquivo, como faz o copy-on-write, e o arquivo antigo, com o aprendiz nele, pertence ao snapshot anterior.

Entre as tabelas do plano, 6 snapshots ainda guardam as linhas que o apagamento removeu, e 0 deles são atuais. Para isso servem os snapshots: o leitor pode voltar a qualquer um deles. No caso de um apagamento, isso significa que a exclusão retirou o aprendiz da tabela, mas não do armazenamento.

Regra prática: Execute um apagamento como exclusões de linhas na ordem do plano, e registre apenas um ID de requisição em cada commit, nunca um valor da pessoa. Trate a exclusão como o primeiro de três passos: os snapshots anteriores a ela ainda guardam a pessoa, e quem tiver permissão para viajar no tempo pode lê-los até que sejam expirados.

Expirar snapshots pelas próprias configurações da tabela

Última alteração na edição 2026.11.27

Depois dos deletes da remoção, as linhas do aprendiz 3590 continuam existindo nos snapshots anteriores a eles. A especificação do Iceberg diz que os snapshots expiram para que os arquivos de dados que eles removeram ou substituíram possam ser apagados fisicamente (especificação de tabelas do Iceberg). Cada tabela define como nas suas propriedades (configuração do Iceberg): gc.enabled permite a coleta de lixo, como expirar snapshots e remover arquivos órfãos; history.expire.min-snapshots-to-keep é a quantidade de snapshots a manter, não importa quão antigos sejam; e history.expire.max-snapshot-age-ms é a idade a partir da qual os demais podem ser descartados. Na biblioteca Java do Iceberg, expirar snapshots com regularidade apaga arquivos de dados não utilizados (manutenção do Iceberg).

O PyIceberg 0.12.0 faz menos. Seu table.maintenance.expire_snapshots() efetua uma única alteração, que remove os snapshots dos metadados da tabela e não apaga nenhum arquivo (código-fonte), embora sua documentação o apresente como forma de "limpar os metadados da tabela e reduzir os custos de armazenamento" (API do PyIceberg). Nada nele lê gc.enabled, e apenas sua ferramenta de linha de comando lê as configurações history.expire. Uma issue pede que a expiração também apague arquivos (issue 2604). Duas cópias de crm.learners têm cada uma 3 snapshots: a carga e dois deletes. Uma cópia tem gc.enabled=false, a outra history.expire.min-snapshots-to-keep=3, e cada uma é expirada de duas formas: por idade com o PyIceberg, older_than o horário atual, e com lib.retention.expire, que lê antes as duas configurações.

expiry-ignores-table-settings.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""PyIceberg's snapshot expiry ignores two of the table's own settings, gc.enabled and min-snapshots-to-keep, so it expiressnapshots they would keep. The book's expiry reads both first, and the `left by PyIceberg's expiry` lines show the difference."""from datetime import datetime, timezonefrom pyiceberg.expressions import EqualTofrom lib import retentionfrom lib.catalog import open_catalogdef learners_with(settings: dict):    """crm.learners with three snapshots: the load, then two deletes."""    table = open_catalog(["crm.learners"]).load_table("crm.learners")    with table.transaction() as transaction:        transaction.set_properties(settings)    # two deletes, so there are snapshots from before them for the expiry to consider    for learner in (3590, 3591):        table.delete(EqualTo("learner_id", learner))    return tablefor settings in ({"gc.enabled": "false"}, {"history.expire.min-snapshots-to-keep": "3"}):    setting = ", ".join(f"{key}={value}" for key, value in settings.items())    table = learners_with(settings)    print(f"{setting}, snapshots:", len(table.snapshots()))    try:        print(f"{setting}, the book's expiry expires:", retention.expire(table))    except retention.RetentionError as error:        print(f"{setting}, the book's expiry refuses:", error)    # PyIceberg's expiry by age, as of now: it reads neither setting    table.maintenance.expire_snapshots().older_than(datetime.now(timezone.utc)).commit()    print(f"{setting}, snapshots left by PyIceberg's expiry:", len(table.snapshots()))
Saídapython expiry-ignores-table-settings.py
gc.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

A expiração do PyIceberg ignora as duas configurações. Ela deixou 1 dos 3 snapshots da primeira tabela, e 1 dos da segunda. older_than expira todo snapshot mais antigo que o horário informado, exceto os que um branch ou uma tag apontam, aqui apenas o atual.

A expiração do livro recusou a primeira tabela, crm.learners has gc.enabled=false, which turns off garbage collection for the table, e expirou 0 snapshots da segunda. Um proprietário define essas propriedades por razões que o código de expiração não consegue ver, e no PyIceberg elas são apenas uma recomendação.

Numa remoção, as duas configurações significam que a tarefa não pode terminar: uma tabela que mantém um snapshot anterior ao delete ainda guarda a pessoa. Uma tarefa que parasse nessa tabela já teria apagado linhas das tabelas anteriores e deixado as demais sem expirar, por isso a verificação deve vir antes do primeiro delete. lib.retention.erase_everywhere executa lib.retention.blocked em todas as tabelas do plano antes de tudo: coleta de lixo desligada, mais de um snapshot a manter, ou um branch ou tag além de main. Se alguma tabela falhar, a tarefa se recusa a começar e nomeia todas essas tabelas.

Aqui crm.learners tem a coleta de lixo desligada, e learning.events mantém três snapshots. Em seguida, a tarefa e a varredura são executadas:

erasure-refuses-to-start.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""The erasure job checks every table in its plan before it changes any, and refuses to start when a table's own settingswould keep the learner. The scan still runs, from the traces the refusal carries, and finds the learner in the files."""from datetime import timedeltafrom lib import retentionLEARNER = 3590catalog, graph = retention.open_platform()# each setting stops expiry from removing the snapshot from before the delete: garbage collection off, or three snapshots keptfor name, settings in (("crm.learners", {"gc.enabled": "false"}),                       ("learning.events", {"history.expire.min-snapshots-to-keep": "3"})):    with catalog.load_table(name).transaction() as transaction:        transaction.set_properties(settings)# every table's current snapshot, to count the tables the job changesbefore = {name: catalog.load_table(name).current_snapshot().snapshot_id for name in retention.tables(catalog)}try:    # min_age of zero: one writer and nothing in flight, so no file needs a minimum age to be safe to sweep    steps, found, done = retention.erase_everywhere(catalog, graph, LEARNER, "erasure-0001", min_age=timedelta(0))except retention.ErasureRefused as refusal:    for name, why in refusal.tables.items():        print(f"the job refuses, because of {name}:", why)    found = refusal.found# a table the job changed has a new current snapshotprint("tables the job changed:", sum(catalog.load_table(name).current_snapshot().snapshot_id != snapshot                                     for name, snapshot in before.items()))report = retention.scan(catalog, found)print("tables whose files hold the learner:", sum(1 for _, holding in report.values() if holding))print("files holding the learner:", sum(holding for _, holding in report.values()))
Saídapython erasure-refuses-to-start.py
the 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

A tarefa se recusa. Ela nomeia as duas tabelas, crm.learners porque gc.enabled=false turns off garbage collection for the table, e learning.events porque history.expire.min-snapshots-to-keep=3 keeps the snapshot from before the delete, e 0 tabelas foram alteradas.

A varredura é executada de qualquer forma, a partir dos rastros que a recusa carrega, e encontra o aprendiz em 8 arquivos distribuídos por 7 tabelas. Uma pessoa então decide junto com os proprietários das tabelas, em vez de o código sobrescrever a configuração de um proprietário.

Regra prática: Expire os snapshots por meio de uma função própria que leia gc.enabled e as configurações history.expire antes de expirar qualquer coisa, e que se recuse quando a coleta de lixo estiver desligada, porque a expiração do PyIceberg não lê nenhuma das duas; verifique novamente a cada versão do PyIceberg lançada. Antes que uma remoção apague qualquer coisa, verifique da mesma forma cada tabela do seu plano, e recuse a remoção inteira quando uma delas manteria a pessoa. Numa remoção, expire todo snapshot anterior ao delete. Para retenção, expire por idade, como history.expire.max-snapshot-age-ms indica, medida pelo relógio, já que os snapshots carregam horários reais de commit.

Remova os arquivos que nenhum snapshot referencia

Última alteração na edição 2026.11.31

Depois que os snapshots antigos forem expirados, os arquivos que só eles referenciavam ficam sem referência. Um arquivo sem referência, que o Iceberg chama de órfão, está sob a localização da tabela, mas não aparece nos metadados de nenhum snapshot. A biblioteca Java do Iceberg os remove em uma ação separada, e alerta que remover arquivos órfãos com um intervalo de retenção menor que o tempo previsto para a conclusão de qualquer escrita é perigoso; seu intervalo padrão é de 3 dias (manutenção do Iceberg). O PyIceberg 0.12.0 não tem essa ação. Suas notas de versão não listam nenhuma (notas de versão). A issue que pedia uma foi fechada pelo bot de issues inativas (stale bot) do projeto, marcada como não planejada (issue 1200). Dois pull requests que adicionavam uma foram fechados sem serem mesclados (1958, 3358). Sua única chamada que apaga arquivos de dados é purge_table, que apaga a tabela inteira (código-fonte).

Por isso, lib.retention os remove por conta própria, a partir do que as tabelas de metadados que o PyIceberg expõe como table.inspect indicam que a tabela referencia. lib.retention.referenced reúne os arquivos de metadados, atuais e registrados no log, a lista de manifestos de cada snapshot, cada manifesto (um manifesto lista os arquivos de dados, com as estatísticas de colunas de cada arquivo), cada arquivo de dados e de exclusão ativo em qualquer snapshot, e quaisquer arquivos de estatísticas. Todo outro arquivo sob a localização da tabela não tem referência, e lib.retention.sweep apaga os que são mais antigos que a idade mínima que quem chama passa. governance/retention.toml define essa idade em 72 horas, o padrão do Java, e lib.retention.min_file_age a lê. Após o apagamento, as tabelas do plano são expiradas, varridas com essa idade e depois sem idade mínima, e cada arquivo é verificado em busca do aprendiz:

sweep-unreferenced-files.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""After the erasure, expire the old snapshots, then remove the files no snapshot references. PyIceberg's expiry deletes nofile 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."""from datetime import timedeltafrom lib import retentionLEARNER = 3590catalog, graph = retention.open_platform()steps = retention.plan(catalog, graph, LEARNER)found = retention.traces(catalog, steps, LEARNER)retention.erase(catalog, steps, "erasure-0001")tables = [catalog.load_table(step.table) for step in steps]print("snapshots expired:", sum(retention.expire(table) for table in tables))print("files under the plan's tables:", sum(len(retention.files_under(table.location())) for table in tables))print("files no metadata references:", sum(len(retention.unreferenced(table)) for table in tables))print("files holding the learner, after expiry:", sum(held for _, held in retention.scan(catalog, found).values()))# the configured minimum age, 72 hours, from governance/retention.tomlprint("files swept with the configured minimum age:", sum(retention.sweep(t, retention.min_file_age()) for t in tables))# One writer, nothing in flight: no file is too young to remove, so the examples sweep with no minimum age.print("files swept with no minimum age:", sum(retention.sweep(table, timedelta(0)) for table in tables))print("files holding the learner, after the sweep:", sum(held for _, held in retention.scan(catalog, found).values()))for table in tables:    # every manifest entry, including those of deleted files, with the bounds it keeps for the email column    entries = table.inspect.entries()    for status, metrics in zip(entries["status"].to_pylist(), entries["readable_metrics"].to_pylist()):        bounds = metrics.get("email") or {}        # bounds are compared lowercased: the learner's email is typed in capitals in the manifest        kept = (bounds.get("lower_bound"), bounds.get("upper_bound"))        if any(text in bound.lower() for bound in kept if bound for text in found.texts):            print(f"{'.'.join(table.name()[-2:])}, manifest entry with status {status}, email bounds:",                  bounds["lower_bound"], "to", bounds["upper_bound"])
Saídapython sweep-unreferenced-files.py
snapshots 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

A expiração remove snapshots, não arquivos. Dos arquivos sob as tabelas do plano, 28 não são referenciados por nada, e 9 contêm o aprendiz. A varredura com as 72 horas configuradas apaga 0 arquivos sem referência, já que todos os arquivos foram escritos segundos antes. Os exemplos passam uma idade zero porque um único processo escreve no catálogo deles. A varredura sem idade mínima apaga todos os arquivos sem referência, e 1 arquivo ainda contém o aprendiz: um manifesto que o snapshot atual de crm.learners referencia.

A especificação explica o motivo: quando um arquivo é substituído ou apagado, sua entrada no manifesto armazena o snapshot em que o arquivo foi apagado e o status 2 (apagado) (especificação de tabelas do Iceberg), e essa entrada mantém as estatísticas de colunas do arquivo apagado. Por padrão, sob o modo de métricas truncate(16) (configuração do Iceberg), elas incluem o menor valor de cada coluna de texto, cortado em 16 caracteres, e o maior, cortado em 16 com o último caractere incrementado em um, de modo que ainda limite todos os valores do arquivo (código-fonte). A entrada apagada em crm.learners mantém os limites de e-mail ALEXA590@POST.EX to zofia.haase@exan. O primeiro é o e-mail do aprendiz 3590, digitado em maiúsculas, que é ordenado antes de todos os outros e-mails da plataforma. O segundo é o do aprendiz 4998, o maior da plataforma, cujo 16º caractere, um m, virou um n. Nenhum aprendiz está a salvo disso: a entrada de cada arquivo de dados mantém o menor e o maior valor de cada coluna, então uma tabela com muitos arquivos pequenos identifica muitos aprendizes.

Regra prática: Remova os arquivos sem referência após cada expiração, com uma varredura própria construída sobre as tabelas de inspeção, já que o PyIceberg não tem nenhuma, e mantenha em produção uma idade mínima de dias para que uma escrita em andamento preserve seus arquivos. Use uma idade de zero apenas onde um único processo escreve. Não considere uma pessoa apagada só porque nenhum arquivo de dados a contém: os manifestos ainda podem guardar os valores dela.

Mantenha valores pessoais fora dos manifestos

Última alteração na edição 2026.11.27

A varredura deixou o e-mail do aluno em um manifesto, como limite de uma coluna. O Iceberg permite que uma tabela escolha, coluna por coluna, o que os seus manifestos guardam, com a propriedade write.metadata.metrics.column.<name>: none não guarda nada, counts guarda as contagens de valores e de nulos, truncate(n) acrescenta limites truncados em n caracteres, e full acrescenta os limites completos (configuração do Iceberg). O PyIceberg 0.12.0 busca a propriedade pelo nome da coluna ao escrever um arquivo (código-fonte).

Digitadas à mão, essas propriedades se desencontrariam das classificações. lib.retention.properties as gera a partir de governance/metadata.toml e da seção [statistics] de governance/retention.toml: none para toda coluna classificada como personal ou sensitive, e para toda coluna que ninguém classificou, com o mesmo padrão fail-closed que a política de acesso usa. Ela acrescenta as configurações de history.expire a partir da seção [snapshots] das regras. lib.retention.apply_properties as define em todas as tabelas e reescreve os dados de cada tabela uma vez, porque um modo de métricas se aplica apenas aos arquivos escritos depois de definido; a expiração e uma varredura então removem os arquivos anteriores. O aluno 4998, cujo e-mail é o maior limite no manifesto de crm.learners, serve de caso de teste, apagado em duas plataformas: uma com estatísticas padrão e outra com as propriedades geradas:

statistics-off-for-personal-columns.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""Generates each table's properties from the classifications, so manifests keep no bounds on personal columns, then erasesthe 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."""from datetime import timedeltafrom lib import retentionLEARNER = 4998for statistics_off in (False, True):    catalog, graph = retention.open_platform(statistics_off)    label = "statistics off for protected columns" if statistics_off else "default statistics"    if statistics_off:        generated = retention.properties(catalog)        # the per-column metrics settings; the history.expire settings are not counted here        turned_off = [key for wanted in generated.values() for key in wanted if key.startswith(retention.METRICS)]        print("columns with statistics turned off:", len(turned_off))        # tables with no entry in governance/metadata.toml, which the generated properties still cover        unclassified = [name for name in generated if name not in retention.metadata.load()]        print("of them in tables nobody has classified:",              sum(key.startswith(retention.METRICS) for name in unclassified for key in generated[name]))        print("crm.learners, properties set:", len(generated["crm.learners"]))        for key, value in sorted(generated["crm.learners"].items()):            print(f"  {key} = {value}")    # crm.learners has one data file, so its one manifest entry keeps the table's email bounds    entry = catalog.load_table("crm.learners").inspect.entries()["readable_metrics"].to_pylist()[0]    print(f"{label}, crm.learners email bounds:", entry["email"]["lower_bound"], "to", entry["email"]["upper_bound"])    columns = retention.metadata.load()["crm.learners"].columns.values()    personal = [column.name for column in columns if column.classification == "personal"]    print(f"{label}, crm.learners personal columns:", len(personal))    with_bounds = sum(entry[name]["lower_bound"] is not None for name in personal)    print(f"{label}, of them with bounds in the manifest:", with_bounds)    steps, found, _ = retention.erase_everywhere(catalog, graph, LEARNER, "erasure-0002", min_age=timedelta(0))    print(f"{label}, files holding learner {LEARNER} after erasure, expiry and sweep:",          sum(held for _, held in retention.scan(catalog, found).values()))
Saídapython statistics-off-for-personal-columns.py
default 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

Com as estatísticas padrão, 1 arquivo ainda guarda o aluno 4998 após o apagamento, a expiração e a varredura, por meio de um limite superior elevado. O manifesto guarda limites para 7 das colunas pessoais da tabela, e seus limites de e-mail são ALEXA590@POST.EX to zofia.haase@exan.

Desligar as estatísticas das colunas pessoais é o que mantém o aluno 4998 fora dos arquivos. Os limites de e-mail são None to None, o manifesto guarda limites para 0 das 7 colunas pessoais da tabela, e 0 arquivos guardam o aluno após o apagamento, a expiração e a varredura.

As propriedades geradas desligam as estatísticas de 24 colunas, 10 delas em marketing.audience e ai.review_corpus, as duas tabelas que o capítulo 2 encontrou sem metadados. crm.learners recebe 9 propriedades: as duas configurações de expiração e none para cada coluna pessoal.

O custo está na poda. O Iceberg usa os limites nos manifestos para pular arquivos que não podem satisfazer o filtro de uma consulta (especificação de tabela do Iceberg), então, sem eles, uma consulta que filtra por email lê todos os arquivos. A plataforma filtra e apaga por learner_id, que é internal e mantém suas estatísticas. counts é a outra opção: guarda as contagens que ajudam o planejador, e nenhum valor. E, como o PyIceberg 0.12.0 mantém a propriedade sob o nome antigo da coluna em uma renomeação, deixando o nome novo sem ela, as propriedades são geradas de novo a cada mudança de esquema, como o capítulo 2 exige de toda visão dos metadados indexada pelo nome.

Regra prática: Gere as propriedades de métricas por coluna a partir das suas classificações, none ou counts para toda coluna pessoal, sensível ou não classificada, e aplique-as quando uma tabela for criada ou, para uma tabela existente, com uma reescrita seguida de expiração e varredura. Mantenha as estatísticas nas colunas de ID pelas quais você filtra e apaga. Gere as propriedades de novo após cada mudança de esquema.

Comprove a eliminação lendo cada arquivo

Última alteração na edição 2026.11.31

Cada passo até aqui removeu algo que o anterior deixou para trás, e deixou algo próprio: a exclusão, a expiração, a varredura e as configurações de estatísticas. É esse o motivo para verificar o resultado em vez de confiar nos passos. O relatório do Conselho Europeu de Proteção de Dados sobre como os controladores tratam a eliminação, adotado em fevereiro de 2026, encontrou entre os pontos fracos os backups e a anonimização usada no lugar da exclusão, e recomenda que os controladores "verifiquem que a eliminação foi realizada e estejam em condições de demonstrá-la" (EDPB, 2026).

lib.retention.scan lê todos os arquivos sob o warehouse do catálogo, cada um com o leitor de seu próprio formato, e procura os vestígios do aprendiz. lib.retention.traces registra os vestígios antes da eliminação: os IDs de cada linha que o plano exclui, por coluna, e os primeiros 15 caracteres, em minúsculas, de cada valor identificador. São quinze porque um manifesto mantém inalterados os primeiros 15 caracteres do maior valor e aumenta em um o 16º; uma busca por 16 caracteres deixaria de encontrar uma pessoa cujo valor é o maior do arquivo, como o e-mail do aprendiz 4998. Um arquivo Parquet é lido como linhas. Um manifesto ou uma lista de manifestos, ambos em Avro, é lido registro a registro com o leitor Avro do PyIceberg: cada string, incluindo os limites, e os limites de cada coluna de ID, decodificados pelo esquema que o manifesto traz. Um arquivo de metadados é lido como texto. Em uma tabela que uma exceção mantém, os IDs do aprendiz são esperados, então ali a varredura procura apenas valores, incluindo os das colunas que a exceção eliminou. lib.retention.erase_everywhere executa a tarefa inteira: planejar, registrar os vestígios, verificar cada tabela, eliminar, expirar, varrer. Na plataforma com as propriedades geradas, a tarefa inteira é executada e termina com a varredura:

verify-erasure.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""Runs the whole erasure job on the platform with statistics off for protected columns, then scans every file under thewarehouse. The `files holding the learner` line is the proof; the rest is evidence of IDs and counts, never the learner's values."""from datetime import timedeltafrom lib import retentionLEARNER, REQUEST = 3590, "erasure-0001"catalog, graph = retention.open_platform(statistics_off=True)# min_age of zero: one writer, so nothing is in flight that a sweep could takesteps, found, done = retention.erase_everywhere(catalog, graph, LEARNER, REQUEST, min_age=timedelta(0))report = retention.scan(catalog, found)for table, (files, holding) in report.items():    print(f"{table}: {files} files read, {holding} holding the learner")print("request:", REQUEST)print("tables visited:", len(steps))# each table the job deleted from has a count of rows; the one it reran has 'rebuilt' insteadprint("rows deleted:", sum(rows for rows in done.values() if rows != "rebuilt"))print("tables rebuilt:", ", ".join(table for table, rows in done.items() if rows == "rebuilt"))print("tables kept under an exception, columns erased:",      "; ".join(f"{step.table}, {', '.join(step.cleared)}" for step in steps if step.kept))# every snapshot but the current one: the ones a reader can still time travel toprint("snapshots a reader can still time travel to:",      sum(len(catalog.load_table(step.table).snapshots()) - 1 for step in steps))print("files no metadata references:",      sum(len(retention.unreferenced(catalog.load_table(name))) for name in retention.tables(catalog)))print("tables missing their generated properties:", ", ".join(retention.missing_properties(catalog)))print("files read:", sum(files for files, _ in report.values()))print("files holding the learner:", sum(holding for _, holding in report.values()))
Saídapython verify-erasure.py
ai.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

A varredura encontra o aprendiz em 0 dos 115 arquivos que lê, e nenhum leitor pode viajar no tempo até o aprendiz, pois permanecem 0 snapshots antigos, e 0 arquivos não são referenciados. As linhas após as contagens por tabela são a evidência: o ID da solicitação, as tabelas visitadas, as linhas excluídas, a tabela que a tarefa reconstruiu, a tabela que uma exceção mantém e a coluna eliminada nela, billing.payments, card_number, com o motivo em governance/retention.toml, e as contagens da varredura. Elas não citam nenhum valor do aprendiz, então mantê-las não recoloca nenhum de volta, o que o capítulo 8 pressupõe ao gravá-las no log de auditoria.

Uma linha é um aviso: analytics.course_performance não tem suas propriedades geradas, porque lib.pipelines.run removeu a tabela e a criou novamente sem elas. Essa tabela não tem colunas pessoais. A próxima tabela que um pipeline reconstruir pode tê-las, e a varredura então relataria os limites de seus manifestos como uma eliminação malsucedida; por isso a verificação deve ocorrer após cada execução de pipeline.

IDs também podem permanecer em um manifesto, já que as colunas de ID mantêm suas estatísticas. Um ID eliminado que era o menor ou o maior valor de um arquivo, como o do aprendiz 5000, permanece nos limites da entrada excluída, e a varredura o informa. Mais um commit na tabela, seguido de uma expiração e de uma varredura, o remove, porque o próximo append do PyIceberg deixa de fora um manifesto que contém apenas arquivos excluídos (fonte).

A varredura cobre apenas o warehouse. Exportações, backups, os sistemas de origem e os logs fora dele podem conter o aprendiz também, e os mesmos vestígios podem ser buscados em cada um que a plataforma consiga ler.

Regra prática: Termine toda eliminação com uma varredura de cada arquivo que a plataforma armazena, em busca dos IDs e dos valores identificadores da pessoa, lidos com o leitor próprio de cada formato, e guarde o resultado, apenas as contagens e os IDs, como evidência. Busque a maior parte possível de cada valor que todos os limites mantêm inalterada, que é um caractere a menos que o comprimento do truncamento. Trate qualquer arquivo que ainda contenha a pessoa como uma eliminação malsucedida, não como um aviso. Pesquise os armazenamentos fora do warehouse que você controla e liste no registro aqueles que você não consegue pesquisar.

O que dá errado em produção

Última alteração na edição 2026.11.27

Uma exclusão que tem êxito parece igual, quer os dados tenham sido apagados, quer ainda estejam no armazenamento, e é assim que o apagamento falha. A primeira falha aqui desfaz um apagamento já concluído.

Um estudante apagado retorna

Última alteração na edição 2026.11.27

Além da sincronização do CRM, o data warehouse recarrega todo o crm.learners todas as noites a partir da exportação da aplicação, e o apagamento foi feito apenas no warehouse. Apague o estudante 3590 em todos os lugares que o plano indica e, em seguida, deixe a recarga noturna e os pipelines que leem a tabela serem executados:

erased-learner-returns.py Python 3.12.15 · duckdb 2.0.0 · openlineage-python 1.55.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 · pyyaml 6.0.3 · sqlglot 30.33.0 Aprovado
"""An erased learner comes back: the nightly reload of crm.learners from the application's export brings the rows back, andthe pipelines rebuild from them. A check against the erasure register catches the rows."""from datetime import timedeltafrom lib import pipelines, retentionLEARNER, REQUEST = 3590, "erasure-0001"catalog, graph = retention.open_platform()retention.erase_everywhere(catalog, graph, LEARNER, REQUEST, min_age=timedelta(0))register = [retention.register_entry(REQUEST, LEARNER)]      # the request's ID and a keyed hash of the learner's IDprint("the erasure register's entry:", register[0]["request"], register[0]["learner"])learners = catalog.load_table("crm.learners")print("the learner's rows in crm.learners after the erasure:", retention.count(learners, retention.rows_of([LEARNER])))# the nightly reload: the application's export still holds the learner, since nobody erased it therelearners.overwrite(retention.crm_export())# the pipelines that read crm.learners rebuild from the reloaded tablefor name in ("learner_activity", "marketing_audience"):    pipelines.run(catalog, name)for table in ("crm.learners", "analytics.learner_activity", "marketing.audience"):    print(f"the learner's rows in {table} after the nightly run:",          retention.count(catalog.load_table(table), retention.rows_of([LEARNER])))# hashes each learner_id in every table and looks it up in the register, so no learner's ID is printedfor table, rows in retention.erased_rows(catalog, register).items():    print(f"the check against the register, rows of erased learners in {table}:", rows)
Saídapython erased-learner-returns.py
the 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

Um apagamento feito apenas no data warehouse não se mantém. Depois dele, crm.learners tem 0 linhas para o estudante; após a execução noturna, volta a ter 1, e analytics.learner_activity, reconstruída a partir dela, tem 1. marketing.audience continua limpa apenas porque o consentimento do estudante volta retirado e as matrículas, às quais ela se une, foram apagadas.

A verificação que detecta esse problema mantém um registro de apagamentos: para cada solicitação, seu ID e um hash com chave (HMAC-SHA256) do ID do estudante apagado, e nada mais. A chave é o segredo do job de apagamento, guardada como a chave de pseudonimização da camada de aplicação de políticas no capítulo 6, mas uma chave diferente, porque quem a possui pode calcular o hash de qualquer ID de estudante e descobrir quem o registro identifica. Após cada carga, restauração e reconstrução, lib.retention.erased_rows calcula o hash de cada learner_id em todas as tabelas que têm essa coluna e procura o resultado no registro; assim, uma restauração ou um backfill é verificado sem que o registro contenha o ID de nenhum estudante. Ela encontra o estudante em analytics.learner_activity e crm.learners, e deixa de fora billing.payments, cujas linhas a exceção mantém. O registro do apagamento no log de auditoria, no capítulo 8, contém o mesmo ID de solicitação e as mesmas contagens, nunca o estudante; por isso, o registro é o único lugar onde uma solicitação encontra um estudante, na forma de um hash. Tratamos um hash com chave de um ID como dado pseudonimizado, nunca como dado anonimizado.

Regra prática: Apague primeiro no sistema de origem, ou na mesma solicitação, e mantenha um registro de hashes com chave dos IDs apagados, contra o qual toda carga filtra e que toda execução verifica, com a chave guardada como segredo, separada dos dados. Trate uma linha com um ID apagado como um incidente, do mesmo modo que trataria um vazamento.

Outras falhas

Última alteração na edição 2026.11.27
  • Snapshots e arquivos antigos mantêm dados "apagados". Um job de retenção ou de apagamento que para depois da exclusão deixa tudo legível pela viagem no tempo, e, no PyIceberg, os arquivos continuam existindo após a expiração. Execute a expiração e a varredura no mesmo job e, em seguida, a verificação.
  • Outro motor exclui por merge-on-read. O PyIceberg lê os vetores de exclusão que outros motores gravam (notas de versão). Linhas excluídas dessa forma permanecem em seus arquivos de dados até que a compactação os reescreva, e um arquivo de exclusão pode manter seus valores, já que os dois tipos de arquivo de exclusão podem codificar os valores das linhas que excluem (especificação de tabelas do Iceberg). Compacte os arquivos afetados antes de a expiração e de a varredura, e verifique também os arquivos de exclusão.
  • Backups mantêm tudo o que a varredura apaga. Eles são um dos pontos fracos que o relatório do EDPB aponta. Decida com as pessoas responsáveis pelos backups como eles serão apagados ou descartados por envelhecimento, e registre isso em cada solicitação.
  • Uma tabela derivada que ninguém apagou. Um job que não envia linhagem grava uma cópia que o plano não consegue enxergar, como a exportação sem instrumentação do capítulo 4 faz. Execute lib.lineage.unaccounted antes de cada apagamento.
  • Uma tabela recriada perde suas propriedades. Um pipeline que remove e cria sua tabela perde as configurações de estatísticas geradas, e o próximo apagamento deixa valores nos seus manifestos. Aplique as propriedades após cada execução, ou crie as tabelas já com elas.
  • Uma coluna renomeada perde sua configuração. No PyIceberg, a propriedade de métricas permanece com o nome antigo da coluna, então, após a renomeação, o novo nome não tem nenhuma. Gere as propriedades novamente a cada alteração de esquema.
  • Retenção contada a partir da data errada. Uma regra que significa "após o fechamento", mas conta a partir da abertura, apaga cedo demais, e uma que conta a partir da data de carga apaga tarde demais. Armazene a data que a regra quer dizer.

O que este capítulo decidiu

Última alteração na edição 2026.11.27
  • Regras de retenção são configuração, aplicadas em relação a um dia informado ao job, nunca ao relógio. Cada período é uma escolha da própria plataforma, mantida em as regras, e os tickets fechados contam a partir da abertura, porque a tabela não tem closed_at.
  • O consentimento é um atributo que a política lê no momento da consulta; uma retirada não apaga nada, e as tabelas construídas com um filtro de consentimento são reconstruídas.
  • Uma eliminação é planejada a partir do catálogo e da linhagem: cada tabela com uma coluna learner_id, depois cada tabela que a linhagem alcança.
  • As exceções à eliminação são da equipe jurídica, registradas em governance/retention.toml com seus motivos; o código mantém o que eles dizem até que a regra de retenção da tabela o encerre.
  • Os commits registram IDs de requisição e nomes de regras, nunca os valores de uma pessoa.
  • A expiração do livro lê as configurações de cada tabela, o que o PyIceberg não faz, e uma eliminação verifica cada tabela do seu plano antes de apagar qualquer coisa.
  • A varredura do livro remove arquivos sem referência, com idade mínima de 72 horas em produção.
  • Os manifestos não guardam valores de colunas protegidas: modo de métricas none, gerado a partir das classificações.
  • Toda eliminação termina com uma varredura de cada arquivo, em busca dos IDs e de 15 caracteres de cada valor identificador; suas contagens são a evidência.
  • O registro de eliminações guarda um hash com chave de cada ID eliminado, verificado após cada carga, restauração e reconstrução. Retenção e eliminação são verificadas pelo que permanece: uma varredura após cada eliminação, um registro de hashes e regras que contam a partir do dia informado ao job. Uma varredura pode passar enquanto dados permanecem em algum lugar que ela não examinou, por isso o registro é verificado novamente após cada carga, restauração e reconstrução.

Este capítulo, nesta edição

Edição 2026.11.31Exemplos aprovados em 19 de nov de 202611 de 11 exemplos exemplos deste capítulo passam

Traduzido do livro em inglês, edição 2026.11.31.

Citar esta seção

Formato

Cada formato cita o livro em inglês, que esta tradução acompanha.

Todos os formatos citam esta edição. Seu link abre a edição atual, em que o título de cada seção indica quando seu texto foi alterado pela última vez. As datas de acesso e de recuperação são o dia em que você abre esta página.

Nesta página

Capítulo 7 de 10: Retenção, consentimento e eliminação

  1. Mantenha as regras de retenção em um arquivo revisado
  2. Remova linhas expiradas com deletes de linhas
  3. Ler o consentimento onde a consulta é executada
  4. Planeje um apagamento a partir da linhagem
  5. Apague as linhas que o plano lista
  6. Expirar snapshots pelas próprias configurações da tabela
  7. Remova os arquivos que nenhum snapshot referencia
  8. Mantenha valores pessoais fora dos manifestos
  9. Comprove a eliminação lendo cada arquivo
  10. O que dá errado em produção
  11. Um estudante apagado retorna
  12. Outras falhas
  13. O que este capítulo decidiu

Voltar ao topoTodos os capítulos