Añadir y renombrar columnas sin reescribir archivos
Unos 19 minutos de lectura, con 4 ejemplos en 8 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
Al terminar este capítulo podrás añadir una columna a una tabla que ya contiene datos, renombrar una columna en Iceberg sin reescribir sus archivos de datos y explicar por qué un cambio de nombre en Delta Lake es una reescritura de toda la tabla.
Dos peticiones llegan a wiki.pageviews_hourly una vez escritas sus tres primeras horas. La tabla contiene recuentos de visitas por hora de seis horas de visitas a páginas de Wikimedia, que el primer capítulo carga, así que cada cambio se aplica a una tabla que ya contiene datos. La primera petición pide una columna de linaje: cada fila debe registrar qué carga horaria la escribió, para que una carga defectuosa pueda rastrearse hasta sus filas. La tabla necesita esa columna, y las filas que ya contiene se escribieron antes de que la columna existiera. La segunda es una corrección de nombre. Los paneles llaman a la columna de título article_title, mientras que la tabla la llama page_title, el nombre que usa el volcado. Para cada cambio la pregunta es la misma: ¿qué ocurre con los archivos escritos antes de él?
En principio, un cambio de esquema es un cambio de metadatos. Los archivos de datos permanecen donde están, y el formato registra las columnas añadidas o renombradas en sus metadatos. Que los archivos antiguos sigan leyéndose correctamente depende de cómo el formato encuentra una columna dentro de un archivo. Un formato que localiza las columnas por nombre tiene problemas cuando un nombre cambia. Un formato que las localiza mediante algo que no cambia no los tiene. Este capítulo muestra cuál de los dos es cada formato, qué cuesta cada cambio y qué cambio no puede realizar la biblioteca de Delta Lake fijada.
Las columnas se rastrean por ID
Un archivo de datos contiene valores de algunas columnas, y el esquema de la tabla indica a qué columna pertenece cada valor. La forma sencilla de hacer coincidir ambos es por nombre. Eso funciona hasta que un nombre cambia. Entonces el esquema nombra una columna que el archivo antiguo no tiene con ese nombre, y el lector tiene que adivinar a qué pertenecen los valores antiguos.
Un lector que hace coincidir por nombre y no encuentra ninguna columna con el nombre antiguo tiene dos malas opciones: que la consulta falle o rellenar la columna con null sin avisar. La segunda es el fallo más silencioso, y un panel de control puede mostrarlo durante semanas antes de que alguien lo revise. Consideramos que el null silencioso es el fallo peor, lo cual es un juicio, no un resultado medido. Hacer coincidir por identidad evita ambos, porque la columna conserva su identidad sea cual sea su nombre.
Iceberg asigna a cada columna un ID de campo entero cuando se crea la columna, y hace coincidir las columnas por ese ID. El nombre es una etiqueta que puede cambiar, y la especificación de Iceberg dice que renombrar un campo "debe cambiar el nombre, pero no el ID del campo" [1]. Cuando un lector abre un archivo antiguo, hace coincidir cada columna por ID de campo. Si el archivo no contiene ningún valor para un campo, la regla de proyección de la especificación comprueba primero dos casos que no aplican aquí: un valor de partición de identidad y un mapeo de nombres. Después devuelve el initial-default del campo cuando hay uno definido, y null en cualquier otro caso [1]. La especificación define initial-default para una columna añadida con un valor por defecto. Este capítulo no define ninguno, así que una columna añadida se lee como null en todas las filas antiguas.
Puedes ver los ID tú mismo. El esquema de una tabla de Iceberg enumera cada campo con su ID, y el ejemplo de la sección de renombrado muestra el ID de una columna antes y después de un cambio de nombre. El ID es el valor que conviene comprobar cuando quieras saber si un renombrado conservó la identidad de la columna.
Delta Lake parte de un punto distinto. Su esquema de tabla nombra cada columna, y un lector hace coincidir por nombre. El protocolo de Delta Lake define una función opcional de mapeo de columnas que separa el nombre en los archivos del nombre que ven los lectores: cada columna recibe un nombre físico guardado en los archivos, y el nombre que usan los lectores es un nombre de visualización que puede cambiar sin tocar los archivos. El protocolo dice que el mapeo de columnas admite "el renombrado y la eliminación de columnas sin tener que reescribir todos los datos" [2]. Si una versión concreta de la biblioteca lo hace es otra cuestión. La sección sobre Delta Lake responde a esa pregunta para la versión fijada.
Regla práctica: Regla práctica: espera que una columna de Iceberg conserve sus datos tras un renombrado, porque el lector hace coincidir por ID de campo. Espera que las columnas de Delta Lake se hagan coincidir por nombre salvo que el mapeo de columnas esté activado. Prueba un renombrado en una copia de la tabla antes de depender de él, y lee después los nombres de las columnas para comprobarlos.
Añade load_batch después de tres horas
El primer cambio es el que el caso necesita primero: una columna que no existe en los archivos ya escritos. En un pipeline, eso ocurre en un día cualquiera. El pipeline empieza a sellar cada carga con su número, y la tabla ya contiene filas anteriores al sello. La configuración escribe las primeras tres horas, cada una como su propio commit, de modo que la tabla contiene tres snapshots y tres archivos de datos. Un snapshot de Iceberg es el estado de la tabla después de un commit que cambia datos. Cada append de este capítulo añade uno, y un cambio de esquema no añade ninguno.
En pyiceberg 0.12.0, añades una columna dentro de una actualización del esquema. La llamada recibe el nombre y el tipo, y la tabla asigna el ID del campo:
with table.update_schema() as update:
update.add_column("load_batch", IntegerType())
Para ver qué hace la adición con las filas que ya están en disco, haz commit de las horas 00 a 02, añade la columna y agrega con append las horas 03 a 05, cada una sellada con su número de hora en load_batch. Contar las filas por hora del día divide la tabla en el momento de la adición: las horas 00 a 02 se escribieron antes, y las horas 03 a 05 después. Cada hora es una escritura, así que la división también es la división por carga.
1"""Adds load_batch to a table that already holds three hours, in Iceberg and then in Delta Lake, and counts the nulls on each side of the add.2Read the four "with load_batch null" lines, which show the rows before the add and the rows after it in each format.3"""45import pyarrow as pa6from deltalake import DeltaTable, write_deltalake7from deltalake.schema import Field, PrimitiveType8from pyiceberg.types import IntegerType910from lib.lakehouse import ICEBERG_ID, delta_file_count, iceberg_file_count, new_warehouse, read_cut_hour, read_delta, split_nulls111213def stamp(rows, hour):14 """Return one hourly load with load_batch set to that load's hour number."""15 # int32 is the width IntegerType stores, so the Arrow column matches the Iceberg field16 return rows.append_column("load_batch", pa.array([hour] * rows.num_rows, type=pa.int32()))171819with new_warehouse() as wh:20 # the schema comes from hour 0, which has no load_batch yet21 table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)22 for hour in range(3): # hours 00 to 02, each one commit, all written before the add23 table.append(read_cut_hour(hour))24 print(f"iceberg snapshots before the add: {len(table.snapshots())}")25 print(f"iceberg data files before the add: {iceberg_file_count(table)}")26 with table.update_schema() as update:27 update.add_column("load_batch", IntegerType())28 print(f"iceberg snapshots after the add: {len(table.snapshots())}")29 print(f"iceberg data files after the add: {iceberg_file_count(table)}")30 for hour in range(3, 6): # hours 03 to 05, written after the add31 table.append(stamp(read_cut_hour(hour), hour))32 iceberg_rows = table.scan().to_arrow()33 print(f"iceberg rows in the table: {iceberg_rows.num_rows}")34 # the split is at 3, the first hour written after the add35 split_nulls(wh.con, iceberg_rows, "iceberg", "load_batch", 3, sides=("written before the add", "written after the add"))3637 path = f"{wh.root}/delta/pageviews_hourly"38 for hour in range(3): # hours 00 to 02, appended as three versions before the add39 write_deltalake(path, read_cut_hour(hour), mode="append")40 print(f"delta version before the add: {DeltaTable(path).version()}")41 print(f"delta data files before the add: {delta_file_count(DeltaTable(path))}")42 DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])43 print(f"delta version after the add: {DeltaTable(path).version()}")44 print(f"delta data files after the add: {delta_file_count(DeltaTable(path))}")45 for hour in range(3, 6): # hours 03 to 05, written after the add46 write_deltalake(path, stamp(read_cut_hour(hour), hour), mode="append")47 delta_rows = read_delta(path)48 print(f"delta rows in the table: {delta_rows.num_rows}")49 # the same split as the Iceberg half, at 350 split_nulls(wh.con, delta_rows, "delta", "load_batch", 3, sides=("written before the add", "written after the add"))
python add-column-to-existing-files.pyiceberg snapshots before the add: 3
iceberg data files before the add: 3
iceberg snapshots after the add: 3
iceberg data files after the add: 3
iceberg rows in the table: 2999
iceberg rows written before the add: 1499
iceberg rows written before the add with load_batch null: 1499
iceberg rows written after the add: 1500
iceberg rows written after the add with load_batch null: 0
delta version before the add: 2
delta data files before the add: 3
delta version after the add: 3
delta data files after the add: 3
delta rows in the table: 2999
delta rows written before the add: 1499
delta rows written before the add with load_batch null: 1499
delta rows written after the add: 1500
delta rows written after the add with load_batch null: 0
La adición cambia los metadatos y ningún archivo de datos. El número de snapshots se mantiene en 3 a lo largo del cambio de esquema, y la tabla conserva sus 3 archivos de datos.
Las 1499 filas escritas antes de la adición leen todas null para load_batch, y 0 de las 1500 filas escritas después son null. La tabla contiene 2999 filas en total.
Delta Lake, con deltalake 1.6.6, añade una columna a través de su objeto alter. La llamada recibe un campo, y la versión de la tabla sube en uno:
DeltaTable(path).alter.add_columns([Field("load_batch", PrimitiveType("integer"))])
La mitad de Delta sigue la misma secuencia: tres horas tempranas como tres appends, la adición y luego las horas 03 a 05. La primera escritura es la versión 0, y cada número de versión que este capítulo imprime es el real de Delta. La versión pasa de 2 a 3, y la tabla conserva sus 3 archivos de datos.
Antes de la adición hay 1499 filas, todas null para load_batch. Una vez incorporados los tres appends posteriores, la tabla tiene 2999 filas, y 0 de las 1500 filas escritas después de la adición son null. Esta tabla no tiene mapeo de columnas, un punto al que la sección de renombrado de Delta Lake vuelve.
Ambos formatos dan el mismo resultado en este caso. Las filas antiguas permanecen como se escribieron, y la columna se lee como null para ellas. El escritor no tuvo que tocar ni un solo archivo antiguo. Las dos mitades tienen los mismos recuentos de filas y los mismos recuentos de nulos, así que una discrepancia entre ellas apuntaría a un lector, no a los datos.
Regla práctica: Añade una columna con la llamada propia del formato, y nunca reescribiendo los archivos. Espera que las filas escritas antes de la adición se lean como null para la columna, y comprueba que así sea.
Archivos antiguos leídos como nulos
Un nulo en una columna añadida puede parecer un dato que falta, y un lector que lo ve podría suponer que los archivos antiguos están mal. No lo están. Los archivos antiguos contienen los valores que escribió la canalización, y la columna que les falta se rellena al leerlos. La regla que sigue el lector es la que describe la sección de columnas: sin initial-default, la ausencia de valor para el campo significa nulo.
Eso hace que el recuento de nulos sea una comprobación útil. Cuenta los nulos por hora, como lo hace el ejemplo de adición, y verás el patrón que debes esperar: todas las filas escritas antes de la adición son nulas, y ninguna de las escritas después lo es. Iceberg tiene 1499 nulos entre sus 1499 filas anteriores, y Delta Lake tiene 1499 entre sus 1499.
Si un recuento se sale de ese patrón, un escritor envió un conjunto de columnas distinto, o envió la columna con nulos, y la causa está en la canalización, no en el formato. Revisa el escritor de las filas que rompen el patrón antes de consultar la columna, porque una consulta sobre una columna parcialmente nula devolverá una respuesta que parece razonable.
Regla práctica: Después de una adición, cuenta los nulos en la columna añadida por hora del día, donde cada hora corresponde a una escritura. Las filas escritas antes de la adición deberían ser nulas, y las escritas después no deberían serlo. Cualquier otro patrón significa que un escritor envió un conjunto de columnas distinto, o envió nulos en la columna, así que localiza ese escritor antes de confiar en la columna.
Renombrar una columna por su ID sin reescribir archivos
Con el ID de campo ya establecido, renombrar una columna en Iceberg es una sola llamada. La llamada cambia el nombre que informa el esquema y conserva el ID:
with table.update_schema() as update:
update.rename_column("page_title", "article_title")
Para comprobar que el ID se mantiene, escribe tres horas, lee el ID de campo de page_title, renombra la columna y vuelve a leer el ID. El ejemplo también cuenta los archivos de datos en ambos momentos y consulta DuckDB con el nuevo nombre.
1"""Renames a column in an Iceberg table and reads the old files back under the new name.2Read the field ID lines, the data file lines and the non-null count, which show what the rename kept.3"""45import pyarrow as pa67from lib.lakehouse import (8 ICEBERG_ID,9 iceberg_file_count,10 new_warehouse,11 read_cut_hour,12 scan_arrow,13 snapshot_labels,14 sql_rows,15)1617with new_warehouse() as wh:18 table = wh.catalog.create_table(ICEBERG_ID, schema=read_cut_hour(0).schema)19 for hour in range(3):20 table.append(read_cut_hour(hour))2122 before = table.schema().find_field("page_title").field_id # the ID is what the reader matches on, not the name23 print(f"page_title field ID before the rename: {before}")24 print(f"data files before the rename: {iceberg_file_count(table)}")25 with table.update_schema() as update:26 update.rename_column("page_title", "article_title")27 print(f"article_title field ID after the rename: {table.schema().find_field('article_title').field_id}")28 print(f"data files after the rename: {iceberg_file_count(table)}")2930 rows = scan_arrow(table)31 print(f"rows: {rows.num_rows}")32 # count(column) leaves out nulls, so this counts the rows that have a value under the new name33 count = sql_rows(wh.con, "SELECT count(article_title) FROM t", t=rows)[0][0]34 print(f"article_title not null: {count}")3536 labels = snapshot_labels([snapshot.snapshot_id for snapshot in table.snapshots()])37 first = table.snapshots()[0].snapshot_id # the first snapshot, written before the rename38 print(f"{labels[first]} columns: {', '.join(scan_arrow(table, snapshot_id=first).column_names)}")
python rename-by-id.pypage_title field ID before the rename: 3
data files before the rename: 3
article_title field ID after the rename: 3
data files after the rename: 3
rows: 1499
article_title not null: 1499
snapshot 1 columns: hour_utc, domain_code, page_title, views, response_bytes
El renombrado conserva el ID de campo. page_title tiene el ID 3 antes de la llamada, y article_title tiene el ID 3 después.
El número de archivos de datos es 3 antes de la llamada y 3 después, así que ningún archivo se reescribió. La consulta a DuckDB cuenta 1499 valores no nulos de article_title entre 1499 filas. Se cuentan todas las filas, incluidas las escritas bajo page_title, porque el lector relaciona los archivos por ID y los lee con el nuevo nombre.
Los paneles necesitan el nombre, y la tabla no tiene que reescribirse para dárselo. Los datos se mantienen tal como se escribieron, y la siguiente lectura ve la columna renombrada. La ejecución también imprime las columnas de la primera instantánea, que son hour_utc, domain_code, page_title, views y response_bytes. Una instantánea se lee con el esquema con el que se escribió, así que una instantánea anterior sigue informando el nombre antiguo. El Capítulo 2 trata la lectura de instantáneas anteriores en general, y aquí el punto es más concreto: un renombrado no modifica el historial.
La comparación de costes es lo que hace de esta la opción correcta en Iceberg. Un renombrado que conserva el ID solo toca los metadatos, así que su coste no crece con el tamaño de la tabla. El mismo renombrado hecho copiando la tabla cuesta una lectura y una escritura de cada fila. La sección sobre Delta Lake muestra cuánto cuesta esa copia en ese formato.
Regla práctica: Renombra una columna de Iceberg cuando su nombre sea incorrecto, y comprueba el ID de campo antes y después de la llamada. El ID de campo debe ser el mismo, y el número de archivos de datos no debe cambiar. Informa a todos los lectores de la tabla sobre el renombrado, porque el esquema actual solo tiene article_title, y una instantánea anterior sigue teniendo page_title.
Delta Lake no tiene renombrado en esta versión fijada
La misma operación de renombrado en Delta Lake no tiene una llamada en esta versión fijada. El objeto de alteración de tablas de Delta Lake no tiene un método de renombrado en deltalake 1.6.6, y sus métodos aparecen listados en el paquete [3]. El que parece un renombrado es set_column_metadata, porque recibe un diccionario de metadatos del campo, y nada impide pasar una clave name. La llamada regresa sin error cuando pasas una clave name. No renombra nada en ninguna tabla, con o sin mapeo de columnas, y esa es la trampa que muestra esta sección.
La trampa crea una tabla con el mapeo de columnas activado, que es la vía del protocolo para un renombrado, y luego envía la llamada:
DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})
1"""Calls set_column_metadata with a name key on a Delta Lake table with column mapping on, then reads the names back and queries2under the new name. The columns read back line and the binder error are the lines to read.3"""45from deltalake import DeltaTable, write_deltalake67from lib.lakehouse import new_warehouse, read_cut_hour, read_delta, safe_error, sql_rows89with new_warehouse() as wh:10 path = f"{wh.root}/delta/pageviews_hourly"11 # column mapping on: the protocol's route to a rename, which this release does not offer as a call12 write_deltalake(path, read_cut_hour(0),13 configuration={"delta.columnMapping.mode": "name"})14 print(f"version before the rename: {DeltaTable(path).version()}")15 # the call raises nothing and writes a commit, so the names read back below are the only check16 DeltaTable(path).alter.set_column_metadata("page_title", {"name": "article_title"})17 print("set_column_metadata returned")18 table = DeltaTable(path)19 print(f"version after the rename: {table.version()}")20 page = next(field for field in table.schema().fields if field.name == "page_title")21 # the name key the call wrote into the field's metadata, which the reader does not use for the column name22 print(f"name in page_title metadata after the rename: {page.metadata['name']}")23 print(f"columns read back: {', '.join(read_delta(path).column_names)}")24 try:25 sql_rows(wh.con, "SELECT article_title FROM t", t=read_delta(path))26 except Exception as exc:27 print(safe_error(exc, wh))
python delta-rename-trap.pyversion before the rename: 0
set_column_metadata returned
version after the rename: 1
name in page_title metadata after the rename: article_title
columns read back: hour_utc, domain_code, page_title, views, response_bytes
BinderException: Binder Error: Referenced column "article_title" not found in FROM clause!
Candidate bindings: "page_title", "domain_code", "hour_utc", "views", "response_bytes"
LINE 1: SELECT article_title FROM t
^^^^^^^^^^^^^
La llamada regresa, y la versión de la tabla pasa de 0 a 1, así que la biblioteca escribió un commit. La clave name está en los metadatos del campo. La columna sigue llamándose page_title: los nombres leídos a través de la biblioteca son hour_utc, domain_code, page_title, views y response_bytes. La consulta de DuckDB que pide article_title falla con un BinderException, y el error enumera page_title entre las columnas que pudo enlazar.
La trampa está en que la llamada parece un renombrado y tiene éxito como si lo fuera. Nada en el valor de retorno indica que el nombre no cambió, así que solo una lectura de los nombres muestra la verdad.
El mapeo de columnas no ofrece renombrado en esta versión fijada. La tabla de la trampa tiene delta.columnMapping.mode definido como name, y aun así la llamada no cambia ningún nombre. La sección de mapeo de columnas del protocolo describe un renombrado [2], pero deltalake 1.6.6 no tiene una llamada que lo realice.
1"""Renames a Delta Lake column by overwriting the table with renamed data and schema, then reads the version before the rewrite back.2Compare the two columns lines: the version before the rewrite, and the version the rewrite makes.3"""45from deltalake import DeltaTable, write_deltalake67from lib.lakehouse import new_warehouse, read_cut_hour, read_delta89with new_warehouse() as wh:10 path = f"{wh.root}/delta/pageviews_hourly"11 for hour in range(3):12 write_deltalake(path, read_cut_hour(hour), mode="append")13 print(f"data files before the rewrite: {len(DeltaTable(path).file_uris())}")14 before = DeltaTable(path).version() # read first, so the old version can be read back after the rewrite15 print(f"version before the rewrite: {before}")16 print(f"columns before the rewrite: {', '.join(read_delta(path, version=before).column_names)}")1718 # the new names, in the table's column order: only the third one changes19 renamed = read_delta(path).rename_columns(["hour_utc", "domain_code", "article_title", "views", "response_bytes"])20 # replace the data and the schema together, in one commit, so readers of the new version see both at once21 write_deltalake(path, renamed, mode="overwrite", schema_mode="overwrite")22 print(f"data files after the rewrite: {len(DeltaTable(path).file_uris())}")23 after = DeltaTable(path).version()24 print(f"version after the rewrite: {after}")25 print(f"columns after the rewrite: {', '.join(read_delta(path).column_names)}")26 print(f"rows after the rewrite: {read_delta(path).num_rows}")
python delta-rename-by-rewrite.pydata files before the rewrite: 3
version before the rewrite: 2
columns before the rewrite: hour_utc, domain_code, page_title, views, response_bytes
data files after the rewrite: 1
version after the rewrite: 3
columns after the rewrite: hour_utc, domain_code, article_title, views, response_bytes
rows after the rewrite: 1499
La reescritura es la forma de obtener el nombre en esta versión fijada. El ejemplo de reescritura lee la tabla completa a través de la biblioteca, renombra la columna en memoria y escribe el resultado de nuevo con mode="overwrite" y schema_mode="overwrite", que reemplazan los datos y el esquema a la vez. La tabla tenía 3 archivos de datos antes de la reescritura y tiene 1 después. La reescritura crea la versión 3, que lee article_title, y en ella hay 1499 filas.
La reescritura cuesta el tamaño de la tabla, porque cada fila se lee y se escribe otra vez. La tabla aquí es pequeña, pero una tabla de producción con millones de filas paga el mismo costo por fila, así que un equipo debe planificar la reescritura como un trabajo aparte. La versión anterior a la reescritura, 2, sigue leyendo page_title, lo que también imprime el ejemplo. La reescritura, por tanto, cambia solo la versión actual, y las versiones antiguas conservan los nombres con los que se escribieron. Antes de ejecutar una, enumera los lectores que piden la columna por nombre. El cambio ocurre en un solo commit, así que todos los lectores de la versión actual se mueven en el mismo instante, mientras que un trabajo que fija una versión anterior conserva el nombre antiguo. Migra esos trabajos junto con los lectores, y registra el número de versión que la reescritura reemplazó hasta que se hayan migrado.
Regla práctica: Elige los nombres de columnas de Delta Lake al crear la tabla, porque en esta versión fijada un renombrado posterior es una reescritura de la tabla completa. No uses set_column_metadata para renombrar una columna: cambia la versión y los metadatos, y la columna conserva su nombre. Después de cualquier cambio de esquema, lee los nombres de columna a través de la biblioteca, como hace el ejemplo de la trampa, y compruébalos antes de que una consulta dependa de ellos.
Qué sale mal en producción
Los cambios de esquema fallan en silencio con más frecuencia de lo que fallan con ruido, y cada fallo que se describe a continuación tiene una señal que puedes vigilar.
Empieza por el renombrado que no hace nada. Una llamada a set_column_metadata se completa, aparece un commit en el historial y la columna conserva su nombre anterior. El fallo se ve en la primera consulta que usa article_title: la consulta de DuckDB falla con un BinderException. Un trabajo programado que ejecuta una consulta así falla en su primera ejecución tras el cambio, de modo que el error aparece cerca de su causa.
A continuación está el nombre obsoleto en el historial. Una reescritura da a la versión actual el nombre article_title, pero las versiones anteriores conservan los nombres con los que se escribieron, y el ejemplo de reescritura lo muestra: la versión 2 sigue leyendo page_title. Una instantánea de Iceberg hace lo mismo: la primera instantánea sigue informando page_title. Una consulta que lee una versión anterior o una instantánea mediante article_title no encuentra esa columna. Las lecturas por número de versión o de instantánea necesitan los nombres que estaban vigentes en ese momento, así que un trabajo que fija un número de versión también fija su esquema.
Tercero, el nulo que parece un dato ausente. Una columna añadida aparece como nula en todas las filas escritas antes de la incorporación. El recuento de nulos en esa columna es correcto, y solo es un fallo cuando se sale del patrón de antes y después que muestra el ejemplo de adición. Cuenta los nulos por hora, como hace el ejemplo de adición, e investiga cualquier fila que rompa el patrón.
Por último, el cambio de esquema que no aparece en la lista de instantáneas. La adición y el renombrado en Iceberg no modificaron el número de instantáneas, ni tampoco el número de archivos. Una herramienta que busca cambios de esquema contando instantáneas los pasará por alto. Cuando necesites saber qué cambió, compara el esquema en sí, por ID de campo y por nombre.
Regla práctica: Después de cualquier cambio de esquema, haz tres cosas antes de que se ejecute una consulta posterior: lee de nuevo los nombres de las columnas a través de la biblioteca, cuenta los nulos en cada columna añadida por hora, donde cada hora es una escritura, y compara el esquema, no el número de instantáneas, con lo que el cambio debía hacer.
Decisiones que tomó este capítulo
La tabla de esta sección pone los dos formatos uno al lado del otro para los cambios de este capítulo. Cada celda proviene de un ejemplo de este capítulo.
| Cambio | Iceberg | Delta Lake |
|---|---|---|
| Añadir una columna | Funciona. Las filas antiguas se leen como null, y el recuento de snapshots se mantiene en 3 | Funciona. Las filas antiguas se leen como null, y la versión sube en uno |
| Renombrar una columna | Funciona. El ID del campo no cambia y no se reescribe ningún archivo de datos | No hay llamada para renombrar. set_column_metadata confirma el cambio sin modificar ningún nombre; solo una reescritura da lugar al nombre |
| Leer un snapshot o una versión anterior | Muestra el nombre anterior | Muestra el nombre anterior |
- Añade una columna a una tabla que ya contiene datos, en ambos formatos. Las filas antiguas la leen como null, y el ejemplo de añadir una columna muestra los recuentos por hora que confirman el patrón. Recomendamos esta opción frente a cualquier copia de la tabla, porque no escribe ningún archivo antiguo.
- Renombra una columna de Iceberg con
rename_column, y comprueba que su ID de campo es el mismo antes y después. Lo recomendamos para cualquier columna de Iceberg cuyo nombre sea incorrecto, porque su coste no depende del tamaño de la tabla. - Elige los nombres de las columnas de Delta Lake cuando se crea la tabla. En la versión fijada, renombrar allí equivale a reescribir la tabla entera, y ese es el coste que hay que prever cuando un nombre es incorrecto.
- No renombres una columna de Delta Lake con
set_column_metadata. La llamada se completa, pero no cambia nada del nombre. - No cuentes con el mapeo de columnas para renombrar en esta versión fijada. La biblioteca no tiene ninguna llamada que lo realice, así que activar el mapeo no aporta ningún renombrado.
- Vuelve a leer los nombres de las columnas después de cada cambio de esquema, en ambos formatos, antes de que una consulta dependa de ellos.
Esta parte aún no está traducida, así que está en inglés.
Sources
- Apache Iceberg Table Spec, Schema Evolution (Column Projection), https://iceberg.apache.org/spec/, read Nov 6, 2026. Quoted: "Renaming an existing field must change the name, but not the field ID." The null rule, which the text paraphrases, is in the same section.
- Delta Transaction Log Protocol, Column Mapping section, tag v4.4.1, https://raw.githubusercontent.com/delta-io/delta/v4.4.1/PROTOCOL.md, read Nov 6, 2026. Quoted: "the renaming and dropping of columns without having to rewrite all the data."
- deltalake 1.6.6, the methods of
DeltaTable.alterin the installed package:add_columns,add_constraint,add_feature,drop_column_not_null,drop_constraint,set_column_metadata,set_table_description,set_table_nameandset_table_properties. None renames a column. To list them, rundir(DeltaTable(path).alter).
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.