Cambiar la partición sin reescribir los archivos antiguos

Unos 20 minutos de lectura, con 4 ejemplos en 7 secciones.

Edición 2026.11.10 Ejemplos verificados el 20 de nov de 2026 39 de 39 ejemplos pasan Qué ha cambiado

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

Aquí cambias la partición de una tabla en Iceberg, Delta Lake y DuckLake, y cuentas los archivos que una consulta planifica antes y después del cambio. La partición decide qué archivos abre una consulta, así que un cambio en ella cambia lo que paga cada lector. Lo que hace con los archivos ya escritos depende del formato.

wiki.pageviews_hourly, cuyos paneles leen una hora a la vez, está particionada por día, y la pregunta es cómo reagruparla por hora sin reescribir lo que ya se cargó. Las tres cargas horarias del principio ya están en disco. Así que el equipo quiere particiones por hora para cada carga posterior a la hora 02, y necesita saber qué hace el cambio con las tres cargas que existen, sin copiarlas.

El cambio tiene dos costos. El primero es el trabajo de hacerlo, que depende de si el formato deja en paz los archivos antiguos. El segundo es lo que paga cada consulta posterior, ya que una consulta que abarca el cambio planifica archivos de ambas épocas. Este capítulo mide los dos con conteos de cada biblioteca, para que la decisión se base en lo que hacen las tablas y no en una descripción del formato.

Las especificaciones de partición también tienen versiones

Último cambio en la edición 2026.11.7

Una especificación de partición indica cómo una tabla agrupa sus filas, por ejemplo, un grupo por cada día de hour_utc. En Iceberg, la especificación forma parte de los metadatos de la tabla, y el manifiesto que enumera cada archivo de datos registra la especificación con la que se escribió ese archivo. Al cambiar la especificación se crea una segunda especificación con su propio ID. Las escrituras posteriores usan la segunda especificación, y los archivos que ya están en disco conservan la especificación con la que se escribieron. La especificación de Iceberg indica que una especificación modificada se añade a la lista de especificaciones de partición de la tabla bajo un ID de especificación único, y que cada manifiesto registra el ID de la especificación usada para escribirlo (partition_spec_id).

Esto da a la tabla dos épocas de particionado coexistiendo. Una consulta lee la especificación de cada archivo que abre, de modo que un mismo escaneo puede abarcar archivos bajo varias especificaciones. El planificador hace esto por ti, así que el coste del cambio aparece en el plan y en el número de archivos, no en las filas que devuelve la consulta. Una consulta escrita para hour_utc mantiene su texto cuando cambia la especificación, que es el objetivo del diseño. Lo que cambia es el conjunto de archivos que abre el planificador. El resto de este capítulo muestra ambos aspectos.

El cambio de especificación solo afecta a los metadatos. Iceberg escribe una especificación con su propio ID y deja intactos los archivos de datos, como muestran los recuentos de archivos de la sección siguiente.

La especificación anterior también se conserva como historial. La tabla guarda un registro de cada especificación que ha tenido, de modo que un lector siempre puede saber con qué campos se escribió un archivo. Esto importa para un equipo que cambia el particionado más de una vez: cada archivo responde a la pregunta «¿cómo me dividieron?» con su propia especificación, y nadie tiene que recordar el orden de los cambios. El registro son metadatos, así que cuesta poco, pero la lista de especificaciones de la tabla crece con cada cambio.

Los otros dos formatos gestionan el particionado de forma distinta, y las diferencias determinan el coste de un cambio. Delta Lake toma sus columnas de partición por nombre, de modo que el escritor las crea como columnas. DuckLake mantiene sus claves de particionado en su catálogo. Cada uno tiene su parte en la sección sobre los otros formatos, después de los pasos de Iceberg de los que depende el resto del capítulo.

Regla práctica: Cambia una especificación de partición de Iceberg cuando cambien los filtros de tus lectores y la especificación actual planifique demasiados archivos para ellos. Si la especificación actual ya planifica pocos archivos para esos filtros, no la modifiques. Cuando sí la cambies, deja los archivos antiguos donde están. Registra el cambio, con la fecha, los campos antiguos y nuevos y los filtros de los lectores que lo motivaron, en el runbook de la tabla. Guarda junto a él los recuentos del plan antes y después del cambio, como muestra la sección sobre qué escanea una consulta.

Cambiar de particiones diarias a horarias

Último cambio en la edición 2026.11.10

Cada ejemplo vuelve a construir su tabla a partir de el corte, con las columnas originales y no con las que el capítulo 3 añadió. Para pasar la tabla a horas, sustituyes una transformación de hour_utc por otra. Iceberg particiona según una transformación de una columna: la transformación de día coloca cada fila bajo su día del calendario, y la transformación de hora coloca cada fila bajo su hora. La biblioteca pyiceberg calcula estas transformaciones con el paquete pyiceberg-core, y la transformación de día importa ese paquete al escribir. Una instalación solo con pyiceberg falla, por tanto, en el primer append bajo una partición de día u hora (código fuente de pyiceberg 0.12.0, pyiceberg/transforms.py, DayTransform.pyarrow_transform). Las versiones fijadas en este libro incluyen pyiceberg-core en 0.11.0, junto a pyiceberg en 0.12.0.

La tabla empieza con una especificación diaria. Las horas 00 a 02 se cargan bajo ella. Después cambia la especificación, y las horas 03 a 05 se cargan bajo la especificación horaria. El cambio es un bloque update_spec() que elimina el campo de día y añade el campo de hora:

with table.update_spec() as update:
    update.remove_field("ts_day")
    update.add_field("hour_utc", HourTransform(), "ts_hour")

Ambas llamadas van en un mismo bloque, de modo que la tabla recibe un único cambio de especificación con el campo de día eliminado. La lista de especificaciones, impresa en orden con la transformación de cada campo, muestra lo que hizo el cambio. Los nombres de campo son los que usa este libro, ts_day y ts_hour, así que una etiqueta de especificación indica qué transformación aplica cada campo. La columna de origen sigue siendo hour_utc. El campo de día y el campo de hora son dos transformaciones de esa columna, así que el filtro de un lector sobre la columna sigue funcionando en ambas etapas.

day-then-hour-spec.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Partition an Iceberg table by day, change its spec to hour, and load more hours under the new spec.The two `data files` lines carry the point, one count for each spec."""from collections import Counterfrom pyiceberg.partitioning import PartitionField, PartitionSpecfrom pyiceberg.transforms import DayTransform, HourTransformfrom lib.lakehouse import create_iceberg_table, new_warehouse, read_cut_hour, safe_error, scan_arrowdef main():    try:        with new_warehouse() as wh:            # source_id 1 is hour_utc, the table's first column: the day transform reads that column            day_spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name="ts_day"))            table = create_iceberg_table(wh, partition_spec=day_spec)            for hour in range(3):  # hours 00 to 02, written under the day spec                table.append(read_cut_hour(hour))            # hour_utc is the source of the hour field too, as it was of the day field            with table.update_spec() as update:                update.remove_field("ts_day")                update.add_field("hour_utc", HourTransform(), "ts_hour")            for hour in range(3, 6):  # hours 03 to 05, written under the hour spec                table.append(read_cut_hour(hour))            # the labels number the specs in the order they were made, so the output names no spec ID            specs = sorted(table.specs())            labels = {spec_id: f"spec {number}" for number, spec_id in enumerate(specs, start=1)}            for spec_id in specs:                for field in table.specs()[spec_id].fields:                    print(f"{labels[spec_id]} field {field.name}: transform {field.transform}")            # group the data files by the spec_id each one carries            files = Counter(table.inspect.data_files().column("spec_id").to_pylist())            for spec_id in specs:                print(f"{labels[spec_id]} data files: {files[spec_id]}")            print(f"rows in table: {scan_arrow(table).num_rows}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython day-then-hour-spec.py
spec 1 field ts_day: transform day
spec 2 field ts_hour: transform hour
spec 1 data files: 3
spec 2 data files: 3
rows in table: 2999

Lee la salida desde arriba. La especificación 1 tiene un campo, ts_day, con la transformación de día. La especificación 2 tiene un campo, ts_hour, con la transformación de hora. Todas las filas de la tabla siguen ahí tras el cambio: 2999 filas, que son las tres horas anteriores al cambio y las tres posteriores.

El cambio de especificación es el único paso que toca solo los metadatos. Las cargas a ambos lados escriben archivos de datos como de costumbre, y la siguiente subsección muestra a qué especificación pertenece cada archivo.

Un error aquí aparece más tarde, no en el cambio en sí. Si la lista de especificaciones es incorrecta, cada carga posterior al cambio escribe archivos con una partición equivocada, y los recuentos de la siguiente sección son el primer lugar donde lo verás. Revisar la lista de especificaciones justo después del cambio cuesta una línea de salida y evita reescribir.

Regla práctica: En Iceberg, haz el cambio de especificación en un único bloque update_spec(), de modo que el campo antiguo se elimine en el mismo cambio que añade su reemplazo. Separa las dos ediciones solo si un paso tiene que ejecutarse entre ellas; este capítulo no tiene ese paso. Revisa la lista de especificaciones tras el cambio, y comprueba que los nombres de campo y las transformaciones son los que pretendías antes de cargar datos bajo la segunda especificación.

Archivos escritos bajo cada especificación

Último cambio en la edición 2026.11.8

Cada archivo de datos pertenece a la especificación bajo la que fue escrito, así que contar los archivos por especificación te indica de qué época es cada archivo. El listado de archivos de datos lleva el ID de especificación de cada archivo, de modo que el recuento puede agrupar los archivos por especificación, con un conteo por cada especificación bajo las etiquetas "spec 1" y "spec 2". Las etiquetas numeran las especificaciones en el orden en que se crearon, por lo que la salida no nombra ningún ID de especificación.

Las tres cargas particionadas por día conservaron sus archivos durante el cambio. La salida muestra 3 archivos de datos bajo la spec 1 y 3 bajo la spec 2, así que las tres cargas particionadas por hora escribieron los suyos, y el cambio de especificación en sí no escribió nada. Si el recuento bajo la spec 1 hubiera bajado después del cambio, algo habría reescrito esos archivos, y tendrías que averiguar qué fue antes de confiar en los datos de la época anterior.

Regla práctica: Después de cualquier cambio de especificación, cuenta los archivos de datos bajo cada especificación y compara los recuentos con las cargas que hiciste. Un recuento que cambia cuando no se planeó ninguna reescritura significa que el cambio hizo más de lo que querías, así que detente y revísalo antes de la siguiente carga.

Comprueba qué analiza una consulta

Último cambio en la edición 2026.11.10

Una especificación de particiones es una forma de omitir archivos. Antes de que una consulta lea un archivo, el planificador revisa los valores de partición del archivo y sus límites por columna, y descarta los archivos que no pueden coincidir con el filtro. Tu consulta solo es tan barata como los archivos que no planifica. Por eso, la manera de comprobar un cambio es contar los archivos que planifica un filtro típico, antes y después del cambio, en lugar de comparar filas. Planificar un análisis devuelve la lista de archivos sin leer sus filas, así que el recuento es lo bastante barato como para ejecutarlo antes de cada cambio.

El descarte de archivos es donde el cambio da fruto, así que planifica tres análisis dos veces: una vez con la especificación diaria (consulta pasar a particiones por hora) y otra vez después de las tres cargas particionadas por hora. Dos filtros piden una hora cada uno: la hora 01, que se cargó antes del cambio, y la hora 04, que se cargó después. El tercero no tiene filtro y es un análisis completo.

plan-files-by-partition.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Count the files an Iceberg scan plans for one hour, for another hour and for the whole table, before and after a spec change.The filtered counts are the lines to compare, one pair for each filter."""from pyiceberg.partitioning import PartitionField, PartitionSpecfrom pyiceberg.transforms import DayTransform, HourTransformfrom lib.lakehouse import create_iceberg_table, hour_filter, new_warehouse, read_cut_hour, safe_errordef plan_counts(table):    """Return the files planned for hour 01, for hour 04 and for no filter, in that order."""    # plan_files gives the planned files as a list; each printed count is that list's length    one_hour = len(table.scan(row_filter=hour_filter(1)).plan_files())    # hour 04 is loaded only after the change, so the filter can match only an hour-partitioned file    hour_four = len(table.scan(row_filter=hour_filter(4)).plan_files())    everything = len(table.scan().plan_files())    return one_hour, hour_four, everythingdef main():    try:        with new_warehouse() as wh:            day_spec = PartitionSpec(PartitionField(source_id=1, field_id=1000, transform=DayTransform(), name="ts_day"))            table = create_iceberg_table(wh, partition_spec=day_spec)            for hour in range(3):  # hours 00 to 02, under the day spec                table.append(read_cut_hour(hour))            one_hour, hour_four, everything = plan_counts(table)            print(f"before the change, one-hour filter plans: {one_hour}")            print(f"before the change, hour 04 filter plans: {hour_four}")            print(f"before the change, no filter plans: {everything}")            with table.update_spec() as update:                update.remove_field("ts_day")                update.add_field("hour_utc", HourTransform(), "ts_hour")            for hour in range(3, 6):  # hours 03 to 05, under the hour spec                table.append(read_cut_hour(hour))            one_hour, hour_four, everything = plan_counts(table)            print(f"after the change, one-hour filter plans: {one_hour}")            print(f"after the change, hour 04 filter plans: {hour_four}")            print(f"after the change, no filter plans: {everything}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython plan-files-by-partition.py
before the change, one-hour filter plans: 1
before the change, hour 04 filter plans: 0
before the change, no filter plans: 3
after the change, one-hour filter plans: 1
after the change, hour 04 filter plans: 1
after the change, no filter plans: 6
Etapa Filtro de una hora Filtro de la hora 04 Sin filtro
Antes del cambio, tres cargas particionadas por día 1 0 3
Después del cambio, se añadieron tres cargas particionadas por hora 1 1 6

Cada filtro llega al archivo de su propia hora, en la época en que se cargó esa hora. El filtro de una hora planifica 1 archivo antes del cambio y 1 archivo después, y el filtro de la hora 04 planifica 0 archivos antes y 1 archivo después. La hora 01 se cargó antes del cambio, así que el único archivo que aparece en ambos planes es el archivo particionado por día de esa hora. Antes del cambio, los tres archivos comparten un mismo día, así que el planificador solo puede omitir los otros dos por sus límites de la columna hour_utc. Después del cambio, también se omiten los otros archivos particionados por hora. La hora 04 funciona al revés. Ningún archivo particionado por día la contiene, así que su única coincidencia es el archivo particionado por hora que guarda esa hora. Los recuentos no muestran si el planificador omitió un archivo por sus valores de partición o por sus límites de columna; solo muestran lo que el plan conservó.

Un recuento de planes es un recuento de archivos, no de bytes. Dos planes con el mismo recuento pueden leer cantidades distintas de datos, porque los archivos tienen tamaños diferentes. Aun así, el recuento es la primera comprobación correcta, porque es el número en el que decide el planificador. Cuando los recuentos coinciden y la consulta sigue lenta, revisa el tamaño de los archivos y la propia consulta.

Un análisis completo paga por cada archivo que la tabla ha escrito. Su plan crece de 3 archivos a 6: los archivos particionados por día más los particionados por hora. Ese crecimiento es el coste de mantener los archivos antiguos en su sitio, y es la razón para contar también el análisis completo, además de los filtrados.

Regla práctica: Planifica los filtros que usan tus lectores, y el análisis completo, antes y después de cada cambio de partición, y guarda los recuentos junto a la entrada del runbook. Si un filtro que planificaba un archivo empieza a planificar muchos, el cambio ha roto el descarte para ese filtro, y debes cambiar la especificación o el filtro antes de la siguiente carga con ella.

Particionamiento en los otros formatos

Último cambio en la edición 2026.11.10

En los otros dos formatos el mismo cambio tiene un costo distinto, aunque las filas leídas son las mismas en los tres. Lo que cambia son los archivos y el plan. La tabla siguiente resume los tres casos.

Formato Cómo se hace el cambio Archivos ya escritos Qué revisar después
Iceberg Un bloque update_spec() Se conservan, y siguen bajo su especificación anterior Número de archivos por especificación; conteos del plan
Delta Lake Sobrescritura completa con schema_mode="overwrite" Se vuelven a escribir en una versión posterior; la versión anterior se conserva Número de filas; número de archivos; columnas de partición de la versión anterior
DuckLake ALTER TABLE ... SET PARTITIONED BY Se conservan; la configuración se aplica a las cargas posteriores Número de archivos después de una carga; la clave de partición

Delta Lake particiona por columnas simples, y su opción de partición acepta nombres de columna, no expresiones. El protocolo de Delta Lake define partitionColumns como un arreglo con los nombres de las columnas por las que se particionan los datos. Una columna generada puede calcular day o hour dentro de la tabla, pero eleva el protocolo de escritura de la tabla, así que este libro calcula ambos en el escritor. Un auxiliar, with_partition_columns, añade las dos columnas de texto a partir de hour_utc antes de cada escritura. La tabla empieza particionada por day, y un cambio a hour se rechaza a menos que la escritura sea una sobrescritura completa que también reemplace el esquema:

DeltaError: Generic error: Specified table partitioning does not match table partitioning: expected: ["day"], got: ["hour"]. To change partition columns, use full table overwrite with schema overwrite and no replaceWhere predicate.

Prueba primero el cambio con un mode="overwrite" simple, y la biblioteca lo rechaza con ese error. La misma escritura con schema_mode="overwrite" sí se completa. Esa es la configuración que usa la API de la biblioteca en las versiones fijadas, en lugar de la marca anterior overwrite_schema. Las filas se leen en memoria antes de que empiece la sobrescritura, porque una sobrescritura reemplaza todas las filas que tiene la tabla. Volver a escribir las filas es la única forma de conservarlas.

delta-partition-overwrite.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Change a Delta Lake table's partition columns from day to hour, which rewrites the table.Read the error line from the plain overwrite first, then the version and row lines after the rewrite."""import pyarrow.compute as pcfrom deltalake import DeltaTable, write_deltalakefrom lib.lakehouse import delta_file_count, new_warehouse, read_cut_hour, read_delta, safe_errordef with_partition_columns(rows):    """Add the day and hour columns that Delta partitions by. Delta partitions only by plain columns."""    rows = rows.append_column("day", pc.strftime(rows["hour_utc"], format="%Y-%m-%d"))    # %H is the 24-hour clock, zero-padded, so hour 04 is the string "04"    return rows.append_column("hour", pc.strftime(rows["hour_utc"], format="%H"))def main():    try:        with new_warehouse() as wh:            path = f"{wh.root}/delta/pageviews_hourly"            for hour in range(3):                write_deltalake(path, with_partition_columns(read_cut_hour(hour)), partition_by=["day"], mode="append")            table = DeltaTable(path)            print(f"partition columns before: {table.metadata().partition_columns}")            print(f"version before: {table.version()}")            print(f"data files before: {delta_file_count(table)}")            # read first, so the rows are in memory before the overwrite below writes them back            rows = read_delta(path)            try:                # no schema_mode here, so the library refuses the change and the error is printed                write_deltalake(path, rows, partition_by=["hour"], mode="overwrite")            except Exception as exc:                print(f"change without schema mode: {safe_error(exc, wh)}")            # schema_mode is what lets the partition columns change in a full overwrite            write_deltalake(path, rows, partition_by=["hour"], mode="overwrite", schema_mode="overwrite")            table = DeltaTable(path)            print(f"partition columns after: {table.metadata().partition_columns}")            print(f"version after: {table.version()}")            print(f"data files after: {delta_file_count(table)}")            print(f"rows after: {read_delta(path).num_rows}")            # version 2 is the last version before the rewrite; Delta counts versions from 0            old = DeltaTable(path, version=2)            print(f"partition columns in version 2: {old.metadata().partition_columns}")            print(f"rows in version 2: {read_delta(path, version=2).num_rows}")    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython delta-partition-overwrite.py
partition columns before: ['day']
version before: 2
data files before: 3
change without schema mode: DeltaError: Generic error: Specified table partitioning does not match table partitioning: expected: ["day"], got: ["hour"]. To change partition columns, use full table overwrite with schema overwrite and no replaceWhere predicate.
partition columns after: ['hour']
version after: 3
data files after: 3
rows after: 1499
partition columns in version 2: ['day']
rows in version 2: 1499

La reescritura pasa la tabla a una nueva versión y conserva sus filas. Las tres cargas son las versiones 0 a 2, así que la tabla está en la versión 2 antes del cambio y en la 3 después de la reescritura.

La nueva versión contiene las mismas 1499 filas en 3 archivos, uno por cada partición horaria, lo que coincide con las tres horas. La versión 2 todavía se lee con read_delta, con su partición day y sus 1499 filas.

El cambio en Delta es una reescritura de los archivos actuales de la tabla, no una edición de metadatos. La tabla de aquí es pequeña. Una tabla grande necesita la misma reescritura con su propio costo, así que plánéala como una tarea de mantenimiento con una ventana de lectura. Además, cada fila se lee en memoria antes de la escritura, así que la reescritura necesita espacio para toda la tabla a la vez. Para una tabla que no cabe, una copia en una nueva ubicación es la vía más segura, y el capítulo 9 muestra cómo verificar una copia de ese tipo.

DuckLake guarda el particionamiento como una configuración de tabla en su catálogo, y un cambio se aplica solo a las cargas posteriores. La documentación de DuckLake indica que las claves de partición de una tabla solo afectan a los datos escritos después del cambio. Configura la tabla para particionar por hour(hour_utc), carga una hora más, y los conteos de archivos antes y después de esa carga muestran la regla en acción. El auxiliar adjunta el catálogo con el inlining desactivado, así que cada carga escribe un archivo de datos, y el conteo muestra lo que hizo cada carga.

ducklake-partition-alter.py Python 3.12.15 · deltalake 1.6.6 · duckdb 2.0.0 · pyarrow 26.0.1 · pyiceberg 0.12.0 Superado
"""Set a DuckLake table's partitioning to hour, then load one more hour and count the files before and after it.The files-kept line is the one to check: it counts the earlier files still listed after the hour load."""from lib.lakehouse import (DUCKLAKE_ALIAS, NAMESPACE, TABLE, connect_ducklake, create_ducklake_table, ducklake_file_count,                           ducklake_file_paths, new_warehouse, read_cut_hour, safe_error)def load(con, hour):    con.register("batch", read_cut_hour(hour))    con.execute(f"INSERT INTO {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SELECT * FROM batch")    con.unregister("batch")def main():    try:        with new_warehouse() as wh:            con = connect_ducklake(wh.con)            # the helper leaves inlining off by default, so every load below writes one data file            create_ducklake_table(con, wh.root)            for hour in range(3):  # hours 00 to 02, before the change                load(con, hour)            print(f"data files before the change: {ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE)}")            before = ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE)            con.execute(f"ALTER TABLE {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE} SET PARTITIONED BY (hour(hour_utc))")            load(con, 3)  # hour 03, the first load after the change            print(f"data files after one load under hour: {ducklake_file_count(con, DUCKLAKE_ALIAS, TABLE)}")            after = ducklake_file_paths(con, DUCKLAKE_ALIAS, TABLE)            # the intersection is the earlier files still listed after the hour load            print(f"files kept from before the change: {len(before & after)}")            # ordered by key index, so the keys print in a fixed order            for key, transform in con.execute(                "SELECT partition_key_index, transform FROM __ducklake_metadata_lake.ducklake_partition_column ORDER BY 1"            ).fetchall():                print(f"partition key {key}: transform {transform}")            rows = con.execute(f"SELECT count(*) FROM {DUCKLAKE_ALIAS}.{NAMESPACE}.{TABLE}").fetchall()            print(f"rows in table: {rows[0][0]}")  # count(*) returns one row with one value    except Exception as exc:        print(safe_error(exc))        raise SystemExit(1)if __name__ == "__main__":    main()
Salidapython ducklake-partition-alter.py
data files before the change: 3
data files after one load under hour: 4
files kept from before the change: 3
partition key 0: transform hour
rows in table: 1999

La tabla tenía 3 archivos de datos antes de la carga horaria y 4 después de ella, así que la carga horaria escribió un archivo. De los archivos listados después de esa carga, 3 ya estaban listados antes. Las tres cargas anteriores no se reescribieron, que es lo que la regla de la documentación significa en la práctica. El catálogo lista una clave de partición, con la transformación hour, y la tabla contiene 1999 filas.

Regla práctica: En Iceberg y DuckLake, un cambio de partición es un cambio de metadatos. Los archivos antiguos permanecen en su lugar y las cargas posteriores usan el particionamiento que establece el cambio, así que revisa los conteos de archivos después de la primera carga. En Delta Lake, un cambio de partición es una sobrescritura completa que reescribe los archivos actuales de la tabla, así que plánealo como una reescritura y revisa el número de filas y el número de archivos después de ella.

Qué sale mal en producción

Último cambio en la edición 2026.11.7

Un cambio de partición rara vez falla en el propio cambio; el problema aparece en las cargas y los planes posteriores.

Empieza por un paquete que falta. Con las versiones fijadas que se indican en la sección sobre el paso a particiones por hora, las transformaciones de día y de hora necesitan pyiceberg-core, y las transformaciones lo importan al escribir. Un entorno que instala solo pyiceberg puede crear la tabla y luego falla en la primera anexión de datos (append) bajo una transformación temporal. El error aparece en la primera carga programada, no cuando se cambia la especificación, y por eso la versión fijada debe ir en el archivo de requisitos y no en la memoria de quien hizo la instalación.

A continuación está la sobrepartición. Un grano de partición más fino de lo que necesitan los filtros obliga a cada consulta a abrir más archivos, y cada archivo contiene menos filas. Las cargas por hora, de unos pocos cientos de filas cada una, producen archivos pequeños en términos absolutos. Esto es una regla práctica, no una medición: el costo depende de tu almacenamiento y de tu motor. El recuento de planes de la sección sobre qué analiza una consulta muestra cuántos archivos abre una consulta con cada especificación. La señal es un recuento de análisis completos que sigue creciendo con cada carga mientras las filas por archivo siguen siendo pocas, y la solución es la compactación, que cubre el capítulo 6, o un grano más grueso para las cargas posteriores.

La tercera es una clave de alta cardinalidad. Una partición de identidad sobre page_title crea una partición por título, y cada carga escribe un archivo por cada título que contiene. La tabla de aquí tiene unos pocos miles de filas, pero una tabla real de páginas tiene muchos más títulos que eso, y el número de archivos seguiría a los títulos, no al tiempo. Particiona por tiempo, que es lo que usan los filtros, y deja los títulos como una columna por la que las consultas filtran.

Después está juzgar el cambio por su resultado. Las filas son las mismas antes y después de un cambio de partición, así que una comprobación que compara las filas pasa tanto si el cambio sirvió de algo como si no. Los ejemplos de este capítulo imprimen las filas solo para confirmar que no se perdió nada. Son los recuentos los que muestran el cambio.

Por último, una reescritura que se ejecuta sobre una tabla que usan los lectores. El ejemplo de Delta de este capítulo se ejecuta por separado y no prueba a los lectores durante la escritura. Para una tabla de la que dependen los lectores, recomendamos escribir la reescritura en una copia, comprobar los recuentos y las filas de la copia y luego apuntar a los lectores hacia ella. El capítulo 9 usa esta misma comprobación entre formatos. Recomendamos esto por criterio; ningún ejemplo lo mide.

Regla práctica: Elige el grano de partición a partir de los filtros que usan tus lectores y del tamaño de los archivos que esperas, no de la frecuencia con que llegan los datos. Antes de ejecutar un cambio de partición en una tabla que atiende a lectores, ejecútalo en una copia y compara los recuentos de planes y el número de filas en ambos lados.

Decisiones que tomó este capítulo

Último cambio en la edición 2026.11.8
  • Particionamos la tabla de Iceberg por las transformaciones de día y hora de hour_utc, y fijamos pyiceberg-core junto a pyiceberg. Las transformaciones mantienen la columna de tiempo como fuente de la partición, de modo que un filtro por tiempo lee el mismo campo que usó el escritor. Recomendamos esto para cualquier tabla que se filtre por tiempo.
  • Cambiamos la tabla de Delta Lake mediante una sobrescritura completa con schema_mode="overwrite", y escribimos sus columnas de partición como columnas de texto simples, day y hour, calculadas por el escritor. Aceptamos la reescritura, porque en esta biblioteca un cambio de partición requiere una sobrescritura completa.
  • Contamos archivos y planes a través del listado propio de cada biblioteca: plan_files() para Iceberg, file_uris() para Delta Lake y ducklake_list_files para DuckLake. Ningún ejemplo imprime un nombre de archivo, porque los nombres contienen un ID aleatorio que cambia en cada ejecución.
  • Desactivamos la inserción en línea de DuckLake en todos los ejemplos que cuentan archivos, como explica el capítulo 1, para que un recuento de archivos sea un recuento de archivos de datos.
  • Elegimos la granularidad por hora a partir de los filtros de los paneles, que leen una hora a la vez, y no a partir de la frecuencia con que llegan las cargas.
  • Mostramos primero el fallo de Delta y después la solución, de modo que la opción de esquema se explique por el error que la exige.
  • Imprimimos la clave de partición de DuckLake desde la tabla de particiones del catálogo, no desde los nombres de archivo, de modo que la salida no cambie cuando cambian los nombres de archivo.
  • Mantenemos las etiquetas de campo y de especificación en la salida y nunca imprimimos un ID de especificación, un ID de instantánea ni un nombre de archivo. Los IDs de instantánea y los nombres de archivo varían de una ejecución a otra, y una etiqueta indica a qué época pertenece una especificación sin que el lector tenga que descifrar su ID.

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.

Cita esta sección

Formato

Cada formato cita el libro en inglés, que esta traducción sigue.

Cada formato nombra esta edición. Su enlace abre la edición actual, donde el encabezado de cada sección indica cuándo cambió su texto por última vez. Las fechas de acceso y de recuperación son el día en que lo abres.

En esta página

Capítulo 4 de 10: Cambiar la partición sin reescribir los archivos antiguos

  1. Las especificaciones de partición también tienen versiones
  2. Cambiar de particiones diarias a horarias
  3. Archivos escritos bajo cada especificación
  4. Comprueba qué analiza una consulta
  5. Particionamiento en los otros formatos
  6. Qué sale mal en producción
  7. Decisiones que tomó este capítulo

Volver arribaTodos los capítulos