Mueve una tabla entre formatos y verifica la copia
Unos 20 minutos de lectura, con 4 ejemplos en 7 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
Al terminar este capítulo sabrás copiar una tabla de un formato a otro y comprobar que la copia contiene las mismas filas. También podrás nombrar lo que la copia deja atrás, y decidir qué pérdidas aceptar y cuáles deben detener el traslado.
Los analistas quieren la tabla pageviews en DuckLake, donde consultan un archivo de catálogo a través de DuckDB. La tabla pageviews, wiki.pageviews_hourly, vive en Apache Iceberg desde el capítulo 1. Otro equipo mantiene sus tablas en Delta Lake y quiere las mismas filas en Iceberg. En ambos traslados la fuente permanece donde está, y el traslado es una copia hacia una tabla nueva. Una copia es una escritura única, y la mayor parte del trabajo está en las comprobaciones que la rodean. El capítulo realiza ambas copias y luego añade las comprobaciones que detectan pérdidas silenciosas.
Los ejemplos de este capítulo fijan 0.12.0 para pyiceberg, 1.6.6 para deltalake y 2.0.0 para DuckDB, que también ejecuta DuckLake. Cada ejemplo de copia construye su propia fuente pequeña en un almacén temporal, a partir de las mismas tres horas del corte de pageviews. Eso son 1499 filas.
Qué conserva una copia y qué pierde
Una copia lee las filas de una tabla en un momento dado y las escribe en otra tabla, en otro formato. Cada biblioteca de destino escribe sus propios archivos de datos, sus propios metadatos y su propio historial. Lo que sobrevive al traslado es lo que ambos lados pueden representar: las filas y las columnas cuyos tipos ambos lados soportan. Todo lo demás permanece en el origen, o tiene que volver a configurarse en el destino a mano.
Las pérdidas se ven con más facilidad en una tabla. Cada fila indica una parte de la tabla, lo que hace la copia con ella y dónde muestra este capítulo el resultado.
| Parte de la tabla | Después de la copia | Dónde lo muestra este capítulo |
|---|---|---|
| Filas y sus valores | Se conservan | La comprobación del resumen |
| Nombres y tipos de columnas | Se conservan cuando ambos formatos tienen el tipo | La sección de Delta Lake |
| Historial de confirmaciones | Se pierde. La copia inicia un historial propio | Ambas secciones de copia |
| Especificación de particiones | Se pierde, salvo que se configure en el destino | La sección de DuckLake |
| Marcas de tiempo por debajo de un microsegundo | Depende del formato: se rechazan, se truncan o se conservan | La sección de marcas de tiempo |
El historial es una pérdida que los lectores a menudo no notan. Iceberg registra los cambios como instantáneas, y Delta Lake registra cada confirmación como una versión. El capítulo sobre instantáneas y viaje en el tiempo mostró cómo las usa un lector. Una copia inicia un nuevo historial en el destino, de modo que el historial del destino empieza en el momento de la copia. El origen conserva su propio historial mientras lo mantengas. Nada en la copia hace referencia a él.
Una copia también es distinta del registro. Un archivo de metadatos registrado hace visible una tabla en un segundo catálogo sin tocar sus archivos, de modo que ambos catálogos leen los mismos datos. Una copia escribe archivos nuevos y no altera el origen, lo que significa que dos tablas ahora reciben escrituras y pueden divergir. Elige una copia cuando el destino deba poseer sus archivos y su historial. Elige el registro cuando los dos catálogos deban compartir un mismo conjunto de archivos, y acepta que los archivos compartidos deben permanecer donde están.
Las filas sobreviven porque la copia traslada valores, no archivos. Una copia no mueve archivos de datos. Lee valores de una tabla y escribe nuevos archivos Parquet para la otra. Por eso los nombres y el número de archivos difieren entre un origen y su copia, y por eso comparar nombres o números de archivos no sirve para verificar la copia. La comprobación debe comparar las filas.
Regla práctica: Antes de una copia, enumera lo que el origen contiene y el destino no conservará: su historial, su especificación de particiones y cualquier valor más fino de lo que el destino puede almacenar. Asigna a cada elemento una decisión: aceptar la pérdida, configurar la propiedad a mano en el destino o detener el traslado. El manual de operaciones debe nombrar cada decisión.
Copia la tabla pageviews a DuckLake
La copia lee la tabla Iceberg con scan_arrow, y luego entrega esas filas a DuckLake. DuckLake crea una tabla vacía con sus columnas, le asigna la especificación de partición y después inserta las filas con INSERT ... SELECT. Arrow es el puente porque cada lado conserva su propia biblioteca. pyiceberg lee el origen, y DuckDB escribe la tabla de DuckLake mediante su propia extensión ducklake. Ninguno de los dos lados lee los archivos del otro. El capítulo del catálogo mostró cómo se adjunta el catálogo de DuckLake, y el asistente de este capítulo lo adjunta de la misma manera.
El origen está particionado por la hora de hour_utc, que es la disposición a la que llega pasar de particiones diarias a horarias. Aquí pyiceberg construye ese origen con la especificación horaria y luego añade tres horas, con una confirmación por cada una:
1"""Copy an Iceberg table into DuckLake through Arrow, then print what the copy kept of the layout and the history.23The point rests on the copy partition transforms and copy files per partition lines, which show whether the4layout arrived with the rows, and on the copy snapshot lines, which show the history starting at the copy."""56from pyiceberg.partitioning import PartitionField, PartitionSpec7from pyiceberg.transforms import HourTransform89from lib.lakehouse import (copy_to_ducklake, create_iceberg_table, ducklake_files_by_partition, ducklake_partition_transforms,10 new_warehouse, read_cut_hour, safe_error, scan_arrow, TABLE)111213def main():14 try:15 with new_warehouse() as wh:16 # source_id 1 is the field ID of hour_utc in the table lib creates17 spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=HourTransform(), name="ts_hour"))18 table = create_iceberg_table(wh, partition_spec=spec)19 for hour in range(3):20 table.append(read_cut_hour(hour))21 arrow = scan_arrow(table)22 print(f"source rows: {arrow.num_rows}")23 print(f"source snapshots: {len(table.metadata.snapshots)}")24 for field in table.spec().fields:25 print(f"source partition field: {field.name}")2627 # the helper creates the copy empty, sets this spec with ALTER, and only then inserts the rows28 target = copy_to_ducklake(wh, arrow, partition_by="hour(hour_utc)")29 print(f"copy rows: {wh.con.execute(f'SELECT count(*) FROM {target}').fetchall()[0][0]}")30 # current=True keeps only the spec still in force; an earlier spec would otherwise be listed too31 print(f"copy partition transforms: {ducklake_partition_transforms(wh.con, table=TABLE, current=True)}")32 # one (partition value, files, rows) tuple per partition, in value order33 files = ducklake_files_by_partition(wh.con, "lake", TABLE)34 print(f"copy partition values: {[value for value, _, _ in files]}")35 print(f"copy files per partition: {[count for _, count, _ in files]}")36 print(f"copy rows per partition: {[int(rows) for _, _, rows in files]}")37 changes = wh.con.execute("SELECT changes FROM ducklake_snapshots('lake') ORDER BY snapshot_id").fetchall()38 # labels start at 1, so label N is the snapshot whose snapshot_id is N-139 for number, (change,) in enumerate(changes, start=1):40 print(f"copy snapshot {number}: {', '.join(sorted(change))}")41 except Exception as exc:42 print(safe_error(exc))43 raise SystemExit(1)444546if __name__ == "__main__":47 main()
python iceberg-to-ducklake-copy.pysource rows: 1499
source snapshots: 3
source partition field: ts_hour
copy rows: 1499
copy partition transforms: ['hour']
copy partition values: ['0', '1', '2']
copy files per partition: [1, 1, 1]
copy rows per partition: [499, 500, 500]
copy snapshot 1: schemas_created
copy snapshot 2: schemas_created
copy snapshot 3: tables_created
copy snapshot 4: tables_altered
copy snapshot 5: tables_inserted_into
El asistente scan_arrow lee el origen en su instantánea actual y devuelve todas las filas de esa instantánea como una sola tabla Arrow. Por lo tanto, la copia contiene las filas de un único momento, la última confirmación que vio el escaneo. Los escritores que confirman después del escaneo no están en la copia, y nada en la copia lo indica. Las confirmaciones que llegan después del escaneo de una copia y nunca llegan a ella son el problema del traspaso (cutover), al que vuelve la sección de producción.
Dos preguntas deciden la copia: ¿llegaron las filas y la disposición?, ¿y qué historial llegó con ellas? La salida responde a ambas.
Primero el origen. Imprime el número de filas, el número de instantáneas y los campos de partición. El origen tiene 3 instantáneas, una por cada añadido, y un campo de partición, ts_hour, una transformación por hora de hour_utc.
Después, el número de filas de la copia, que es 1499. El número de filas es igual al del origen. Es una primera comprobación útil, pero la sección de sumas de verificación (digest) que sigue explica por qué no basta por sí sola.
Una copia puede perder su disposición sin que aparezca ningún error, así que el orden de las sentencias importa. El asistente crea la copia como tabla vacía, ejecuta ALTER TABLE ... SET PARTITIONED BY (hour(hour_utc)) sobre ella y solo después inserta las filas. La documentación de particionado de DuckLake indican que las claves de partición "solo afectan a los datos nuevos escritos en la tabla", así que un ALTER ejecutado después de que las filas estén dentro dejaría los datos sin particionar. El asistente conserva solo la especificación que sigue vigente y muestra una transformación, hour. La lista indica lo que se le dio a la copia. Los archivos indican lo que contiene: la copia escribe [1, 1, 1] archivos, y las filas se reparten entre ellos como [499, 500, 500]. Una copia hecha en una sola sentencia no lleva especificación de partición, así que su lista está vacía y sus filas quedan en archivos sin particionar. Las filas están todas en ambos casos, por lo que la comprobación debe mirar la disposición.
La lista de particiones lee la tabla de catálogo ducklake_partition_column, tal como la define la especificación de DuckLake, a través de la base de datos de metadatos adjunta. Ninguna función pública la devuelve en esta versión fijada.
Por último, la lista de instantáneas muestra el historial de la copia. Cada línea indica el número de una instantánea y los cambios que hizo. Las etiquetas cuentan cada instantánea que DuckLake registra, incluida la configuración inicial, como en el capítulo 2. Las dos primeras instantáneas crean el esquema predeterminado y el esquema wiki. La tercera crea la tabla vacía, la cuarta le asigna su especificación de partición y la quinta escribe las filas en la tabla que ya está particionada. Los tres añadidos horarios del origen no aparecen. El historial de la copia empieza con su propia creación, así que el viaje en el tiempo sobre la copia solo llega hasta ese punto. Para leer el origen tal como estaba después de la primera hora, todavía necesitas la tabla Iceberg.
El asistente de adjuntado también fija DATA_INLINING_ROW_LIMIT en 0, de modo que las filas copiadas se escriben como archivos Parquet, y los recuentos anteriores corresponden a esos archivos.
Regla práctica: Copia a través de Arrow con el escritor propio del destino. Crea el destino vacío, asigna su especificación de partición con un ALTER y solo entonces inserta las filas. Imprime la lista de particiones del destino y sus archivos por partición. Lee las instantáneas de la copia como el historial propio de la copia, y conserva el origen hasta que pasen las comprobaciones de las dos últimas secciones.
Copiar la tabla de Delta en una tabla de pyiceberg
La fuente Delta se construye del modo en que lo haría el pipeline de un equipo: tres appends con deltalake, uno por hora. Los tres appends son las versiones 0, 1 y 2. La copia lee las filas actuales con read_delta y las añade a una tabla de Iceberg creada con el esquema de destino:
1"""Copy a Delta Lake table into Iceberg through Arrow, then compare the copy with its source.23The point rests on the delta versions and iceberg snapshots lines, which show several commits becoming one,4and on the two column listings, which show the names carried across."""56from deltalake import DeltaTable78from lib.lakehouse import (create_iceberg_table, new_warehouse, print_schema, read_delta, safe_error, scan_arrow,9 write_delta_hours)101112def main():13 try:14 with new_warehouse() as wh:15 path = write_delta_hours(wh.root, range(3))16 source = read_delta(path)17 # Delta numbers its versions from 0, so the count is the last version plus one18 print(f"delta versions: {DeltaTable(path).version() + 1}")19 print(f"delta rows: {source.num_rows}")20 print("delta columns (name, type, nullability):")21 print_schema(source.schema)2223 table = create_iceberg_table(wh)24 table.append(source)25 print(f"iceberg snapshots: {len(table.metadata.snapshots)}")26 print(f"iceberg rows: {scan_arrow(table).num_rows}")27 print("iceberg columns (name, type, requirement):")28 # sorted by name, so the two listings line up row for row29 for field in sorted(table.schema().fields, key=lambda field: field.name):30 # Iceberg calls a nullable field optional, so the listing says optional where Delta says nullable31 requirement = "required" if field.required else "optional"32 print(f"{field.name}\t{field.field_type}\t{requirement}")33 except Exception as exc:34 print(safe_error(exc))35 raise SystemExit(1)363738if __name__ == "__main__":39 main()
python delta-to-iceberg-copy.pydelta versions: 3
delta rows: 1499
delta columns (name, type, nullability):
domain_code string nullable
hour_utc timestamp[us] nullable
page_title string nullable
response_bytes int64 nullable
views int64 nullable
iceberg snapshots: 1
iceberg rows: 1499
iceberg columns (name, type, requirement):
domain_code string optional
hour_utc timestamp optional
page_title string optional
response_bytes long optional
views long optional
La copia tiene tantas filas como la fuente, pero deja atrás el historial. La tabla Delta tiene 3 versiones y 1499 filas. La tabla de Iceberg se construye a partir de un único append de todas ellas, así que tiene 1 snapshot, el inicio de su propio historial, igual que la copia de DuckLake. Su número de filas, 1499, es el mismo que el de la fuente.
El resto de la salida enumera ambos esquemas, una columna por línea. Léelos uno al lado del otro:
| Columna | Delta Lake (tipo Arrow) | Tipo Iceberg |
|---|---|---|
domain_code |
string |
string |
hour_utc |
timestamp[us] |
timestamp |
page_title |
string |
string |
response_bytes |
int64 |
long |
views |
int64 |
long |
Los nombres pasan sin cambios, porque la copia los toma del esquema Arrow. Los tipos se corresponden uno a uno. El único cambio de escritura es int64 en Arrow, que Iceberg llama long. Ambos lados usan microsegundos para hour_utc, y la comprobación de timestamps más abajo explica qué ocurre cuando no coinciden.
pyiceberg es estricto con los nombres. Comprueba el esquema Arrow frente al esquema de la tabla antes de escribir. Se detiene con un error de incompatibilidad cuando un nombre de columna difiere, o cuando un tipo no puede promoverse al tipo de la tabla. Acepta un tipo que puede promover, como int a long. Esa comprobación está en la función _check_pyarrow_schema_compatible de la biblioteca fijada, en pyiceberg/io/pyarrow.py. La tabla Delta tampoco puede renombrar una columna con la versión fijada, como mostró la sección de renombrado del capítulo de esquemas. Si los dos lados no coinciden en un nombre, cambias el destino, no la fuente. pyiceberg asocia las columnas Arrow con la tabla por nombre, así que los IDs de campo del destino proceden del esquema que escribes. Escribes tú mismo el esquema de destino, en lugar de dejar que lo decida el primer lote.
Regla práctica: Escribe tú el esquema de destino, con los tipos que quieras, e imprime ambos esquemas tras la copia, como hace el ejemplo. Acepta un tipo casi equivalente, como int64 a long, solo después de haberlo comprobado en la salida. No aceptes un nombre que difiera.
Verifica la precisión de las marcas de tiempo antes de la copia
Las marcas de tiempo son un punto en el que los formatos no coinciden, a veces sin avisar. La especificación de Iceberg define las marcas de tiempo en nanosegundos como un tipo de la versión 3, así que una tabla de la versión 2 no tiene tipo para ellas (la especificación de Iceberg, sección de la versión 3). La tabla del ejemplo es de la versión 2, la predeterminada. En esta versión fijada de pyiceberg, este se niega a escribir la versión 3, así que los valores en nanosegundos solo pueden conservarse con un formato distinto de Iceberg. Este ejemplo escribe dos valores que solo difieren por debajo de un microsegundo, 1000000500 y 1000000999 nanosegundos, en cada formato:
1"""Write two timestamps that differ only below a microsecond to Iceberg, Delta Lake and DuckLake, and show what each kept.23The point rests on the Iceberg error line and on the Delta and DuckLake read-back lines."""45import pyarrow as pa6from deltalake import write_deltalake7from pyiceberg.schema import Schema8from pyiceberg.types import NestedField, TimestampType910from lib.lakehouse import copy_to_ducklake, new_warehouse, NAMESPACE, read_delta, safe_error, sql_rows1112# nanoseconds since 1970: one second plus 500 and 999 nanoseconds, so the two values differ below a microsecond13NANOSECONDS = pa.table({"hour_utc": pa.array([1000000500, 1000000999], pa.timestamp("ns"))})141516def main():17 try:18 with new_warehouse() as wh:19 # cast to int64 gives the integer behind each timestamp, so distinct values are counted exactly20 print(f"written distinct values: {len(set(NANOSECONDS['hour_utc'].cast(pa.int64()).to_pylist()))}")21 # TimestampType stores microseconds; a version 2 table has no nanosecond type to declare instead22 table = wh.catalog.create_table(23 f"{NAMESPACE}.precision",24 schema=Schema(NestedField(1, "hour_utc", TimestampType(), required=False)),25 )26 try:27 # this append raises, because the table cannot hold nanoseconds; the except prints the error28 table.append(NANOSECONDS)29 except Exception as exc:30 print(f"iceberg append: {safe_error(exc, wh)}")3132 path = str(wh.root / "precision")33 write_deltalake(path, NANOSECONDS, mode="overwrite")34 # the cast reads the count in the column's unit, which Delta wrote as microseconds, so 1000000 is one second35 kept = read_delta(path)["hour_utc"].cast(pa.int64()).to_pylist()36 print(f"delta read back as microseconds: {kept}")37 print(f"delta distinct values read back: {len(set(kept))}")3839 target = copy_to_ducklake(wh, NANOSECONDS)40 # epoch_ns returns nanoseconds since 1970, so a value cut to microseconds would end in three zeros41 rows = sql_rows(wh.con, f"SELECT epoch_ns(hour_utc) FROM {target}")42 print(f"ducklake epoch nanoseconds read back: {[row[0] for row in rows]}")43 except Exception as exc:44 print(safe_error(exc))45 raise SystemExit(1)464748if __name__ == "__main__":49 main()
python timestamp-precision-check.pywritten distinct values: 2
iceberg append: UnsupportedPyArrowTypeException: Column 'hour_utc' has an unsupported type: timestamp[ns]
delta read back as microseconds: [1000000, 1000000]
delta distinct values read back: 1
ducklake epoch nanoseconds read back: [1000000500, 1000000999]
La primera línea es la entrada, dos valores distintos. Luego cada formato responde a su manera.
La adición (append) en Iceberg falla. El error es UnsupportedPyArrowTypeException: Column 'hour_utc' has an unsupported type: timestamp[ns]. El error nombra la columna y el tipo, así que el fallo es el más claro de los tres casos, y por defecto no se altera nada en silencio. El error de pyiceberg nombra una configuración, PYICEBERG_DOWNCAST_NS_TIMESTAMP_TO_US_ON_WRITE, que convierte los nanosegundos a microsegundos al escribir. Con ella activada, la misma escritura se completa y los valores se leen de nuevo como microsegundos enteros, con solo una advertencia registrada. Es el mismo recorte que hace Delta, así que actívala solo en un trabajo que haya decidido recortar los valores, y no en un entorno que comparten todos los escritores.
La escritura en Delta se completa, y la lectura posterior muestra [1000000, 1000000]. Ambos valores se recortaron a microsegundos enteros, y los dos valores distintos se convirtieron en uno. La escritura no produjo ningún error, y el número de filas es el mismo. Solo una comprobación de los valores muestra la pérdida. El recuento de valores distintos baja de 2 a 1.
DuckLake conserva los nanosegundos. Su tabla guarda los dos valores tal como se escribieron, y el ejemplo los lee de nuevo como [1000000500, 1000000999].
La tabla de visitas a páginas registra horas, así que en ese caso el problema nunca aparece. Una tabla de registros de peticiones sin procesar sí lo presenta. Sus marcas de tiempo proceden de un reloj que cuenta con más precisión que un microsegundo, y su copia tiene que elegir una regla para esos dígitos. Haz esta pregunta para cada columna de marca de tiempo antes de la primera copia, porque la respuesta solo se ve en los valores. Las copias de este capítulo usan marcas de tiempo en microsegundos, que los tres formatos conservan, así que las copias coinciden. Una tabla real puede contener valores por debajo de un microsegundo desde su origen, y la copia debe decidir qué hacer con ellos antes de la primera escritura.
Regla práctica: Verifica la precisión de las marcas de tiempo con un valor por debajo de un microsegundo antes de la primera copia. Elige la regla de antemano. Convierte la columna a microsegundos y cuenta los valores que la conversión cambia, rechaza la copia o escribe en un formato que conserve los nanosegundos. No dejes la elección a la biblioteca de escritura, porque un recorte silencioso no da ningún error que puedas atender.
Verifica cada copia con un resumen ordenado
Un número de filas igual no demuestra que los valores coincidan. Una copia puede conservar el número y cambiar un valor, y el conteo no lo mostrará. Un resumen sí. El resumen de una tabla es un hash de sus filas ordenadas: digest_rows ordena las filas, escribe cada una como una línea de texto y calcula el hash del resultado. La ordenación hace que el resumen no dependa del orden en que se devuelven las filas, de modo que dos copias con las mismas filas obtienen el mismo resumen, sin importar cómo las devuelva cada formato. digest_rows se ejecuta en ambas copias, y en una copia con un conteo de vistas cambiado a propósito:
1"""Check each copy against its source with a sorted digest, and show that one changed value fails it.23The point rests on the two iceberg to ducklake digest lines: the copy matches its source, and a copy with one4changed count does not."""56from lib.lakehouse import (copy_to_ducklake, create_iceberg_table, digest_rows, new_warehouse, read_cut_hour,7 read_delta, safe_error, scan_arrow, sql_rows, write_delta_hours)8910def same(source, copy):11 return digest_rows(source) == digest_rows(copy)121314def check_iceberg_to_ducklake():15 with new_warehouse() as wh:16 table = create_iceberg_table(wh)17 for hour in range(3):18 table.append(read_cut_hour(hour))19 target = copy_to_ducklake(wh, scan_arrow(table))20 source_rows = sql_rows(wh.con, "SELECT * FROM source", source=scan_arrow(table))21 copy_rows = wh.con.execute(f"SELECT * FROM {target}").fetchall()22 first = copy_rows[0]23 # the copy's columns are hour_utc, domain_code, page_title, views, response_bytes, so index 3 is views24 changed = [(*first[:3], first[3] + 1, first[4]), *copy_rows[1:]]25 print(f"iceberg to ducklake rows: {len(source_rows)} and {len(copy_rows)}")26 matches = same(source_rows, copy_rows)27 # printed before the assert, so a failing run still shows the word28 print(f"iceberg to ducklake digests: {'match' if matches else 'differ'}")29 assert matches30 still_matches = same(source_rows, changed)31 print(f"iceberg to ducklake with one changed view count digests: {'match' if still_matches else 'differ'}")32 # one changed count must change the digest33 assert not still_matches343536def check_delta_to_iceberg():37 with new_warehouse() as wh:38 path = write_delta_hours(wh.root, range(3))39 table = create_iceberg_table(wh)40 table.append(read_delta(path))41 source_rows = sql_rows(wh.con, "SELECT * FROM source", source=read_delta(path))42 copy_rows = sql_rows(wh.con, "SELECT * FROM copy", copy=scan_arrow(table))43 print(f"delta to iceberg rows: {len(source_rows)} and {len(copy_rows)}")44 assert same(source_rows, copy_rows)454647def main():48 try:49 check_iceberg_to_ducklake()50 check_delta_to_iceberg()51 except Exception as exc:52 print(safe_error(exc))53 raise SystemExit(1)545556if __name__ == "__main__":57 main()
python verify-copies-by-digest.pyiceberg to ducklake rows: 1499 and 1499
iceberg to ducklake digests: match
iceberg to ducklake with one changed view count digests: differ
delta to iceberg rows: 1499 and 1499
Basta un número cambiado para que cambie el resumen, así que un resumen que coincide es evidencia, y uno que difiere es una señal para detenerse. Para la copia de Iceberg a DuckLake, la salida imprime los dos números de filas, que son iguales, y luego los resúmenes match. La misma comprobación sobre la copia de Delta a Iceberg también coincide. Con un conteo de vistas cambiado, los resúmenes differ.
El resumen compara los valores tal como los devuelve la base de datos, y tiene un límite. Si ambos lados se convierten a texto antes de calcular el hash, dos valores de tipos distintos pueden producir el mismo texto. El entero 1 y el texto '1' son el mismo texto. Compara valores tipados, como hace el ejemplo, e imprime los esquemas como lo hizo la copia de Delta a Iceberg. El resumen tampoco dice nada sobre los nombres ni los tipos de las columnas. Dos tablas con las mismas filas bajo nombres de columna distintos tienen el mismo resumen. Los listados de esquema de las secciones anteriores comprueban los nombres, y el resumen comprueba los valores, así que una copia necesita ambos.
El resumen no es un hash de los archivos. Las filas se ordenan por sus valores tipados, cada una se convierte en una línea con su representación de Python, y el texto unido se procesa con el hash SHA-256. Dos filas con valores iguales producen líneas iguales, que es lo que necesita la comparación. Un cambio en un valor cambia una línea y, por tanto, todo el resumen.
Elige también el momento de la comprobación. Un resumen es válido solo para las filas que existían cuando se ejecutó. Cualquier escritura en el origen posterior a ese punto deja la copia desactualizada, y el resumen de antes de la escritura ya no sirve. La comprobación debe hacerse después de la última escritura en el origen y antes de que alguien lea de la copia.
Regla práctica: Calcula el resumen de ambos lados después de la última escritura en el origen, sobre las mismas columnas, con valores tipados. Compara los números de filas y los resúmenes juntos. No cambies a los lectores ni elimines el origen hasta que ambos coincidan. Si hubo escritores durante la copia, repite la copia y el resumen.
Qué sale mal en producción
Una migración fallida suele superar la primera comprobación y fallar después. Estos son los fallos que conviene buscar, y cómo notarías cada uno.
- Un corte que compite con un escritor. Un resumen de verificación cubre solo las filas que leyó, como dice la sección de resúmenes. La primera adición posterior deja la copia desactualizada, y el resumen no te avisa. Detén los escritores, copia, calcula el resumen y después traslada los lectores. Si los escritores no pueden detenerse, copia por ventanas y revisa las filas que llegaron después de la última ventana.
- Borrar el origen antes de que pasen las comprobaciones. El origen guarda el historial que la copia no tiene. Una vez eliminado el origen, desaparece con él el acceso a sus snapshots y versiones. Conserva el origen hasta que los resúmenes coincidan y todos los lectores se hayan trasladado. Después decide, por escrito, cuánto tiempo conservarlo.
- Una copia con las filas pero sin la disposición. Una copia hecha sin el
ALTERtendría todas las filas y coincidiría con el resumen, pero sin el conjunto de particiones. La lista de particiones y el número de archivos por partición son las comprobaciones que muestran que falta la disposición, así que imprímelas ambas después de copiar. - Marcas de tiempo que cambian sin error. Delta Lake redujo los valores de nanosegundos a microsegundos sin lanzar ningún error. El número de filas no cambió. Solo una comprobación de los valores detecta el problema, así que una copia con datos de menos de un microsegundo necesita esa comprobación antes de ejecutarse.
- Nombres y tipos que difieren. pyiceberg rechaza una inserción cuyos nombres de columna no coinciden con los de la tabla, o cuyo tipo no puede promover, y ese rechazo es el fallo más claro. El caso más difícil es una columna cuyo nombre coincide y cuyo tipo acepta, como un
longque antes era unint. Imprime ambos esquemas y léelos, en lugar de confiar en que la inserción tuvo éxito. - Tamaño y memoria. Los auxiliares de este capítulo leen una tabla completa en memoria antes de escribirla. Eso sirve para 1499 filas. Una tabla de miles de millones de filas necesita una copia que lea y escriba por lotes, y el resumen debe calcularse sobre los mismos lotes en ambos lados, para que siga siendo una comprobación de la tabla completa.
- Lectores que escriben en ambas tablas. Durante una copia, un trabajo que escribe en ambas tablas por error hace que difieran, y el resumen mostrará una discrepancia que ninguna escritura individual explica. Designa en el manual de operaciones un único escritor por tabla antes de empezar el corte.
- Un resumen sobre texto. Un resumen calculado sobre conversiones puede coincidir aunque los tipos difieran. La comprobación de este capítulo compara valores tipados, y el manual debe decirlo, para que una modificación posterior de la comprobación no elimine los tipos en silencio.
Decisiones que tomó este capítulo
- Las copias pasan por Arrow, y cada destino lo escribe la biblioteca propietaria de su formato. pyiceberg escribe Iceberg, la extensión
ducklakede DuckDB escribe DuckLake, y deltalake escribe Delta Lake. Este libro no usa las extensionesicebergodeltade DuckDB, así que ninguna copia en él depende de ellas. - Las tablas Delta se leen con
read_delta, por la razón que se explica en el capítulo 8. Cada lectura Delta de este capítulo pasa por esa función. - Una copia es puntual, inicia un historial nuevo y se verifica antes de que alguien cambie a ella. El origen permanece en su lugar hasta que los resúmenes coinciden y los lectores se han trasladado.
- La especificación de particiones se establece en el destino a mano, con un
ALTERantes de insertar las filas, y se imprime. La copia no la traslada. - Cada ejemplo de copia construye su propio origen a partir de las mismas tres horas del corte. Cada ejemplo se ejecuta por separado, y cada verificación lee solo las filas que su propio ejemplo escribió.
- Las verificaciones se ejecutan sobre valores tipados, después de la última escritura, sobre las mismas columnas. El número de filas y el resumen se leen juntos, y ninguno de los dos se usa por sí solo para dar una copia por buena.
- Las copias usan marcas de tiempo en microsegundos, y un ejemplo aparte verifica valores de precisión inferior al microsegundo. Cada copia de este capítulo conserva sus valores en microsegundos, de modo que los resúmenes coinciden. El ejemplo de precisión muestra qué hace cada formato con un valor que no puede conservar.
- La migración solo de metadatos no se usa aquí. La operación
Table.add_filesde pyiceberg añade archivos Parquet que ya existen a una tabla Iceberg como archivos de datos (Table.add_filesenpyiceberg/table/__init__.py, pyiceberg 0.12.0). Su documentación de la API, que no está fijada a esa versión, describe esto como la confirmación de los archivos sin reescribirlos. Eso mantiene los archivos de datos en su lugar, algo que una copia no hace. Este capítulo no lo ejecutó, y en su lugar copia filas.
Este capítulo, en esta edición
Edición 2026.11.10Ejemplos verificados el 20 de nov de 2026Superan la prueba 4 de 4 ejemplos ejemplos de este capítulo
Traducido del libro en inglés, edición 2026.11.10.