Corrija linhas com deletes, updates e merges

Cerca de 22 minutos min de leitura, com 5 exemplos em 9 seções.

Edição 2026.11.10 Exemplos aprovados em 20 de nov de 2026 39 de 39 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.10. Leia o original

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

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

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

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

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.

delete-low-views.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""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."""from datetime import datetimefrom deltalake import DeltaTablefrom pyiceberg.expressions import And, EqualTo, LessThanfrom lib.lakehouse import DUCKLAKE_ALIAS, NAMESPACE, TABLE, ducklake_file_count, load_three_formats, new_warehouse, read_delta, safe_error, scan_arrowHOUR_02 = datetime(2024, 6, 3, 2)# 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.LOW_VIEWS = 180def main():    with new_warehouse() as wh:        iceberg, delta_path, lake = load_three_formats(wh, range(6))  # hours 00 to 05, one commit per hour in each format        iceberg_before = scan_arrow(iceberg).num_rows        delta_before = read_delta(delta_path).num_rows        table = f"{DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}"        lake_before = lake.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0]        files_before = ducklake_file_count(lake, DUCKLAKE_ALIAS, TABLE)  # counted before the delete, to compare with the count after        iceberg.delete(And(EqualTo("hour_utc", HOUR_02), LessThan("views", LOW_VIEWS)))        summary = iceberg.current_snapshot().summary  # the snapshot summary counts each data file the delete removed from the table        print("Iceberg deleted rows:", iceberg_before - scan_arrow(iceberg).num_rows)        print("Iceberg remaining rows:", scan_arrow(iceberg).num_rows)        print("Iceberg data files rewritten:", summary["deleted-data-files"])        delta = DeltaTable(delta_path)        # the hour is written as a timestamp string inside the SQL predicate        metrics = delta.delete(f"hour_utc = '2024-06-03T02:00:00' AND views < {LOW_VIEWS}")        print("Delta Lake deleted rows:", delta_before - read_delta(delta_path).num_rows)        print("Delta Lake remaining rows:", read_delta(delta_path).num_rows)        print("Delta Lake data files rewritten:", metrics["num_removed_files"])        lake.execute(f"DELETE FROM {table} WHERE hour_utc = TIMESTAMP '2024-06-03 02:00:00' AND views < {LOW_VIEWS}")        lake_after = lake.execute(f"SELECT count(*) FROM {table}").fetchall()[0][0]        print("DuckLake deleted rows:", lake_before - lake_after)        print("DuckLake remaining rows:", lake_after)        print("DuckLake data files before:", files_before)        print("DuckLake data files after:", ducklake_file_count(lake, DUCKLAKE_ALIAS, TABLE))        # a delete file is listed against the data file it applies to, so counting the listed rows that have one counts the delete files        print("DuckLake delete files written:", lake.execute(            f"SELECT count(*) FROM ducklake_list_files('{DUCKLAKE_ALIAS}', '{TABLE}', schema => '{NAMESPACE}') "            "WHERE delete_file IS NOT NULL").fetchall()[0][0])if __name__ == "__main__":    try:        main()    except Exception as exc:  # the redacted error is what a reader sees        print(safe_error(exc))        raise SystemExit(1)
Saídapython delete-low-views.py
Iceberg 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

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

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

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

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.

redeliver-hour-upsert.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""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."""import pyarrow as pafrom lib.lakehouse import KEY, hour_corrections, load_three_formats, new_warehouse, read_cut_hour, safe_error, snapshot_labelsdef main():    with new_warehouse() as wh:        iceberg, _, _ = load_three_formats(wh, range(6))        before = {snapshot.snapshot_id for snapshot in iceberg.snapshots()}  # so the loop below lists only the snapshots this upsert adds        # hour_corrections halves the views of the first 20 page titles in byte order, so the same titles change on every run        corrected = hour_corrections(read_cut_hour(2))        # A late row: a page the first delivery of hour 02 did not have.        late = corrected.slice(0, 1).set_column(            corrected.schema.get_field_index("page_title"),            "page_title",            pa.array(["Late_arrival_example"], type=pa.string()),        )        batch = pa.concat_tables([corrected, late])        result = iceberg.upsert(batch, join_cols=list(KEY))  # KEY is the three key columns; a row matches when all three are equal        # rows_updated counts only rows whose non-key values changed, so identical rows are not counted        print("rows updated:", result.rows_updated)        print("rows inserted:", result.rows_inserted)        iceberg.refresh()        labels = snapshot_labels([snapshot.snapshot_id for snapshot in iceberg.snapshots()])  # snapshot IDs change on every run, so the labels number commits        added = [snapshot for snapshot in iceberg.snapshots() if snapshot.snapshot_id not in before]        for snapshot in added:            label = labels[snapshot.snapshot_id]            print(label, snapshot.summary.operation.value)            # a snapshot that adds or deletes no records has no such key, so the count is 0            print(f"{label} records added:", snapshot.summary.get("added-records") or 0)            print(f"{label} records deleted:", snapshot.summary.get("deleted-records") or 0)        print("snapshots added:", len(added))        again = iceberg.upsert(batch, join_cols=list(KEY))  # the same batch again, as a retry would send it        print("rows updated on second upsert:", again.rows_updated)        print("rows inserted on second upsert:", again.rows_inserted)if __name__ == "__main__":    try:        main()    except Exception as exc:  # the redacted error is what a reader sees        print(safe_error(exc))        raise SystemExit(1)
Saídapython redeliver-hour-upsert.py
rows 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

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

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.

merge-correction-ducklake.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""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."""import pyarrow as pafrom lib.lakehouse import hour_corrections, load_three_formats, new_warehouse, read_cut_hour, safe_error# The WHEN MATCHED condition is what keeps a rerun from counting matched rows that already agree.MERGE = """MERGE INTO lake.wiki.pageviews_hourly AS tUSING batch AS sON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_titleWHEN MATCHED AND t.views <> s.views THEN UPDATE SET views = s.viewsWHEN 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)"""def main():    with new_warehouse() as wh:        _, _, lake = load_three_formats(wh, range(6))        corrected = hour_corrections(read_cut_hour(2))        # a copy of the hour's first row, with a page title the table never held        late = corrected.slice(0, 1).set_column(            corrected.schema.get_field_index("page_title"),            "page_title",            pa.array(["Late_arrival_example"], type=pa.string()),        )        lake.register("batch", pa.concat_tables([corrected, late]))        print("source rows:", lake.execute("SELECT count(*) FROM batch").fetchall()[0][0])        # the join counts source rows whose key the table already holds, which splits the changes into inserts and updates        matched = lake.execute(            "SELECT count(*) FROM lake.wiki.pageviews_hourly AS t JOIN batch AS s "            "ON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_title"        ).fetchall()[0][0]        print("source rows matched:", matched)        # DuckDB returns one count for a MERGE, with updates and inserts added together        print("rows changed by the merge:", lake.execute(MERGE).fetchall()[0][0])        print("rows changed by the same merge again:", lake.execute(MERGE).fetchall()[0][0])        print("rows in table:", lake.execute("SELECT count(*) FROM lake.wiki.pageviews_hourly").fetchall()[0][0])if __name__ == "__main__":    try:        main()    except Exception as exc:  # the redacted error is what a reader sees        print(safe_error(exc))        raise SystemExit(1)
Saídapython merge-correction-ducklake.py
source 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

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

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.

merge-domains-label.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""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."""import pyarrow as pafrom lib.lakehouse import attach_ducklake, connect_ducklake, print_rows, read_domains, new_warehouse, safe_errorMERGE = """MERGE INTO lake.wiki.domains AS tUSING labels AS sON t.domain_code = s.domain_codeWHEN MATCHED AND t.language <> s.language THEN UPDATE SET language = s.languageWHEN NOT MATCHED THEN INSERT (domain_code, language) VALUES (s.domain_code, s.language)"""def main():    with new_warehouse() as wh:        lake = connect_ducklake(wh.con)        attach_ducklake(lake, "lake", wh.root, inlining_row_limit=0)  # inlining off, so the rows land in data files        lake.execute("CREATE SCHEMA lake.wiki")        lake.execute("CREATE TABLE lake.wiki.domains (domain_code VARCHAR, language VARCHAR)")        lake.register("dims", read_domains())        lake.execute("INSERT INTO lake.wiki.domains SELECT * FROM dims")        # 'fr' is already in the table, so this label is an update and not an insert        lake.register("labels", pa.table({"domain_code": ["fr"], "language": ["French (France)"]}))        print("rows changed by the merge:", lake.execute(MERGE).fetchall()[0][0])        print("rows changed by the same merge again:", lake.execute(MERGE).fetchall()[0][0])        print_rows(lake.execute("SELECT domain_code, language FROM lake.wiki.domains").fetchall())  # sorted, so the order DuckLake returns rows in does not matterif __name__ == "__main__":    try:        main()    except Exception as exc:  # the redacted error is what a reader sees        print(safe_error(exc))        raise SystemExit(1)
Saídapython merge-domains-label.py
rows 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

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

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.

duplicate-source-keys.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Aprovado
"""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."""import pyarrow as pafrom lib.lakehouse import KEY, hour_corrections, load_three_formats, new_warehouse, read_cut_hour, safe_error, scan_arrowMERGE = """MERGE INTO lake.wiki.pageviews_hourly AS tUSING batch AS sON t.hour_utc = s.hour_utc AND t.domain_code = s.domain_code AND t.page_title = s.page_titleWHEN MATCHED AND t.views <> s.views THEN UPDATE SET views = s.viewsWHEN 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)"""def main():    with new_warehouse() as wh:        iceberg, _, lake = load_three_formats(wh, range(6))        corrected = hour_corrections(read_cut_hour(2))        # A corrected row, sent twice: the batch holds two rows with one key.        before = read_cut_hour(2)["views"].to_pylist()  # the cut's views, to find the rows the correction changed        changed = [i for i, after in enumerate(corrected["views"].to_pylist()) if after != before[i]]        doubled = pa.concat_tables([corrected, corrected.slice(changed[0], 1)])        try:            iceberg.upsert(doubled, join_cols=list(KEY))            print("Iceberg upsert: no error")        except Exception as exc:            print("Iceberg upsert:", safe_error(exc, wh))  # safe_error replaces the warehouse path, so no local path is printed        print("Iceberg rows after the failed upsert:", scan_arrow(iceberg).num_rows)        lake.register("batch", doubled)        try:            lake.execute(MERGE)            print("DuckLake merge: no error")        except Exception as exc:            print("DuckLake merge:", safe_error(exc, wh))        print("DuckLake rows after the failed merge:", lake.execute("SELECT count(*) FROM lake.wiki.pageviews_hourly").fetchall()[0][0])if __name__ == "__main__":    try:        main()    except Exception as exc:  # the redacted error is what a reader sees        print(safe_error(exc))        raise SystemExit(1)
Saídapython duplicate-source-keys.py
Iceberg 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

Última alteração na edição 2026.11.7
  • As correções são identificadas pela chave hour_utc, domain_code e page_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 DELETE do 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_table e to_pyarrow_dataset recusem 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.

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 5 de 10: Corrija linhas com deletes, updates e merges

  1. Dados atrasados chegam como correção
  2. Apague linhas e veja o que cada formato grava
  3. Copy-on-write e merge-on-read
  4. Fazer upsert de uma hora corrigida
  5. Upserts no pyiceberg
  6. MERGE no DuckLake
  7. Faça merge de um rótulo alterado na tabela de domínios
  8. O que dá errado em produção
  9. Decisões tomadas neste capítulo

Voltar ao topoTodos os capítulos