Corrija linhas com deletes, updates e merges
Cerca de 22 minutos min de leitura, com 5 exemplos em 9 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
Nesta página
Linhas já confirmadas também podem ser alteradas: este capítulo deleta, faz upsert e mescla essas linhas no Iceberg, no Delta Lake e no DuckLake, explica o que cada escrita faz nos arquivos e conta os snapshots que um upsert do pyiceberg adiciona.
Até agora, a tabela só cresce. Cada escrita do capítulo 1 acrescentou dados a wiki.pageviews_hourly, uma tabela em cujas horas a fonte às vezes reenvia dados.
Dados atrasados chegam como correção
A primeira entrega da hora 02 chegou à tabela no capítulo 1 com as contagens que a fonte enviou naquele momento. Uma entrega posterior da mesma hora traz contagens corrigidas para algumas páginas, e uma página que a primeira entrega deixou de fora. As páginas da correção são as mesmas páginas de antes, então a tabela precisa trocar linhas no lugar. Acrescentar a hora corrigida armazenaria cada página duas vezes, uma com cada contagem.
Neste livro, uma linha é identificada pela sua chave: hour_utc, domain_code e page_title juntos. Uma correção é um conjunto de linhas com chaves, e para cada chave a tabela ou já tem uma linha, que deve mudar, ou não tem, que deve ser adicionada. Escrever uma correção é, portanto, uma questão de chaves, e a escrita responde com uma regra: uma chave deve identificar uma única linha no lote que você escreve. O pyiceberg e o DuckLake aplicam essa regra. Este capítulo não testa uma chave repetida em um merge do deltalake.
Uma correção geralmente chega como a hora inteira, reenviada, e não como algumas linhas. Enviar a hora inteira mantém o lote autocontido, porque a escrita decide, linha por linha, o que mudou. O custo é que cada linha da hora é comparada, não apenas as corrigidas. Como cada linha é comparada, o pyiceberg pode contar apenas as linhas cujos valores diferem, e uma nova execução do mesmo lote não altera nada.
As correções aqui são construídas em código, a partir do recorte real do capítulo 1. O auxiliar hour_corrections reduz pela metade as contagens de 20 títulos de página da hora 02, arredondando para baixo. A linha atrasada é uma cópia da primeira linha da hora, com um título de página que a primeira entrega nunca teve. Apenas o lote de correção é gerado; as linhas de pageviews são as que o capítulo 1 recortou.
Regra prática: antes de escrever uma correção, verifique se o lote contém cada chave uma única vez. O pyiceberg e o DuckLake recusam um lote com chave repetida, cada um à sua maneira, e tentar de novo não corrige os dados. A seção de produção mostra as falhas.
Apague linhas e veja o que cada formato grava
Um delete remove as linhas que correspondem a um predicado. As linhas somem em todos os formatos, mas os arquivos que as continham podem ser tratados de duas maneiras. Em copy-on-write, o gravador reescreve cada arquivo de dados que continha uma linha correspondente e deixa de fora as linhas apagadas. Em merge-on-read, o gravador deixa o arquivo de dados intacto e grava um arquivo de delete que registra quais linhas foram removidas. Os leitores aplicam o arquivo de delete no momento da leitura.
As duas bibliotecas recebem o predicado em formas diferentes. O pyiceberg recebe um objeto de expressão, construído aqui a partir de EqualTo e LessThan. O deltalake recebe uma string SQL, que lembra a cláusula WHERE que o leitor já conhece. O delete abaixo usa as duas formas sobre as mesmas linhas, para que você possa compará-las diretamente.
O delete remove as linhas da hora 02 com menos de 180 visualizações, um limite escolhido neste capítulo. O corte no capítulo 1 mantém apenas as linhas mais visualizadas em cada hora, então um predicado para menos de duas visualizações não corresponde a nenhuma linha. Nesse caso, o pyiceberg emite UserWarning: Delete operation did not match any records e não grava snapshot, como mostra seu código-fonte. Um limite de 180 apanha algumas das linhas menos visualizadas da hora 02, o que basta para mostrar o que um delete grava.
1"""Runs one delete through Iceberg, Delta Lake and DuckLake and prints what each format removed and rewrote. The data-file lines carry the point; the deleted-row lines beside them are for comparison."""23from datetime import datetime45from deltalake import DeltaTable6from pyiceberg.expressions import And, EqualTo, LessThan78from lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, ducklake_file_count, load_three_formats, new_warehouse, read_delta, safe_error, scan_arrow910HOUR_02 = datetime(2024, 6, 3, 2)11# A threshold, not a fact about the data: the cut keeps the most-viewed rows of each hour, so a small one would match nothing.12LOW_VIEWS = 180131415def main():16 with new_warehouse() as wh:17 iceberg, delta_path, lake = load_three_formats(wh, range(6)) # hours 00 to 05, one commit per hour in each format18 iceberg_before = scan_arrow(iceberg).num_rows19 delta_before = read_delta(delta_path).num_rows20 table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"21 lake_before = lake.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0]22 files_before = ducklake_file_count(lake, DUCKLAKE_ALIAS, TABLE) # counted before the delete, to compare with the count after2324 iceberg.delete(And(EqualTo("hour_utc", HOUR_02), LessThan("views", LOW_VIEWS)))25 summary = iceberg.current_snapshot().summary # the snapshot summary counts each data file the delete removed from the table26 print("Iceberg deleted rows:", iceberg_before - scan_arrow(iceberg).num_rows)27 print("Iceberg remaining rows:", scan_arrow(iceberg).num_rows)28 print("Iceberg data files rewritten:", summary["deleted-data-files"])2930 delta = DeltaTable(delta_path)31 # the hour is written as a timestamp string inside the SQL predicate32 metrics = delta.delete(f"hour_utc = '2024-06-03T02:00:00' AND views < {LOW_VIEWS}")33 print("Delta Lake deleted rows:", delta_before - read_delta(delta_path).num_rows)34 print("Delta Lake remaining rows:", read_delta(delta_path).num_rows)35 print("Delta Lake data files rewritten:", metrics["num_removed_files"])3637 lake.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")38 lake_after = lake.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0]39 print("DuckLake deleted rows:", lake_before - lake_after)40 print("DuckLake remaining rows:", lake_after)41 print("DuckLake data files before:", files_before)42 print("DuckLake data files after:", ducklake_file_count(lake, DUCKLAKE_ALIAS, TABLE))43 # a delete file is listed against the data file it applies to, so counting the listed rows that have one counts the delete files44 print("DuckLake delete files written:", lake.execute(45 f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "46 "WHERE delete_file IS NOT NULL").fetchall()[0][0])474849if __name__ == "__main__":50 try:51 main()52 except Exception as exc: # the redacted error is what a reader sees53 print(safe_error(exc))54 raise SystemExit(1)
python delete-low-views.pyIceberg deleted rows: 4
Iceberg remaining rows: 2995
Iceberg data files rewritten: 1
Delta Lake deleted rows: 4
Delta Lake remaining rows: 2995
Delta Lake data files rewritten: 1
DuckLake deleted rows: 4
DuckLake remaining rows: 2995
DuckLake data files before: 6
DuckLake data files after: 6
DuckLake delete files written: 1
Os três formatos apagam o mesmo número de linhas: 4 no Iceberg, 4 no Delta Lake e 4 no DuckLake, mas os arquivos que reescrevem são diferentes.
O Iceberg reescreveu 1 arquivo de dados, o que continha a hora 02, e deixa 2995 linhas. O Delta Lake remove as mesmas linhas, deixa 2995 e reescreveu 1 arquivo. Os dois formatos reescreveram o arquivo da hora 02 e deixaram as outras cinco horas intactas, porque um arquivo é a unidade que um delete em copy-on-write substitui.
O DELETE do DuckLake deixa 2995 linhas e não reescreve nenhum arquivo de dados. Seus arquivos de dados permanecem em 6 antes do delete e 6 depois dele, e o delete grava 1 arquivo de delete.
O custo dos deletes do Iceberg e do Delta Lake acompanha o tamanho dos arquivos que eles tocam, não o número de linhas que removem. 4 linhas foram removidas, e 1 arquivo inteiro foi reescrito para isso. Uma tabela cujas correspondências estão espalhadas por muitos arquivos paga por cada um deles. Portanto, o custo depende de onde estão as linhas correspondentes.
Cada biblioteca informa suas próprias contagens, e este exemplo calcula as linhas apagadas como as linhas antes menos as linhas depois, de modo que as contagens de apagadas e restantes concordam por construção. As contagens de arquivos reescritos vêm da biblioteca: o deleted-data-files do resumo do snapshot do Iceberg e a métrica num_removed_files que o deltalake retorna de delete.
Copy-on-write e merge-on-read
Os dois estilos de escrita dividem o custo entre quem escreve e quem lê. O copy-on-write torna a escrita cara e a leitura barata: quem lê recebe as linhas como os arquivos as guardam, sem nada para aplicar. O merge-on-read torna a escrita barata, porque grava apenas as posições das linhas apagadas, e transfere o custo para as leituras até que algo reescreva os arquivos de dados.
Os três formatos deste capítulo diferem da seguinte forma.
| Formato | Biblioteca nas versões fixadas | Como a biblioteca grava um delete nas versões fixadas | Mostrado neste capítulo |
|---|---|---|---|
| Iceberg | pyiceberg 0.12.0 | Copy-on-write. delete reescreve os arquivos de dados que contêm linhas correspondentes e não grava arquivos de delete. Com write.delete.mode definido como merge-on-read, o pyiceberg emite o aviso "Merge on read is not yet supported, falling back to copy-on-write" (fonte). |
Sim, no exemplo de delete |
| Delta Lake | deltalake 1.6.6 | Copy-on-write. O arquivo com linhas correspondentes é reescrito, e o log registra o arquivo antigo como removido. | Sim, no exemplo de delete |
| DuckLake | DuckDB 2.0.0 | Merge-on-read. DELETE grava um arquivo de delete e deixa o arquivo de dados no lugar. |
Sim, no exemplo de delete |
A linha do DuckLake é mostrada pelo exemplo de delete, que conta o arquivo de delete e os arquivos de dados que permanecem no lugar. A documentação do DuckLake sobre deletion vectors descreve uma opção experimental que registra as posições das linhas apagadas em arquivos .puffin. Essa opção vem desativada por padrão, e este capítulo não a ativa. O custo de ler através dos arquivos de delete não é medido aqui. Quem lê uma tabela merge-on-read paga esse custo em cada varredura, até que os arquivos de dados sejam reescritos; por isso, meça esse custo na própria tabela.
O Delta Lake também tem deletion vectors, que registram as posições das linhas apagadas em um arquivo. Isso faz deles a opção merge-on-read do Delta, e não um terceiro estilo de escrita, e este livro não os utiliza. Nas versões fixadas, o deltalake 1.6.6 não grava um deletion vector: delete em uma tabela com o recurso ativado continua reescrevendo o arquivo. O protocolo Delta exige o recurso deletion-vectors nos reader features e nos writer features da tabela quando ela usa deletion vectors, e ativar o recurso o adiciona a ambos. QueryBuilder, que este livro usa em todas as leituras Delta, lê essa tabela. to_pyarrow_table e to_pyarrow_dataset a recusam, porque a tabela declara o recurso. Por isso, este livro mantém o recurso desativado, e seus deletes em Delta são copy-on-write.
Regra prática: Espere que os deletes copy-on-write custem uma reescrita de arquivo para cada arquivo que contenha uma correspondência. Prefira predicados cujas correspondências estejam em poucos arquivos, como uma hora, e agrupe em uma única escrita os deletes que você já conhece. O merge-on-read é adequado para uma tabela em que as escritas são frequentes e as leituras podem arcar com os arquivos de delete até que algo os reescreva.
Fazer upsert de uma hora corrigida
Um upsert atualiza a linha cuja chave coincide e insere a linha cuja chave não existe. Ele é a escrita certa para uma correção, porque a hora corrigida traz chaves que a tabela já tem, e a linha atrasada traz uma chave que a tabela ainda não tem. Um simples append guardaria as linhas corrigidas ao lado das originais, e cada página da hora apareceria duas vezes.
As duas subseções seguintes mostram o método do pyiceberg e o MERGE em SQL do DuckLake, ambos com o mesmo lote.
A chave encontra a linha à qual uma alteração se aplica, e decide quando duas linhas recebidas são a mesma linha. Uma chave estreita demais funde duas linhas reais em uma, e uma chave larga demais insere uma segunda cópia. A chave aqui é hour_utc, domain_code e page_title, a identidade que o corte dá a cada linha no capítulo 1. Os lotes dos exemplos trazem cada chave uma única vez.
Upserts no pyiceberg
O upsert do pyiceberg recebe uma tabela Arrow de linhas e as colunas que formam a chave, passadas como join_cols. Ele retorna a contagem de linhas que atualizou e a contagem de linhas que inseriu. Uma linha só é contada como atualizada quando alguma coluna que não é chave mudou, de modo que uma linha idêntica à da tabela não é contada como atualizada. O copy-on-write ainda reescreve essa linha quando o arquivo dela também contém uma linha alterada.
Envie a hora corrigida e a linha atrasada por meio de um único upsert e conte o que a chamada deixa no histórico da tabela.
1"""Upserts the corrected hour 02, with its late row, into the Iceberg table, then upserts the same batch again. The snapshot lines carry the point, in the order the commits were made."""23import pyarrow as pa45from lib.lakehouse import KEY, hour_corrections, load_three_formats, new_warehouse, read_cut_hour, safe_error, snapshot_labels678def main():9 with new_warehouse() as wh:10 iceberg, _, _ = load_three_formats(wh, range(6))11 before = {snapshot.snapshot_id for snapshot in iceberg.snapshots()} # so the loop below lists only the snapshots this upsert adds12 # hour_corrections halves the views of the first 20 page titles in byte order, so the same titles change on every run13 corrected = hour_corrections(read_cut_hour(2))14 # A late row: a page the first delivery of hour 02 did not have.15 late = corrected.slice(0, 1).set_column(16 corrected.schema.get_field_index("page_title"),17 "page_title",18 pa.array(["Late_arrival_example"], type=pa.string()),19 )20 batch = pa.concat_tables([corrected, late])2122 result = iceberg.upsert(batch, join_cols=list(KEY)) # KEY is the three key columns; a row matches when all three are equal23 # rows_updated counts only rows whose non-key values changed, so identical rows are not counted24 print("rows updated:", result.rows_updated)25 print("rows inserted:", result.rows_inserted)2627 iceberg.refresh()28 labels = snapshot_labels([snapshot.snapshot_id for snapshot in iceberg.snapshots()]) # snapshot IDs change on every run, so the labels number commits29 added = [snapshot for snapshot in iceberg.snapshots() if snapshot.snapshot_id not in before]30 for snapshot in added:31 label = labels[snapshot.snapshot_id]32 print(label, snapshot.summary.operation.value)33 # a snapshot that adds or deletes no records has no such key, so the count is 034 print(f"{label} records added:", snapshot.summary.get("added-records") or 0)35 print(f"{label} records deleted:", snapshot.summary.get("deleted-records") or 0)36 print("snapshots added:", len(added))3738 again = iceberg.upsert(batch, join_cols=list(KEY)) # the same batch again, as a retry would send it39 print("rows updated on second upsert:", again.rows_updated)40 print("rows inserted on second upsert:", again.rows_inserted)414243if __name__ == "__main__":44 try:45 main()46 except Exception as exc: # the redacted error is what a reader sees47 print(safe_error(exc))48 raise SystemExit(1)
python redeliver-hour-upsert.pyrows updated: 20
rows inserted: 1
snapshot 7 overwrite
snapshot 7 records added: 480
snapshot 7 records deleted: 500
snapshot 8 append
snapshot 8 records added: 20
snapshot 8 records deleted: 0
snapshot 9 append
snapshot 9 records added: 1
snapshot 9 records deleted: 0
snapshots added: 3
rows updated on second upsert: 0
rows inserted on second upsert: 0
Uma chamada de upsert não é um commit: esta gravou 3 snapshots para atualizar 20 linhas e inserir 1. A lista de snapshots mostra o que cada um registrou.
O primeiro snapshot é um overwrite. Ele remove 500 linhas, as linhas do arquivo da hora 02, e readiciona 480 delas sem alteração. Os dois seguintes são appends. O segundo adiciona 20 linhas alteradas, e o terceiro adiciona 1, a linha atrasada. Os rótulos vêm de snapshot_labels, então os números indicam a ordem dos commits.
No código-fonte do pyiceberg 0.12.0, upsert chama overwrite somente quando alguma linha mudou, e append para as linhas novas somente quando há alguma. overwrite grava dois snapshots, um delete e um append. A biblioteca registra o primeiro como overwrite, porque ele também grava linhas de volta. Assim, um lote com linhas alteradas e novas adiciona três snapshots, um com apenas linhas alteradas adiciona dois, e um com apenas linhas novas adiciona um. Conte-os na lista de snapshots, e não pela chamada da biblioteca.
Executar o mesmo upsert novamente não muda nada: ele informa 0 linhas atualizadas e 0 inseridas. Na segunda execução, todas as chaves já estão com o valor corrigido, então uma correção enviada duas vezes não altera a tabela duas vezes, e é isso que torna seguro repetir a operação.
Regra prática: Use upsert com join_cols definido como a chave, e leia as contagens do resultado. Conte os snapshots pela lista de snapshots e não presuma um commit por chamada. Execute o mesmo lote novamente quando não tiver certeza de que a primeira gravação foi concluída, e verifique se a segunda execução não informa atualizações.
MERGE no DuckLake
O DuckLake aplica a mesma correção como uma instrução MERGE em SQL. Uma instrução MERGE indica a tabela de destino, o lote de origem e a chave na cláusula ON, e cada cláusula WHEN diz o que fazer com uma linha correspondente ou não correspondente. A instrução abaixo é a que o exemplo seguinte executa.
MERGE INTO lake.wiki.pageviews_hourly AS t
USING batch AS s
ON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_title
WHEN MATCHED AND t.views <> s.views THEN UPDATE SET views = s.views
WHEN NOT MATCHED THEN INSERT (hour_utc, domain_code, page_title, views, response_bytes)
VALUES (s.hour_utc, s.domain_code, s.page_title, s.views, s.response_bytes)
O ramo WHEN NOT MATCHED também insere response_bytes, que é 0 em todas as linhas do recorte, de modo que o valor da linha tardia também é 0.
A condição AND t.views <> s.views é importante. Sem ela, o MERGE atualizaria e contaria toda linha correspondente, de modo que uma nova execução contaria todas outra vez. Com ela, uma linha correspondente cujas contagens já coincidem é deixada como está e não é contada. Nenhum exemplo executa a instrução sem a condição, portanto a afirmação sobre uma nova execução sem ela é uma leitura da instrução, não uma contagem medida.
1"""Merges the corrected hour 02 and its late row into the DuckLake copy with a SQL MERGE, then runs the same MERGE again. The matched-row line splits the changed count into inserts and updates; the second changed-row line is the rerun."""23import pyarrow as pa45from lib.lakehouse import hour_corrections, load_three_formats, new_warehouse, read_cut_hour, safe_error67# The WHEN MATCHED condition is what keeps a rerun from counting matched rows that already agree.8MERGE = """9MERGE INTO lake.wiki.pageviews_hourly AS t10USING batch AS s11ON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_title12WHEN MATCHED AND t.views <> s.views THEN UPDATE SET views = s.views13WHEN NOT MATCHED THEN INSERT (hour_utc, domain_code, page_title, views, response_bytes)14 VALUES (s.hour_utc, s.domain_code, s.page_title, s.views, s.response_bytes)15"""161718def main():19 with new_warehouse() as wh:20 _, _, lake = load_three_formats(wh, range(6))21 corrected = hour_corrections(read_cut_hour(2))22 # a copy of the hour's first row, with a page title the table never held23 late = corrected.slice(0, 1).set_column(24 corrected.schema.get_field_index("page_title"),25 "page_title",26 pa.array(["Late_arrival_example"], type=pa.string()),27 )28 lake.register("batch", pa.concat_tables([corrected, late]))29 print("source rows:", lake.execute("SELECT count(*) FROM batch").fetchall()[0][0])30 # the join counts source rows whose key the table already holds, which splits the changes into inserts and updates31 matched = lake.execute(32 "SELECT count(*) FROM lake.wiki.pageviews_hourly AS t JOIN batch AS s "33 "ON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_title"34 ).fetchall()[0][0]35 print("source rows matched:", matched)36 # DuckDB returns one count for a MERGE, with updates and inserts added together37 print("rows changed by the merge:", lake.execute(MERGE).fetchall()[0][0])38 print("rows changed by the same merge again:", lake.execute(MERGE).fetchall()[0][0])39 print("rows in table:", lake.execute("SELECT count(*) FROM lake.wiki.pageviews_hourly").fetchall()[0][0])404142if __name__ == "__main__":43 try:44 main()45 except Exception as exc: # the redacted error is what a reader sees46 print(safe_error(exc))47 raise SystemExit(1)
python merge-correction-ducklake.pysource rows: 501
source rows matched: 500
rows changed by the merge: 21
rows changed by the same merge again: 0
rows in table: 3000
Tal como o upsert, o merge é seguro para ser executado novamente: ele altera 21 linhas na primeira vez e 0 na segunda, e a tabela termina com 3000 linhas, as seis horas e a linha tardia.
A contagem de alterações soma os dois tipos de mudança, então a divisão exige o tamanho da origem. Das 501 linhas do lote, 500 correspondem a uma chave já presente na tabela, de modo que a única linha sem correspondência é a linha tardia. As linhas inseridas são as linhas da origem menos as linhas correspondentes, aqui 501 menos 500. As linhas atualizadas são as linhas alteradas menos as linhas inseridas. Uma contagem apenas das linhas correspondentes não dá nenhum dos dois números.
O DuckLake é anexado com o inlining desativado nestes exemplos, como explica o capítulo 1, de modo que cada carga grava arquivos de dados em vez de linhas no catálogo. As contagens do merge são de linhas.
Regra prática: escreva um MERGE com uma condição WHEN MATCHED AND que compare as colunas que você atualiza, para que uma nova execução não altere nada. Certifique-se de que a origem contém cada chave uma única vez antes de executá-lo. O DuckLake recusa um merge que associa uma linha do destino a duas linhas da origem, e a seção de produção mostra o erro.
Faça merge de um rótulo alterado na tabela de domínios
A segunda tabela deste livro, wiki.domains, associa cada código de domínio a um idioma. Uma tabela de dimensão guarda rótulos, não contagens, e um merge é adequado para poucos rótulos que mudam ao mesmo tempo. O ponto é que o mesmo formato de instrução funciona em uma tabela de dimensão, e a regra sobre condições se aplica também ali.
Um UPDATE alteraria o rótulo. O formato MERGE também tem uma cláusula WHEN NOT MATCHED, que insere um código de domínio que a tabela ainda não contém; assim, uma carga que adiciona um domínio pode usar a mesma instrução. Esta tabela existe apenas no DuckLake, portanto o merge é executado ali. A tabela de visualizações de página é mesclada no DuckLake em MERGE no DuckLake. Em um pipeline, o rótulo que você mescla aqui é o rótulo que o join do capítulo 8 retorna.
1"""Merges one changed language label into the DuckLake copy of the domains table, then runs the same MERGE again. Read the second changed-row line against the sorted table, which shows the label that merged in."""23import pyarrow as pa45from lib.lakehouse import attach_ducklake, connect_ducklake, print_rows, read_domains, new_warehouse, safe_error67MERGE = """8MERGE INTO lake.wiki.domains AS t9USING labels AS s10ON t.domain_code = s.domain_code11WHEN MATCHED AND t.language <> s.language THEN UPDATE SET language = s.language12WHEN NOT MATCHED THEN INSERT (domain_code, language) VALUES (s.domain_code, s.language)13"""141516def main():17 with new_warehouse() as wh:18 lake = connect_ducklake(wh.con)19 attach_ducklake(lake, "lake", wh.root, inlining_row_limit=0) # inlining off, so the rows land in data files20 lake.execute("CREATE SCHEMA lake.wiki")21 lake.execute("CREATE TABLE lake.wiki.domains (domain_code VARCHAR, language VARCHAR)")22 lake.register("dims", read_domains())23 lake.execute("INSERT INTO lake.wiki.domains SELECT * FROM dims")2425 # 'fr' is already in the table, so this label is an update and not an insert26 lake.register("labels", pa.table({"domain_code": ["fr"], "language": ["French (France)"]}))27 print("rows changed by the merge:", lake.execute(MERGE).fetchall()[0][0])28 print("rows changed by the same merge again:", lake.execute(MERGE).fetchall()[0][0])29 print_rows(lake.execute("SELECT domain_code, language FROM lake.wiki.domains").fetchall()) # sorted, so the order DuckLake returns rows in does not matter303132if __name__ == "__main__":33 try:34 main()35 except Exception as exc: # the redacted error is what a reader sees36 print(safe_error(exc))37 raise SystemExit(1)
python merge-domains-label.pyrows changed by the merge: 1
rows changed by the same merge again: 0
de German
en English
fr French (France)
ja Japanese
Mesclar um rótulo, fr de French para French (France), altera 1 linha, e uma segunda execução do mesmo merge altera 0. A tabela começa com as quatro linhas dos próprios dados do livro, e a tabela ordenada no final da saída mostra cada domínio com seu rótulo.
Regra prática: Faça merge de uma tabela de dimensão com a mesma condição WHEN MATCHED AND de uma tabela de fatos, e execute o merge uma segunda vez para verificar que ele não altera nada. Uma mudança de rótulo chega a toda consulta que faz join com a dimensão, então revise o rótulo que você está prestes a mesclar.
O que dá errado em produção
As correções dão errado na prática por meio de uma chave repetida, de um laço de deleções de uma linha e de uma contagem de snapshots que surpreende quem lê o histórico. Cada um deles é barato de verificar antes da escrita e caro de encontrar depois, por isso as verificações pertencem ao job que escreve o lote.
Uma chave repetida no lote. Uma correção enviada duas vezes, ou duas linhas com a mesma chave vindas de um join malfeito, tornam o lote inválido. Este exemplo envia uma linha corrigida duas vezes, e o pyiceberg recusa o upsert antes de escrever qualquer coisa.
1"""Sends a batch with one key twice to an Iceberg upsert and to a DuckLake MERGE, and prints each refusal with the row count after it. The two error lines carry the point: each names the cause of its refusal."""23import pyarrow as pa45from lib.lakehouse import KEY, hour_corrections, load_three_formats, new_warehouse, read_cut_hour, safe_error, scan_arrow67MERGE = """8MERGE INTO lake.wiki.pageviews_hourly AS t9USING batch AS s10ON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_title11WHEN MATCHED AND t.views <> s.views THEN UPDATE SET views = s.views12WHEN NOT MATCHED THEN INSERT (hour_utc, domain_code, page_title, views, response_bytes)13 VALUES (s.hour_utc, s.domain_code, s.page_title, s.views, s.response_bytes)14"""151617def main():18 with new_warehouse() as wh:19 iceberg, _, lake = load_three_formats(wh, range(6))20 corrected = hour_corrections(read_cut_hour(2))21 # A corrected row, sent twice: the batch holds two rows with one key.22 before = read_cut_hour(2)["views"].to_pylist() # the cut's views, to find the rows the correction changed23 changed = [i for i, after in enumerate(corrected["views"].to_pylist()) if after != before[i]]24 doubled = pa.concat_tables([corrected, corrected.slice(changed[0], 1)])2526 try:27 iceberg.upsert(doubled, join_cols=list(KEY))28 print("Iceberg upsert: no error")29 except Exception as exc:30 print("Iceberg upsert:", safe_error(exc, wh)) # safe_error replaces the warehouse path, so no local path is printed31 print("Iceberg rows after the failed upsert:", scan_arrow(iceberg).num_rows)3233 lake.register("batch", doubled)34 try:35 lake.execute(MERGE)36 print("DuckLake merge: no error")37 except Exception as exc:38 print("DuckLake merge:", safe_error(exc, wh))39 print("DuckLake rows after the failed merge:", lake.execute("SELECT count(*) FROM lake.wiki.pageviews_hourly").fetchall()[0][0])404142if __name__ == "__main__":43 try:44 main()45 except Exception as exc: # the redacted error is what a reader sees46 print(safe_error(exc))47 raise SystemExit(1)
python duplicate-source-keys.pyIceberg upsert: ValueError: Duplicate rows found in source dataset based on the key columns. No upsert executed
Iceberg rows after the failed upsert: 2999
DuckLake merge: InvalidInputException: Invalid Input Error: MERGE INTO command cannot affect the same target row more than once. A target row matched more than one source row; ensure the source rows are deduplicated or the ON condition is unique.
DuckLake rows after the failed merge: 2999
As duas recusas deixam a tabela com todas as linhas que ela tinha antes da escrita. O upsert do Iceberg lança um ValueError, e a tabela continua com 2999 linhas. O merge do DuckLake lança um InvalidInputException que nomeia a causa, uma linha de destino que correspondeu a mais de uma linha de origem, e a tabela continua com 2999 linhas. Um pipeline que captura o erro e tenta novamente o mesmo lote falha de novo, porque o problema está no lote. Remova as duplicatas da origem por chave antes da escrita. O merge do Delta Lake com chave repetida não é testado aqui (veja a primeira seção).
Um laço de deleções de uma linha. O copy-on-write faz com que cada deleção seja um commit que reescreve os arquivos que contêm as suas correspondências. Dez deleções em um laço reescrevem dez vezes o arquivo que contém as correspondências e deixam para trás dez snapshots ou versões. O modelo de custo, e não uma medição feita aqui, é o que sugere isso. Reúna as linhas a excluir e depois faça uma única deleção com um predicado que as cubra.
Uma contagem de snapshots que surpreende o leitor. Um único upsert com linhas alteradas e linhas novas adiciona 3 snapshots na execução acima. Um leitor que espera um commit por alteração vai achar o histórico mais longo do que o registro de alterações. Os snapshots permanecem nos metadados da tabela até serem expirados, o que o capítulo 7 explica, e cada um mantém os arquivos a que se refere.
Como você perceberia. Cada um destes problemas aparece em um número que você já registra. As contagens de linhas atualizadas e de linhas inseridas do resultado do pyiceberg, e a contagem de linhas alteradas de um merge, devem corresponder ao lote que você enviou. Uma reexecução que relata alterações significa que o lote é diferente do que você imagina. Uma contagem de snapshots que cresce mais rápido do que os snapshots que você espera por carga (até três, para um upsert) aponta para uma nova tentativa não idempotente, como um append enviado duas vezes. As recusas aparecem como exceções, então um job que as captura e continua parecerá saudável enquanto a tabela fica para trás.
Regra prática: Verifique o lote quanto a chaves repetidas antes de qualquer escrita, e trate uma recusa como um bug no lote, não como uma falha transitória. Reúna as deleções em uma única escrita. Conte os snapshots a partir da lista de snapshots ao auditar uma correção.
Decisões tomadas neste capítulo
- As correções são identificadas pela chave
hour_utc,domain_codeepage_title, e um lote deve conter cada chave uma única vez antes de ser gravado. - O exemplo de exclusão usa um limite de 180 visualizações, porque o corte mantém apenas as linhas mais visualizadas em cada hora; assim, um limite de dois não corresponde a nenhuma linha.
- As exclusões no Iceberg e no Delta Lake são do tipo copy-on-write, e seus exemplos mostram os arquivos que reescrevem.
- O
DELETEdo DuckLake grava um arquivo de exclusão e mantém os arquivos de dados no lugar, e o mesmo exemplo mostra isso. - Os vetores de exclusão não são usados. Nas versões fixadas, o deltalake 1.6.6 não os grava, e ativar esse recurso faz com que
to_pyarrow_tableeto_pyarrow_datasetrecusem a tabela. - Os upserts e os merges são verificados executando-os duas vezes: a segunda execução não altera nenhuma linha.
- As contagens de snapshots são lidas da lista de snapshots. O capítulo não trata uma chamada como um commit.
- Os exemplos do DuckLake desativam o inlining, como explica o capítulo 1, de modo que as contagens descrevem arquivos de dados.
- As correções são construídas em código, e a linha tardia é gerada; portanto, o que estes exemplos mostram é o caminho de gravação, e não o histórico de uma correção real.
- O exemplo de chave duplicada mostra a própria recusa, e não uma descrição dela; assim, a falha aparece na saída que o leitor vê.
- O capítulo não tem exemplo de upsert ou merge no Delta Lake; portanto, não faz nenhuma afirmação sobre o merge do deltalake além da exclusão.
- A linha tardia e a correção compartilham um mesmo lote; assim, uma única chamada mostra tanto uma atualização quanto uma inserção.
Este capítulo, nesta edição
Edição 2026.11.10Exemplos aprovados em 20 de nov de 20265 de 5 exemplos exemplos deste capítulo passam
Traduzido do livro em inglês, edição 2026.11.10.