Corregir filas con deletes, updates y merges
Unos 18 minutos de lectura, con 5 ejemplos en 9 secciones.
Traducido con IA. Verificado por personas en inglés. Cómo hacemos los libros
Traducido del libro en inglés, edición 2026.11.10. Lee el original
En esta página
Las filas ya confirmadas también pueden cambiar: este capítulo las borra, hace upsert y las combina en Iceberg, Delta Lake y DuckLake, explica qué hace cada escritura con los archivos y cuenta los snapshots que añade un upsert de pyiceberg.
Hasta ahora la tabla solo crece. Cada escritura del capítulo 1 añadió datos a wiki.pageviews_hourly, una tabla en la que la fuente a veces vuelve a entregar datos de una hora ya cargada.
Los datos tardíos llegan como una corrección
La primera entrega de la hora 02 llegó a la tabla en el capítulo 1 con los conteos que la fuente envió en ese momento. Una entrega posterior de la misma hora trae conteos corregidos para algunas páginas, y una página que la primera entrega omitió. Las páginas de la corrección son las mismas páginas de antes, así que la tabla necesita cambiar filas en su lugar. Añadir la hora corregida almacenaría cada página dos veces, una con cada conteo.
En este libro, una fila se identifica por su clave: hour_utc, domain_code y page_title juntos. Una corrección es un conjunto de filas con claves, y para cada clave la tabla ya tiene una fila, que debe cambiar, o no la tiene, en cuyo caso debe añadirse. Escribir una corrección es, por tanto, una cuestión de claves, y la escritura la resuelve con una sola regla: una clave debe identificar una sola fila en el lote que escribes. pyiceberg y DuckLake aplican esa regla. Este capítulo no prueba una clave repetida en una fusión de deltalake.
Una corrección suele llegar como la hora completa, reenviada, y no como unas pocas filas. Enviar la hora completa mantiene el lote autocontenido, porque la escritura decide fila por fila qué cambió. El costo es que se comparan todas las filas de la hora, no solo las corregidas. Como se comparan todas las filas, pyiceberg puede contar solo las filas cuyos valores difieren, y volver a ejecutar el mismo lote no cambia nada.
Las correcciones aquí se construyen en código, a partir del corte real del capítulo 1. La función auxiliar hour_corrections reduce a la mitad los conteos de 20 títulos de página de la hora 02, redondeando hacia abajo. La fila tardía es una copia de la primera fila de la hora, con un título de página que la primera entrega nunca tuvo. Solo se genera el lote de corrección; las filas de pageviews son las que cortó el capítulo 1.
Regla práctica: Antes de escribir una corrección, comprueba que su lote contenga cada clave una sola vez. pyiceberg y DuckLake rechazan un lote con una clave repetida, cada uno a su manera, y reintentar no corrige los datos. La sección de producción muestra los fallos.
Eliminar filas y lo que escribe cada formato
Un borrado elimina las filas que cumplen un predicado. Las filas desaparecen en todos los formatos, pero los archivos que las contenían pueden tratarse de dos maneras. En copy-on-write, el escritor reescribe cada archivo de datos que contenía una fila coincidente y deja fuera las filas borradas. En merge-on-read, el escritor deja el archivo de datos intacto y escribe un archivo de borrado que registra qué filas ya no están. Los lectores aplican el archivo de borrado al escanear.
Las dos bibliotecas reciben el predicado en formas distintas. pyiceberg toma un objeto de expresión, construido aquí a partir de EqualTo y LessThan. deltalake toma una cadena SQL, que se parece a la cláusula WHERE que ya conoces. El borrado siguiente usa ambas formas sobre las mismas filas, para que puedas compararlas directamente.
El borrado elimina las filas de la hora 02 con menos de 180 visualizaciones, un umbral que este capítulo eligió. El recorte del capítulo 1 conserva solo las filas más vistas de cada hora, así que un predicado de menos de dos visualizaciones no coincide con nada. pyiceberg entonces avisa con UserWarning: Delete operation did not match any records y no escribe ninguna instantánea, como muestra su código fuente. Un umbral de 180 atrapa algunas de las filas menos vistas de la hora 02, lo que basta para mostrar lo que escribe un borrado.
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
Los tres formatos borran el mismo número de filas: 4 en Iceberg, 4 en Delta Lake y 4 en DuckLake, pero los archivos que reescriben difieren.
Iceberg reescribió 1 archivo de datos, el que contenía la hora 02, y deja 2995 filas. Delta Lake elimina las mismas filas, deja 2995 y reescribió 1 archivo. Ambos formatos reescribieron el archivo de la hora 02 y dejaron intactas las otras cinco horas, porque un archivo es la unidad que un borrado copy-on-write reemplaza.
El DELETE de DuckLake deja 2995 filas y no reescribe ningún archivo de datos. Sus archivos de datos siguen en 6 antes del borrado y en 6 después, y el borrado escribe 1 archivo de borrado.
El coste de los borrados de Iceberg y Delta Lake depende del tamaño de los archivos que tocan, no del número de filas que eliminan. Se fueron 4 filas, y para eliminarlas se reescribió 1 archivo completo. Una tabla cuyas coincidencias están repartidas entre muchos archivos paga por cada uno de ellos. Así, el coste depende de dónde estén las filas coincidentes.
Cada biblioteca informa sus propios recuentos, y este ejemplo calcula las filas borradas como las filas antes menos las filas después, de modo que los recuentos de borradas y restantes coinciden por construcción. Los recuentos de archivos reescritos proceden de la biblioteca: el deleted-data-files del resumen de la instantánea de Iceberg y la métrica num_removed_files que deltalake devuelve desde delete.
Copy-on-write y merge-on-read
Los dos estilos de escritura intercambian costo entre quien escribe y quien lee. Copy-on-write hace costosa la escritura y barata la lectura: quien lee obtiene las filas tal como están en los archivos, sin nada que aplicar. Merge-on-read hace barata la escritura, porque solo escribe las posiciones de las filas borradas, y traslada el costo a las lecturas hasta que algo reescriba los archivos de datos.
Los tres formatos de este capítulo difieren de la siguiente manera.
| Formato | Biblioteca con las versiones fijadas | Cómo escribe la biblioteca un borrado con las versiones fijadas | Se muestra en este capítulo |
|---|---|---|---|
| Iceberg | pyiceberg 0.12.0 | Copy-on-write. delete reescribe los archivos de datos que contienen filas coincidentes y no escribe archivos de borrado. Con write.delete.mode configurado en merge-on-read, pyiceberg advierte "Merge on read is not yet supported, falling back to copy-on-write" (fuente). |
Sí, en el ejemplo de borrado |
| Delta Lake | deltalake 1.6.6 | Copy-on-write. Se reescribe el archivo con filas coincidentes, y el log registra el archivo antiguo como eliminado. | Sí, en el ejemplo de borrado |
| DuckLake | DuckDB 2.0.0 | Merge-on-read. DELETE escribe un archivo de borrado y deja en su sitio el archivo de datos. |
Sí, en el ejemplo de borrado |
La fila de DuckLake se muestra en el ejemplo de borrado, que cuenta el archivo de borrado y los archivos de datos que permanecen en su sitio. La documentación de DuckLake sobre vectores de borrado describe una opción experimental que registra las posiciones de las filas borradas en archivos .puffin. Esa opción está desactivada por defecto, y este capítulo no la activa. El costo de leer a través de archivos de borrado no se mide aquí. Quien lee una tabla merge-on-read paga ese costo en cada escaneo hasta que se reescriben los archivos de datos, así que mídelo en tu propia tabla.
Delta Lake también tiene vectores de borrado, que registran en un archivo las posiciones de las filas borradas. Eso los convierte en la opción merge-on-read de Delta, no en un tercer estilo de escritura, y este libro no los usa. Con las versiones fijadas, deltalake 1.6.6 no escribe un vector de borrado: delete sobre una tabla con la característica activada sigue reescribiendo el archivo. El protocolo de Delta exige la característica de vectores de borrado en las características de lector y escritor de una tabla cuando la tabla usa vectores de borrado, y activar la característica la añade a ambas. QueryBuilder, que este libro usa para cada lectura de Delta, lee una tabla así. to_pyarrow_table y to_pyarrow_dataset la rechazan, porque la tabla declara la característica. Por eso este libro mantiene la característica desactivada, y sus borrados en Delta son copy-on-write.
Regla práctica: Espera que los borrados copy-on-write cuesten una reescritura de archivo por cada archivo que contenga una coincidencia. Prefiere predicados cuyas coincidencias estén en pocos archivos, como una hora, y agrupa en una sola escritura los borrados que conozcas. Merge-on-read conviene a una tabla donde las escrituras son frecuentes y las lecturas pueden asumir el costo de los archivos de borrado hasta que algo los reescriba.
Upsert de una hora corregida
Un upsert actualiza la fila cuya clave coincide e inserta la fila cuya clave no coincide. Es la escritura adecuada para una corrección, porque la hora corregida contiene las claves que la tabla ya tiene, y la fila tardía contiene una clave que la tabla todavía no tiene. Un simple append almacenaría las filas corregidas junto a las originales, de modo que cada página de la hora aparecería dos veces.
Las dos subsecciones siguientes muestran el método de pyiceberg y el SQL MERGE de DuckLake con el mismo lote.
La clave encuentra la fila a la que se aplica un cambio, y decide cuándo dos filas entrantes son la misma fila. Una clave demasiado estrecha colapsa dos filas reales en una, y una clave demasiado amplia inserta una segunda copia. La clave aquí es hour_utc, domain_code y page_title, la identidad que el corte asigna a cada fila en el capítulo 1. Los lotes de los ejemplos contienen cada clave una sola vez.
Upserts en pyiceberg
El método upsert de pyiceberg recibe una tabla de Arrow con filas y las columnas que forman la clave, pasadas como join_cols. Devuelve el número de filas que actualizó y el número que insertó. Una fila cuenta como actualizada solo cuando cambió alguna columna que no es clave, así que una fila idéntica a la de la tabla no se cuenta como actualizada. Aun así, copy-on-write vuelve a escribir esa fila cuando su archivo también contiene una fila modificada.
Envía la hora corregida y la fila tardía en una sola llamada a upsert, y cuenta lo que la llamada deja en el historial de la tabla.
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
Una llamada a upsert no es un solo commit: esta escribió 3 snapshots para actualizar 20 filas e insertar 1. La lista de snapshots muestra lo que registró cada uno.
El primer snapshot es un overwrite. Elimina 500 filas, las filas del archivo de la hora 02, y vuelve a añadir 480 de ellas sin cambios. Los dos siguientes son appends. El segundo añade 20 filas modificadas, y el tercero añade 1 fila, la fila tardía. Las etiquetas provienen de snapshot_labels, así que los números indican el orden de los commits.
En el código fuente de pyiceberg 0.12.0, upsert llama a overwrite solo cuando hay filas modificadas, y a append para las filas nuevas solo cuando las hay. overwrite escribe dos snapshots, un delete y un append. La biblioteca registra el primero como overwrite, porque también vuelve a escribir filas. Por tanto, un lote con filas modificadas y nuevas añade tres snapshots, uno con solo filas modificadas añade dos, y uno con solo filas nuevas añade uno. Cuéntalos en la lista de snapshots, no a partir de la llamada a la biblioteca.
Ejecutar el mismo upsert otra vez no cambia nada: informa 0 filas actualizadas y 0 insertadas. La segunda ejecución encuentra cada clave ya en su valor corregido, así que una corrección enviada dos veces no cambia la tabla dos veces, y eso es lo que hace seguro reintentar.
Regla práctica: Usa upsert con join_cols configurado con la clave, y lee sus conteos del resultado. Cuenta los snapshots en la lista de snapshots, y no supongas un commit por llamada. Ejecuta el mismo lote otra vez cuando no estés seguro de que la primera escritura se aplicó, y comprueba que la segunda ejecución no informa actualizaciones.
MERGE en DuckLake
DuckLake aplica la misma corrección como una sentencia MERGE en SQL. Una sentencia MERGE indica la tabla destino, el lote de origen y la clave en su cláusula ON, y cada cláusula WHEN dice qué hacer con una fila que coincide o que no coincide. La sentencia de abajo es la que ejecuta el ejemplo que sigue.
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)
La rama WHEN NOT MATCHED también inserta response_bytes, que es 0 en todas las filas del corte, de modo que el valor de la fila tardía también es 0.
La condición AND t.views <> s.views es importante. Sin ella, la MERGE actualizaría y contaría cada fila que coincide, de modo que una nueva ejecución volvería a contarlas todas. Con ella, una fila que coincide cuyos contadores ya son iguales se deja tal cual y no se cuenta. Ningún ejemplo ejecuta la sentencia sin la condición, así que la afirmación sobre una nueva ejecución sin ella es una interpretación de la sentencia, no un recuento medido.
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
Al igual que el upsert, el merge es seguro de volver a ejecutar: la primera vez cambia 21 filas y la segunda 0, y la tabla termina con 3000 filas, las de las seis horas y la fila tardía.
El recuento de cambios suma los dos tipos de cambio, así que para separarlos hace falta el tamaño del origen. De las 501 filas del lote, 500 coinciden con una clave que ya está en la tabla, de modo que la única fila sin coincidencia es la fila tardía. Las filas insertadas son las filas de origen menos las filas que coinciden, aquí 501 menos 500. Las filas actualizadas son las filas cambiadas menos las filas insertadas. Un recuento solo de filas que coinciden no da ninguno de los dos números.
DuckLake se conecta con la inserción en línea desactivada en estos ejemplos, como explica el capítulo 1, de modo que cada carga escribe archivos de datos y no filas en el catálogo. Los recuentos del merge son de filas.
Regla práctica: escribe un MERGE con una condición WHEN MATCHED AND que compare las columnas que actualizas, de modo que una nueva ejecución no cambie nada. Asegúrate de que el origen contiene cada clave una sola vez antes de ejecutarlo. DuckLake rechaza un merge que empareje una fila destino con dos filas de origen, y la sección de producción muestra el error.
Fusionar una etiqueta modificada en la tabla de dominios
La segunda tabla de este libro, wiki.domains, asocia cada código de dominio con un idioma. Una tabla de dimensión guarda etiquetas, no recuentos, y una fusión es adecuada para unas pocas etiquetas que cambian a la vez. La clave está en que la misma forma de sentencia funciona en una tabla de dimensión, y la regla sobre condiciones también se aplica allí.
Una UPDATE cambiaría la etiqueta. La forma MERGE también tiene una cláusula WHEN NOT MATCHED, que inserta un código de dominio que la tabla todavía no contiene, de modo que un flujo que añade un dominio puede usar la misma sentencia. Esta tabla existe solo en DuckLake, así que la fusión se ejecuta allí. La tabla de visitas de páginas se fusiona en DuckLake en MERGE en DuckLake. En un flujo de trabajo, la etiqueta que fusionas aquí es la que devuelve la unión del capítulo 8.
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
Al fusionar una etiqueta, fr de French a French (France), cambia 1 fila, y una segunda ejecución de la misma fusión cambia 0. La tabla empieza con las cuatro filas de los datos propios del libro, y la tabla ordenada al final de la salida muestra cada dominio con su etiqueta.
Regla práctica: Fusiona una tabla de dimensión con la misma condición WHEN MATCHED AND que usarías en una tabla de hechos, y ejecuta la fusión una segunda vez para comprobar que no cambia nada. Un cambio de etiqueta llega a cada consulta que se une con la dimensión, así que revisa la etiqueta que vas a fusionar.
Qué sale mal en producción
Las correcciones fallan en la práctica por una clave repetida, por un bucle de borrados de una sola fila y por un recuento de snapshots que sorprende a quien lee el historial. Cada uno de estos problemas es barato de comprobar antes de la escritura y caro de encontrar después, así que las comprobaciones pertenecen al trabajo que escribe el lote.
Una clave repetida en el lote. Una corrección enviada dos veces, o dos filas con la misma clave por un join incorrecto, hacen que el lote sea inválido. Este ejemplo envía una fila corregida dos veces, y pyiceberg rechaza el upsert antes de escribir nada.
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
Ambos rechazos dejan la tabla con todas las filas que tenía antes de la escritura. El upsert de Iceberg lanza un ValueError, y la tabla sigue con 2999 filas. La fusión de DuckLake lanza un InvalidInputException que indica la causa, una fila de destino que coincidió con más de una fila de origen, y la tabla sigue con 2999 filas. Un pipeline que captura el error y reintenta el mismo lote vuelve a fallar, porque el problema es el lote. Elimina los duplicados del origen por clave antes de la escritura. La fusión de Delta Lake con una clave repetida no se prueba aquí (consulta la primera sección).
Un bucle de borrados de una sola fila. La copia en escritura hace que cada borrado sea un commit que reescribe los archivos que contienen sus coincidencias. Diez borrados en un bucle reescriben diez veces el archivo que contiene sus coincidencias y dejan diez snapshots o versiones. Lo que lo sugiere es el modelo de costes, no una medición aquí. Reúne las filas a borrar y después escribe un único borrado con un predicado que las cubra todas.
Un recuento de snapshots que sorprende al lector. Un único upsert con filas modificadas y filas nuevas añade 3 snapshots en la ejecución anterior. Un lector que espera un commit por cada cambio encontrará el historial más largo que el registro de cambios. Los snapshots permanecen en los metadatos de la tabla hasta que caducan, algo que cubre el capítulo 7, y cada uno mantiene los archivos a los que se refiere.
Cómo lo notarías. Cada uno de estos problemas aparece en un número que ya registras. Los recuentos de filas actualizadas y de filas insertadas del resultado de pyiceberg, y el recuento de filas modificadas de una fusión, deben coincidir con el lote que enviaste. Una nueva ejecución que informa de cambios significa que el lote es distinto de lo que crees. Un recuento de snapshots que crece más deprisa de lo que esperas por carga (hasta tres para un upsert) apunta a un reintento no idempotente, como un append enviado dos veces. Los rechazos aparecen como excepciones, así que un trabajo que las captura y continúa parecerá sano mientras su tabla se queda atrasada.
Regla práctica: Comprueba el lote en busca de claves repetidas antes de cualquier escritura, y trata un rechazo como un error en el lote, no como un fallo transitorio. Reúne los borrados en una única escritura. Cuenta los snapshots a partir de la lista de snapshots cuando audites una corrección.
Decisiones que tomó este capítulo
- Las correcciones se emparejan por la clave
hour_utc,domain_codeypage_title, y un lote debe contener cada clave una sola vez antes de escribirse. - El ejemplo de borrado usa un umbral de 180 visitas, porque el recorte conserva solo las filas más vistas en cada hora, así que un umbral de dos no coincide con ninguna.
- Los borrados de Iceberg y Delta Lake son copy-on-write, y sus ejemplos muestran los archivos que reescriben. DuckLake
DELETEescribe un archivo de borrado y deja los archivos de datos en su lugar, y el mismo ejemplo lo muestra. - No se usan vectores de borrado. Con las versiones fijadas, deltalake 1.6.6 no los escribe, y activar la función hace que
to_pyarrow_tableyto_pyarrow_datasetrechacen la tabla. - Los upserts y las fusiones se comprueban ejecutándolos dos veces: la segunda ejecución no cambia ninguna fila.
- Los recuentos de snapshots se leen de la lista de snapshots. El capítulo no da por hecho que una llamada equivalga a una confirmación (commit).
- Los ejemplos de DuckLake desactivan la inserción en línea, como explica el capítulo 1, así que los recuentos describen archivos de datos.
- Las correcciones se construyen en código, y la fila tardía se genera, así que lo que muestran estos ejemplos es la ruta de escritura, no el historial de una corrección real.
- El ejemplo de clave duplicada muestra el rechazo en sí, no una descripción de él, de modo que el fallo está en la salida que ve el lector.
- El capítulo no tiene ningún ejemplo de upsert o fusión en Delta Lake, así que no hace afirmaciones sobre la fusión de deltalake más allá del borrado.
- La fila tardía y la corrección comparten un mismo lote, de modo que una sola llamada muestra tanto una actualización como una inserción.
Este capítulo, en esta edición
Edición 2026.11.10Ejemplos verificados el 20 de nov de 2026Superan la prueba 5 de 5 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.10.