Expirar snapshots e remover arquivos não referenciados
Cerca de 23 minutos min de leitura, com 3 exemplos em 8 seções.
Traduzido com IA. Verificado por pessoas em inglês. Como fazemos os livros
Traduzido do livro em inglês, edição 2026.11.10. Leia o original
Ao final deste capítulo, você saberá expirar snapshots antigos em cada um dos três formatos, remover os arquivos de dados que apenas esses snapshots ainda listavam e mostrar que uma leitura de um snapshot expirado falha.
Compactação deixa o mesmo tipo de arquivo antigo: as reescritas deixaram os arquivos substituídos no disco, porque snapshots mais antigos ainda os listam. Este capítulo expira os snapshots antigos de wiki.pageviews_hourly e, em seguida, exclui os arquivos que nenhum snapshot lista mais. Todos os exemplos deste capítulo usam a correção da hora 02 do capítulo sobre correções, escrita como uma sobrescrita dessa hora, e não como o upsert da seção posterior, porque a sobrescrita deixa exatamente um arquivo antigo por formato. Esses arquivos antigos permanecem até que seus snapshots sejam expirados e seus arquivos removidos. As duas etapas são executadas em cada formato, e cada etapa é verificada com uma contagem, e não com uma listagem em que você precise confiar.
Snapshots mantêm os arquivos vivos
Cada snapshot registra quais arquivos de dados compõem a tabela naquele commit. O que um snapshot aponta explica como cada formato armazena essa lista. O ponto deste capítulo é que um commit que substitui linhas não apaga os arquivos que substitui. Ele grava arquivos para as linhas de substituição, e os snapshots anteriores ao commit continuam listando os antigos, de modo que a viagem no tempo continua funcionando. Um arquivo de dados se torna um órfão apenas quando nenhum snapshot que você mantém o lista.
Remover um arquivo exige duas etapas em todos os formatos: primeiro a expiração, depois a limpeza. A página de manutenção do Iceberg apresenta a mesma ordem: a expiração remove snapshots dos metadados, de modo que a viagem no tempo não consegue alcançá-los, e "os arquivos de dados não são apagados enquanto não deixarem de ser referenciados por um snapshot que possa ser usado para viagem no tempo ou reversão" (Apache Iceberg, manutenção). Após a expiração, a limpeza apaga os arquivos que nenhum snapshot restante lista.
wiki.pageviews_hourly recebe três anexações horárias, e depois a hora 02 é corrigida por uma sobrescrita dessa hora. Cada anexação grava um arquivo. A sobrescrita grava um arquivo com as linhas corrigidas da hora 02 e remove o arquivo antigo do snapshot atual. O snapshot que anexou o arquivo antigo ainda o lista. Enquanto esse snapshot não for expirado, o arquivo antigo não pode ser apagado sem quebrar a viagem no tempo até ele. Fazer upsert de uma hora corrigida mostra a outra forma de gravar a mesma correção, e ela deixa para trás o mesmo tipo de arquivo antigo.
Cada formato tem sua própria chamada de expiração e sua própria chamada de limpeza. A tabela as lista, e o restante do capítulo segue a mesma ordem para cada formato.
| Formato | Chamada de expiração | A expiração apaga arquivos? | Chamada de limpeza |
|---|---|---|---|
| Iceberg (pyiceberg) | expire_snapshots().by_ids(...) |
Não | Nenhuma na biblioteca: conte e remova os arquivos você mesmo |
| Delta Lake (deltalake) | Retenção de versões em vacuum |
Sim, por vacuum |
vacuum |
| DuckLake | ducklake_expire_snapshots |
Não | ducklake_cleanup_old_files, depois ducklake_delete_orphaned_files |
Regra prática: Decida quais snapshots ou versões um leitor ainda pode precisar, e expire os demais antes de remover qualquer arquivo. Nunca remova um arquivo que um snapshot que você mantém ainda liste, e verifique essa afirmação com uma contagem antes de apagar.
Expirar snapshots com pyiceberg
Na pyiceberg 0.12.0, table.maintenance.expire_snapshots() recebe IDs de snapshots, com by_ids para uma lista ou by_id para um único, ou um timestamp informado por older_than. Não há argumento que mantenha os últimos N snapshots. Este capítulo escolhe os IDs pela ordem de commit, como o caso faz: os três appends horários são os três primeiros snapshots. Os próprios IDs são números aleatórios de 64 bits, então o exemplo imprime os rótulos "snapshot 1", "snapshot 2" e assim por diante, na mesma ordem.
A sobrescrita adiciona dois snapshots, não um. A pyiceberg grava um snapshot de delete que remove o arquivo antigo e, depois, um snapshot de append que adiciona as linhas corrigidas. O snapshot 4 é o delete e o snapshot 5 é o append. Expirar os três appends, portanto, deixa a sobrescrita em vigor, e esse é o estado que o exemplo verifica.
A chamada de expiração não remove arquivos de dados, então o exemplo os conta por conta própria, antes e depois: os arquivos distintos que os snapshots listam e os arquivos em disco que nenhum deles lista. Observe a última contagem, que é onde aparece o arquivo substituído:
1"""Expire the three append snapshots by ID, then count what the snapshots still reference. The point rests on the2line that counts unreferenced data files on disk: expiry removes metadata, and the file the overwrite replaced stays."""34from lib.lakehouse import (5 ICEBERG_ID,6 create_iceberg_table,7 hour_corrections,8 hour_filter,9 new_warehouse,10 orphan_data_files,11 read_cut_hour,12 scan_arrow,13 snapshot_labels,14)151617def referenced_files(table):18 """Distinct data files that some retained snapshot lists. Count them; do not print them."""19 # all_files() can list one file from several manifests, so the set counts each file once20 return len(set(table.inspect.all_files()["file_path"].to_pylist()))212223with new_warehouse() as wh:24 table = create_iceberg_table(wh)25 for hour in (0, 1, 2):26 table.append(read_cut_hour(hour))27 # hour_filter(2) matches only hour 02's rows, so the overwrite replaces that hour and leaves hours 00 and 01 alone28 table.overwrite(hour_corrections(read_cut_hour(2)), overwrite_filter=hour_filter(2))2930 ids = [snapshot.snapshot_id for snapshot in table.metadata.snapshots] # metadata lists snapshots in commit order31 labels = snapshot_labels(ids)32 print("snapshots before expiry:", len(ids))33 print("data files referenced before expiry:", referenced_files(table))34 print("data files in the current snapshot:", len(table.inspect.files())) # files() reads the current snapshot only3536 expired = ids[:3] # the three hourly appends, by commit order37 table.maintenance.expire_snapshots().by_ids(expired).commit()38 table = wh.catalog.load_table(ICEBERG_ID)3940 print("remaining snapshots:", ", ".join(labels[s.snapshot_id] for s in table.metadata.snapshots))41 print("data files referenced after expiry:", referenced_files(table))42 # files under the table location that no remaining snapshot lists; a file a writer has not committed counts too43 print("unreferenced data files left on disk:", len(orphan_data_files(table)))44 print("rows in the current snapshot:", scan_arrow(table).num_rows)45 try:46 scan_arrow(table, snapshot_id=expired[-1])47 except ValueError as exc:48 print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
python expire-iceberg-snapshots.pysnapshots before expiry: 5
data files referenced before expiry: 4
data files in the current snapshot: 3
remaining snapshots: snapshot 4, snapshot 5
data files referenced after expiry: 3
unreferenced data files left on disk: 1
rows in the current snapshot: 1499
read snapshot 3: ValueError
Antes da expiração, a tabela tem 5 snapshots, e 4 arquivos de dados são listados por pelo menos um deles. O snapshot atual lista apenas 3 desses arquivos. O restante é o antigo arquivo da hora 02, que o snapshot 3 ainda lista. Ler as contagens dessa forma mostra o que a sobrescrita fez: a tabela atual está completa, e o histórico ainda guarda o arquivo que a sobrescrita substituiu.
Em seguida, o exemplo expira os snapshots 1 a 3, os três appends. Os snapshots que permanecem são snapshot 4, snapshot 5, o delete da sobrescrita e o seu append. Depois disso, 3 arquivos de dados são listados, e o antigo arquivo da hora 02 não é mais listado por nenhum snapshot. Ele continua em disco: o exemplo informa 1 arquivo não referenciado. A tabela atual ainda retorna 1499 linhas, então a expiração não alterou nenhum dado que um leitor da tabela atual veja.
A última leitura falha. Uma leitura do snapshot 3 após a expiração lança ValueError, que a saída mostra como "read snapshot 3: ValueError". Um leitor que fixou o snapshot 3 antes da expiração recebe um erro, não as linhas antigas. O erro, Snapshot not found, indica o ID do snapshot, mas não diz que uma expiração removeu o snapshot. Seus próprios logs precisam registrar qual expiração foi executada e qual snapshot o relatório usou.
Regra prática: Expire os snapshots do Iceberg pelo ID, escolhido pela ordem de commit, e conte os arquivos que cada snapshot restante lista antes e depois. Não espere recuperar espaço em disco com a expiração. A pyiceberg remove apenas metadados, então os arquivos que ela deixa para trás continuam em disco até que você os remova por conta própria.
Encontre arquivos órfãos após a expiração
Um arquivo que nenhum snapshot lista é um órfão. Spark e Java oferecem uma ação deleteOrphanFiles: ela lista a localização da tabela, compara os arquivos com os metadados e exclui a diferença, e seu intervalo de idade padrão é de 3 dias (Apache Iceberg, manutenção). A página da API do pyiceberg não lista nenhuma etapa de arquivos órfãos, e o pacote 0.12.0 também não tem uma. Seus métodos de manutenção só expiram snapshots (PyIceberg API).
Um auxiliar do módulo compartilhado do livro, examples/lib/lakehouse.py, chamado orphan_data_files, faz a comparação manualmente. Ele lista os arquivos Parquet sob a localização da tabela, subtrai os arquivos que qualquer snapshot restante lista e devolve o restante. A saída mostra apenas a contagem, porque os nomes dos arquivos carregam UUIDs. Essa contagem é a linha que mostra que o arquivo expirado ainda está no disco.
Uma listagem não consegue distinguir um órfão de um arquivo que um escritor gravou e ainda não confirmou. O commit vincula o arquivo à tabela, e até lá o arquivo parece não referenciado. Por isso as proteções por idade importam. ducklake_delete_orphaned_files do DuckLake mantém arquivos novos por padrão, e a ação do Spark recebe um intervalo de idade pelo mesmo motivo. O pyiceberg não tem intervalo, então essa verificação fica por sua conta. Excluir um órfão é uma decisão separada, e ela deve vir depois que os escritores que poderiam confirmá-lo tiverem parado.
Regra prática: Conte os órfãos por listagem, e remova-os somente depois de confirmar que nenhum escritor ainda pode confirmá-los e que nenhum leitor ainda usa um snapshot que os lista. No pyiceberg, nada na biblioteca faz essa verificação por você.
Executar o vacuum em uma tabela com deltalake
O Delta Lake não apaga um arquivo quando um commit o substitui. Um commit do Delta que substitui um arquivo adiciona uma ação remove ao log, uma lápide que diz que o arquivo não faz mais parte da tabela, e o arquivo continua no disco. O protocolo afirma que esses arquivos "podem ser apagados de forma preguiçosa pelo comando vacuum após um período de retenção definido pelo usuário (padrão de 7 dias)" (Delta transaction log protocol, v4.4.1). A saída desta seção usa os números de versão do próprio Delta, que começam em 0.
O vacuum apaga os arquivos cujas lápides são mais antigas que a retenção. Até lá, toda versão pode ser lida, porque todo arquivo que ela lista ainda existe. A página de utilitários do Delta descreve o custo: "A capacidade de voltar no tempo para uma versão mais antiga que o período de retenção é perdida após executar o vacuum" (Delta Lake, VACUUM).
O caso tem três appends, que formam as versões 0 a 2, e depois a correção da hora 02. A correção é uma exclusão daquela hora, que é a versão 3, seguida de um append das linhas corrigidas, que é a versão 4. A versão 2 ainda lista o arquivo antigo da hora 02, e a versão 3 não. Nada foi removido ainda, e é desse estado que a próxima seção parte.
A retenção padrão no deltalake é de 168 horas, sete dias. Uma tabela pode definir a sua própria na propriedade delta.deletedFileRetentionDuration, e o vacuum usa essa propriedade quando você não passa retention_hours. Essa propriedade é a configuração de produção. A biblioteca recusa uma retenção menor que o valor da propriedade, a menos que você desative enforce_retention_duration. Uma retenção maior não precisa de flag. A retenção que você escolhe é uma promessa sobre até onde o histórico alcança. Todo leitor que abre uma versão mais antiga depende dela, e a próxima seção mostra a recusa e o motivo pelo qual a execução de ensino deste capítulo desliga a verificação.
Regra prática: Mantenha a retenção padrão do vacuum, ou defina uma mais longa em delta.deletedFileRetentionDuration, de modo que toda versão que um leitor possa solicitar continue legível por esse tempo depois de deixar de ser a atual. Só use um valor menor depois de verificar a leitura mais longa e a escrita mais longa do seu sistema, e apenas desligando enforce_retention_duration como uma decisão deliberada e registrada.
Primeiro, a simulação
Uma simulação (dry run) lista os arquivos que um vacuum real excluiria e não exclui nenhum deles. Execute uma antes de cada vacuum e compare a contagem com o histórico da tabela. O caso é de três appends, um delete na versão 3 e um append na versão 4. Uma lista curta pode ser conferida à mão: aqui, cada arquivo da lista é um que um delete removeu, e o que importa é o delete da versão 3. Duas simulações sobre esse histórico perguntam ao vacuum, com duas retenções, o que ele excluiria:
1"""Show that vacuum's default retention keeps a file that a delete has just removed, and that a read of an older version2fails once a teaching-only run removes that file. The point rests on the default-retention line and the read of version 2."""34import pyarrow as pa5from deltalake import DeltaTable, write_deltalake6from deltalake.exceptions import DeltaError78from lib.lakehouse import new_warehouse, read_cut_hour, read_delta, hour_corrections910with new_warehouse() as wh:11 path = str(wh.root / "delta" / "pageviews_hourly")12 for hour in (0, 1, 2):13 write_deltalake(path, read_cut_hour(hour), mode="append")14 dt = DeltaTable(path)15 dt.delete("hour_utc = '2024-06-03T02:00:00'") # hour 02, matched by its exact timestamp16 # hour_corrections halves the views of some page titles in hour 02, so this append holds the corrected rows17 write_deltalake(path, hour_corrections(read_cut_hour(2)), mode="append")1819 dt = DeltaTable(path)20 print("current version:", dt.version())21 # the delete was seconds ago, so the default retention still keeps its file22 print("default retention, dry run lists:", len(dt.vacuum(dry_run=True)))23 try:24 dt.vacuum(retention_hours=0, dry_run=True) # a retention below the table's minimum: refused without the flag25 except DeltaError as exc:26 print("zero retention without the flag:", type(exc).__name__)27 # Teaching run only: a zero-hour retention removes files at once. Production keeps the 168-hour default.28 print("zero retention, dry run lists:", len(dt.vacuum(retention_hours=0, dry_run=True, enforce_retention_duration=False)))29 print("zero retention, removed:", len(dt.vacuum(retention_hours=0, dry_run=False, enforce_retention_duration=False)))30 print("rows in version 0:", read_delta(path, version=0).num_rows) # version 0 reads files the vacuum left alone31 try:32 read_delta(path, version=2) # version 2 still lists the hour-02 file that the vacuum removed33 except pa.ArrowInvalid as exc:34 print("read version 2:", type(exc).__name__)
python vacuum-delta-dry-run.pycurrent version: 4
default retention, dry run lists: 0
zero retention without the flag: DeltaError
zero retention, dry run lists: 1
zero retention, removed: 1
rows in version 0: 499
read version 2: ArrowInvalid
A tabela está na versão 4. Com a retenção padrão, a simulação lista 0 arquivos. O arquivo que a versão 3 removeu é recente demais para aparecer na lista, e o vacuum o mantém.
A chamada seguinte define a retenção como zero, e o deltalake a recusa com DeltaError. A própria mensagem da biblioteca diz que a retenção mínima é de 168 horas, de modo que a verificação protege a configuração padrão.
A execução de ensino desliga essa verificação com enforce_retention_duration=False. O código a marca como exclusiva para ensino, e a produção não a utiliza. Com a verificação desligada, a simulação lista 1 arquivo, e o vacuum real remove 1 arquivo, o arquivo antigo hour-02. A retenção zero é a configuração adequada para uma demonstração, porque exclui o arquivo imediatamente. Em produção, ela está errada: qualquer leitor que tenha começado antes do vacuum, ou que tenha fixado uma versão anterior, perde os arquivos que está lendo no meio de uma consulta. Uma retenção curta também exclui os arquivos de um escritor que já escreveu, mas ainda não confirmou (commit) a operação. A página de utilitários do Delta alerta que "tables can be corrupted when VACUUM deletes files that have not yet been committed" (Delta Lake, VACUUM). O dano atinge a tabela, e não apenas uma leitura.
A leitura no final mostra o custo do vacuum. A versão 0 ainda é lida, com 499 linhas, porque todos os arquivos que ela lista continuam existindo. A versão 2 falha com ArrowInvalid, exibido como "read version 2: ArrowInvalid". Essa classe é a que o mecanismo de consulta lança quando uma leitura de Parquet falha, e a mensagem indica o objeto ausente. A leitura imprime apenas a classe. Leia a mensagem completa nos seus logs antes de concluir que a tabela está danificada: ela informa qual objeto está ausente e, portanto, se um vacuum o removeu.
A simulação não é uma garantia sobre a execução real. Um escritor que confirme uma operação entre as duas chamadas altera a tabela, e a execução real trabalha com o estado da tabela que encontrar. Trate a contagem da simulação como uma verificação do que você espera, e leia a contagem da execução real ao lado dela.
Regra prática: Execute o vacuum primeiro como simulação e leia a contagem. Remova os arquivos com uma execução real somente quando a contagem corresponder ao que você esperava pelo histórico da tabela, e mantenha a retenção padrão, a menos que você tenha verificado a leitura mais longa do seu sistema.
Expirar e limpar no DuckLake
O DuckLake mantém os arquivos físicos de um snapshot até que esse snapshot seja expirado. A documentação do DuckLake diz isso desta forma: "Os dados só podem ser removidos fisicamente do DuckLake expirando snapshots que se referem aos dados antigos" (DuckLake, expiração de snapshots). A mesma página observa que a expiração não exclui imediatamente os arquivos que ela deixa sem referência, e a página sobre limpeza traz a segunda chamada (DuckLake, limpeza de arquivos).
Portanto, a manutenção do DuckLake tem duas etapas, e o exemplo abaixo executa ambas. ducklake_expire_snapshots recebe uma lista de números de snapshot em versions, ou um timestamp em older_than, mas não os dois. ducklake_cleanup_old_files remove os arquivos que a expiração agendou. Com older_than, remove apenas os arquivos agendados antes de determinado momento. Com cleanup_all => true, remove todo arquivo agendado, sem verificação de idade. Ambas as etapas aceitam dry_run.
Uma terceira chamada, ducklake_delete_orphaned_files, trata dos arquivos que nenhum snapshot lista e que a limpeza nunca agendou, como um arquivo que um escritor deixou para trás após um commit malsucedido. Seu comportamento padrão mantém um arquivo que ainda é recente, porque um escritor pode estar prestes a fazer o commit dele. Sua opção cleanup_all remove esses arquivos independentemente da idade. O capítulo sobre o catálogo mostra o que essa opção faz quando um segundo catálogo compartilha a pasta de dados.
Conectar o catálogo e criar o schema e a tabela por meio dos auxiliares produz três snapshots antes de qualquer linha: a conexão gera o snapshot 1, e as duas instruções CREATE geram os snapshots 2 e 3, numerados a partir de 1 com a preparação incluída, como o capítulo 2 faz. Em seguida, o auxiliar de carga insere as horas 00 a 02, apaga a hora 02 e insere a hora 02 corrigida. Isso produz 8 snapshots, que o exemplo rotula de "snapshot 1" até o último. O último é a inserção corrigida. O anterior a ele é o delete, que descarta o antigo arquivo da hora 02. A inserção anterior a essa, o snapshot 6, é o último snapshot que o lista.
1"""Expire every snapshot before the correction, clean up what expiry released, and run the orphan check as a dry run. The2point rests on the cleanup lines and on the orphan line, which shows that the default age check spares the stray copy."""34import shutil5from pathlib import Path67import duckdb89from lib.lakehouse import (10 DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table,11 ducklake_file_count, ducklake_file_paths, load_ducklake_with_correction, new_warehouse,12 version_labels,13)1415LAKE = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"161718def listed(con, call):19 """Run a DuckLake procedure and return how many rows it lists."""20 return con.sql(f"CALL {call}").to_arrow_table().num_rows212223with new_warehouse() as wh:24 con = connect_ducklake(wh.con)25 create_ducklake_table(con, wh.root)26 load_ducklake_with_correction(con) # lib inserts hours 00 to 02, deletes hour 02, then inserts the corrected hour 022728 # ORDER BY 1 sorts by snapshot_id, which grows with each commit, so the labels number the snapshots in commit order29 ids = [r[0] for r in con.execute(f"SELECT snapshot_id FROM ducklake_snapshots('{DUCKLAKE_ALIAS}') ORDER BY 1").fetchall()]30 labels = version_labels(ids, word="snapshot")31 print("snapshots before expiry:", len(ids))32 print("data files in the current snapshot:", ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE))33 stray = Path(sorted(ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE))[0]) # sorted, so every run copies the same file34 shutil.copy(stray, stray.with_name("stray.parquet")) # written, but no snapshot lists it3536 expired = ids[:-1] # all but the last snapshot, which is the corrected insert and stays37 # versions takes DuckLake's snapshot numbers, not the labels38 expire = f"ducklake_expire_snapshots('{DUCKLAKE_ALIAS}', versions => {expired}"39 print("expiry dry run lists:", listed(con, f"{expire}, dry_run => true)"))40 con.execute(f"CALL {expire})")41 print("remaining snapshots:", labels[ids[-1]])42 # no age check, so this is safe only because one catalog owns the folder and no reader is running43 cleanup = f"ducklake_cleanup_old_files('{DUCKLAKE_ALIAS}', cleanup_all => true"44 print("cleanup dry run lists:", listed(con, f"{cleanup}, dry_run => true)"))45 print("cleanup removed:", listed(con, f"{cleanup})"))46 # no cleanup_all, so the default age check spares the stray copy, which was written seconds ago47 orphans = f"ducklake_delete_orphaned_files('{DUCKLAKE_ALIAS}', dry_run => true)"48 print("orphans listed without cleanup_all:", listed(con, orphans))49 print("rows in the current snapshot:", con.sql(f"SELECT count(*) FROM {LAKE}").fetchall()[0][0])50 try:51 # the newest expired snapshot, the delete; reading it now fails52 con.sql(f"SELECT count(*) FROM {LAKE} AT (VERSION => {expired[-1]})").fetchall()53 except duckdb.InvalidInputException as exc:54 print(f"read {labels[expired[-1]]}: {type(exc).__name__}")
python ducklake-expire-cleanup.pysnapshots before expiry: 8
data files in the current snapshot: 3
expiry dry run lists: 7
remaining snapshots: snapshot 8
cleanup dry run lists: 1
cleanup removed: 1
orphans listed without cleanup_all: 0
rows in the current snapshot: 1499
read snapshot 7: InvalidInputException
O snapshot atual lista 3 arquivos de dados, e um deles é copiado para outro nome na mesma pasta, para representar um arquivo que um escritor gravou mas não confirmou, como descreve Encontrar arquivos órfãos. Em seguida, as etapas são executadas em ordem.
A simulação de expiração lista 7 snapshots, que são todos, exceto a inserção corrigida. Como essa inserção permanece, o estado atual da tabela não é alterado. A expiração real deixa snapshot 8. O antigo arquivo da hora 02 é liberado nesta etapa, porque o snapshot 6, o último snapshot que o listava, é expirado.
A simulação de limpeza lista 1 arquivo, o antigo arquivo da hora 02. O DELETE correspondeu a todas as linhas desse arquivo, e nenhum arquivo de exclusão está agendado junto com ele, então o arquivo antigo é o único que resta para remover. A limpeza real remove 1 arquivo.
A verificação de órfãos lista 0 órfãos. A cópia avulsa continua na pasta, porque a verificação de idade padrão a manteve: o arquivo tem apenas alguns segundos de idade. A tabela ainda retorna 1499 linhas.
Por fim, a leitura da exclusão, no snapshot 7, falha: "read snapshot 7: InvalidInputException". A classe é a que o DuckLake lança para uma versão que ele não possui mais.
cleanup_all => true aparece aqui porque há um único catálogo e nenhum leitor. Em produção, usa-se older_than no lugar, com uma idade maior que a da leitura mais longa, de modo que a limpeza remova apenas os arquivos que foram agendados por tempo suficiente.
Regra prática: Expire primeiro os snapshots do DuckLake e, em seguida, execute cada chamada de limpeza como simulação e depois de verdade, nessa ordem. Mantenha a verificação padrão de órfãos. Use cleanup_all somente quando um único catálogo for o dono da pasta de dados e nenhum leitor ainda usar os arquivos que ele remove, e use older_than nos demais casos.
O que dá errado em produção
Remover um arquivo que um leitor ainda usa. Uma consulta iniciada antes de um vacuum ou de uma limpeza lê um arquivo que, em seguida, deixa de existir, e a leitura falha no meio do caminho. Você verá isso como um erro de leitura que nomeia um objeto ausente, em um job executado durante uma janela de manutenção. Agende a manutenção fora das leituras longas e mantenha a retenção maior que a mais longa delas. Uma retenção curta também pode apagar um arquivo que um escritor já gravou e ainda não confirmou, o que corrompe a tabela em vez de fazer apenas uma leitura falhar; por isso, mantenha a retenção maior que a escrita mais longa em execução também.
Retenção menor que a consulta mais longa. O padrão de sete dias do Delta Lake é uma margem, não uma medição. Um dashboard que lê uma versão de um mês atrás está fora dela. Se um leitor precisa ver uma versão mais antiga, a retenção precisa cobri-la, ou o leitor precisa copiar os dados antes.
Viagem no tempo que falha após a manutenção. O snapshot expirado e a versão submetida a vacuum falham com ValueError, ArrowInvalid ou InvalidInputException, conforme o formato. Iceberg gera ValueError, e Delta gera ArrowInvalid. DuckLake gera InvalidInputException. Qualquer job que registra um ID de snapshot ou um número de versão para ler depois falha da mesma forma assim que esse snapshot expira. Mantenha um registro próprio de qual snapshot cada relatório usou, para que uma reconstrução parta dos dados e não dependa da leitura do snapshot antigo.
Uma simulação (dry run) que difere da execução real. Duas chamadas podem divergir quando um escritor confirma uma gravação entre elas. A contagem da simulação é o que você esperava, não o que a execução real vai remover. Compare a contagem real com a da simulação, e pare se elas diferirem por mais do que você consegue explicar.
Uma auditoria que precisa de um snapshot mais antigo. Alguns relatórios precisam reproduzir um número de meses atrás. A expiração remove essa capacidade definitivamente; por isso, defina a janela da auditoria antes de expirar e mantenha os snapshots ou os dados copiados de que a auditoria precisa. A expiração não substitui uma cópia.
Uma limpeza que apaga um arquivo que outro catálogo precisa. cleanup_all e a verificação de órfãos com cleanup_all apagam arquivos pelo caminho. Se um segundo catálogo aponta para a mesma pasta de dados, os arquivos ativos dele parecem órfãos para o primeiro catálogo. O capítulo sobre catálogos mostra essa falha em um diretório temporário.
Regra prática: Antes de expirar ou limpar, liste os leitores, relatórios e auditorias que podem abrir um snapshot ou uma versão mais antiga, e defina a retenção para cobrir o mais longo deles. Execute cada chamada como simulação, compare a contagem com o que você esperava, e execute a chamada real somente quando as duas coincidirem.
Decisões tomadas neste capítulo
- Os snapshots do Iceberg são expirados por ID, escolhidos pela ordem dos commits. O capítulo não expira por idade, para que o resultado não dependa do relógio da máquina, e o pyiceberg 0.12.0 não tem um argumento para manter os últimos N.
- O pyiceberg não remove arquivo algum, então
expire-iceberg-snapshotsconta os arquivos alcançáveis e não alcançáveis e deixa a remoção por sua conta. - A execução com retenção zero em
vacuum-delta-dry-runserve apenas para ensino. Ela está marcada no código, e a produção mantém a retenção padrão. - A expiração e a limpeza do DuckLake são chamadas separadas, e cada uma roda como dry run antes da chamada real.
cleanup_allaparece apenas nos exemplos de catálogo único. O capítulo sobre catálogos trata do caso em que ele remove arquivos ativos.- Cada exemplo imprime contagens, rótulos estáveis e nomes de classes de erro, e nenhum ID, carimbo de data e hora, nome de arquivo ou caminho (capítulo 1 explica o motivo), e todo número do texto vem de uma linha de saída vinculada ou da própria construção do exemplo.
- Cada exemplo mantém a tabela que os capítulos anteriores construíram, para que cada contagem possa ser conferida com o histórico que você já viu.
- Cada exemplo constrói o seu próprio armazém de dados temporário, então nenhuma saída depende de um exemplo anterior nem da máquina que o executa.
- A cópia avulsa em
ducklake-expire-cleanuprepresenta um arquivo que um escritor ainda não confirmou, como descreve Encontrar arquivos órfãos. Isso mostra a regra dos arquivos órfãos sem esperar que um arquivo envelheça, porque a execução leva apenas segundos.
Este capítulo, nesta edição
Edição 2026.11.10Exemplos aprovados em 20 de nov de 20263 de 3 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.10.