24  Lakehouse con Apache Iceberg: tablas con transacciones sobre el data lake

big-data
ingenieria-datos
iceberg
lakehouse
spark
Autor/a

Wilder Ramírez Delgado

Fecha de publicación

8 de noviembre de 2026

El problema que vas a resolver

El pipeline de ingesta de BITLogística (empresa ficticia; los datos son sintéticos y no corresponden a BIT ni a ningún cliente) funciona, pero el capítulo de ingesta terminó con una lista de cosas que los archivos Parquet simples no resuelven. Para corregir unas pocas filas hay que reescribir fechas completas. Si una escritura falla a la mitad, la tabla puede quedar con una parte nueva y otra vieja. No hay forma de ver la tabla como estaba ayer, ni de deshacer un DELETE equivocado. Agregar una columna obliga a que todos los lectores sepan pedir mergeSchema.

Este capítulo resuelve esa lista con Apache Iceberg, un formato de tabla abierto que funciona sobre los mismos archivos Parquet y el mismo HDFS, sin servidores nuevos. Con los envíos de BITLogística, la tabla recibe junio y 300 correcciones de mayo en una sola operación, se consulta como estaba antes, sobrevive a un lote dañado, recupera un borrado por error y cambia de esquema y de partición sin reescribir el pasado.

Ficha En este capítulo
Pregunta ¿Cómo se consigue sobre un data lake lo que da una base de datos: actualizar filas, transacciones, historial y cambios de esquema seguros?
Datos La plata del taller de PySpark: 26 566 envíos de enero a mayo para crear la tabla, y junio más 300 correcciones como lote nuevo
Tiempo estimado de lectura 60 minutos, más la práctica
Nivel Intermedio
Conocimientos previos recomendados Particiones y archivos pequeños en Almacenamiento analítico; el catálogo en Spark SQL y DataFrames; los límites de la sección 10 de Ingesta y cargas incrementales
Tecnologías mencionadas Apache Iceberg 1.6.1, Spark 3.5.3, HDFS, Parquet; como alternativas: Delta Lake y Apache Hudi

Objetivos de aprendizaje

Al terminar este capítulo podrás:

  1. Explicar la diferencia entre un formato de archivo y un formato de tabla, y qué es un lakehouse.
  2. Crear una tabla Iceberg con partición oculta y reconocer sus archivos de metadatos y de datos en HDFS.
  3. Actualizar e insertar filas en una sola operación con MERGE INTO, y leer lo que hizo en el historial de instantáneas.
  4. Consultar una tabla como estaba en una instantánea anterior.
  5. Comprobar que una escritura que falla no deja la tabla a medias, y deshacer una operación equivocada.
  6. Agregar una columna y cambiar la partición de una tabla sin reescribir los datos existentes.
  7. Compactar archivos pequeños y expirar instantáneas, y explicar lo que se pierde al hacerlo.
TipLo que necesitas recordar
Concepto En una línea Dónde se explica
Parquet y particiones por carpeta Archivos por columnas, organizados en carpetas columna=valor. Almacenamiento analítico, secciones 3 y 8
Archivos pequeños y compactación Muchos archivos chicos cuestan más que pocos grandes; compactar los junta. Almacenamiento analítico, sección 9
Catálogo y tablas externas Registro de tablas por nombre sobre archivos del data lake. Spark SQL y DataFrames, sección 10
Idempotencia Repetir una carga deja el mismo resultado. Ingesta, sección 2

Antes de empezar

El capítulo es un notebook que se ejecuta en el Jupyter de spark-client, con el kernel Python del clúster. En el apéndice «Operar el clúster» están el arranque y la descarga: el archivo se llama taller_iceberg.ipynb dentro de talleres-notebooks.zip. Necesita la capa /bitlogistica/plata del taller de PySpark.

Iceberg no viene incluido en Spark: es una librería de unos 40 MB que se descarga una vez. El capítulo usa la versión 1.6.1, la última que funciona con Java 8: el cliente de Spark corre con Java 11, pero los executors corren en los NodeManagers, que usan Java 8, y las versiones 1.7 en adelante exigen Java 11. Desde la terminal de Ubuntu, en tu equipo:

mkdir -p ~/hdfs-docker-lab/notebooks/jars && curl -L -o ~/hdfs-docker-lab/notebooks/jars/iceberg-spark-runtime-3.5_2.12-1.6.1.jar   https://repo1.maven.org/maven2/org/apache/iceberg/iceberg-spark-runtime-3.5_2.12/1.6.1/iceberg-spark-runtime-3.5_2.12-1.6.1.jar && ls -l ~/hdfs-docker-lab/notebooks/jars/

Salida esperada: un archivo iceberg-spark-runtime-3.5_2.12-1.6.1.jar de unos 40 MB. La carpeta notebooks es la que spark-client ve como /opt/spark/work-dir, así que el notebook encuentra el archivo en jars/. El nombre dice para qué versiones sirve: Spark 3.5, Scala 2.12 e Iceberg 1.6.1.

La tabla vive en /bitlogistica/lakehouse y ocupa menos de 2 MB. Se conserva al final para los capítulos siguientes; la primera celda la borra si existe, para que el notebook empiece siempre desde cero.

1. Formato de archivo, formato de tabla y lakehouse

NotaFormato de tabla

Un formato de archivo, como Parquet, dice cómo se guardan las filas dentro de un archivo. Un formato de tabla, como Apache Iceberg, dice qué archivos forman la tabla en cada momento. Lo hace con un registro aparte, los metadatos: la lista de archivos de datos, el esquema, la forma de particionar y el historial de cambios. Una carpeta con archivos Parquet es una tabla solo por convención; con Iceberg, la tabla es lo que dicen sus metadatos, aunque en la carpeta haya otros archivos.

NotaInstantánea

Una instantánea (snapshot) es el estado completo de la tabla después de una escritura: la lista exacta de archivos de datos que la forman en ese momento. Cada escritura crea una instantánea nueva y no modifica las anteriores. La tabla «actual» es la instantánea a la que apunta el catálogo.

NotaLakehouse

Un lakehouse es un data lake que, gracias a un formato de tabla, ofrece lo que antes solo daba una bodega de datos: transacciones, actualizaciones de filas, esquema controlado e historial. Los datos siguen siendo archivos abiertos en almacenamiento barato (HDFS o un almacenamiento de objetos) y cualquier motor que entienda el formato puede leerlos: Spark, Trino, Flink o pandas.

Cinco columnas de izquierda a derecha. Catálogo: lago.bitlogistica.envios, versión actual v3, resaltada. Metadatos de la tabla: v3.metadata.json resaltado con esquema, particiones e instantáneas, y debajo v2 y v1. Lista de manifiestos: snap 3, resaltada, y snap 2. Manifiestos: A y B. Archivos de datos: Parquet de los meses 2026-01, 2026-05 nuevo y 2026-06. Flechas unen cada nivel con el siguiente. Abajo: una escritura agrega archivos nuevos y una versión nueva de los metadatos, y al final cambia de una sola vez el puntero del catálogo; quien lee sigue siempre una versión completa.

Cómo encuentra Iceberg los archivos de una tabla.

La figura muestra el camino de una lectura: el catálogo apunta al archivo de metadatos vigente; ese archivo nombra la instantánea actual; la instantánea tiene una lista de manifiestos, y cada manifiesto lista archivos de datos con estadísticas por columna (mínimos, máximos, nulos). Una escritura nunca toca archivos existentes: escribe archivos nuevos y una versión nueva de los metadatos, y al final cambia el puntero. Ese último paso es atómico. De ahí salen las transacciones y el viaje en el tiempo de este capítulo.

Iceberg no es el único formato de tabla. Delta Lake y Apache Hudi resuelven lo mismo con diseños parecidos. El libro usa Iceberg porque es independiente de un proveedor, funciona con Spark 3.5 con un solo .jar y no necesita servicios nuevos en el clúster.

2. La sesión con un catálogo Iceberg

La sesión agrega cuatro opciones a las de siempre:

  • spark.jars apunta al .jar de Iceberg. El driver lo carga y YARN lo copia a los executors.
  • spark.sql.extensions agrega a Spark SQL las instrucciones de Iceberg: MERGE INTO, CALL para los procedimientos de mantenimiento y los ALTER TABLE de particiones.
  • spark.sql.catalog.lago crea un catálogo llamado lago, con tipo hadoop: guarda el registro de tablas como archivos en HDFS, bajo la carpeta warehouse, sin metastore ni servicio aparte. En producción se usan catálogos con servidor (Hive Metastore, un catálogo REST o el de la nube) para que varios motores compartan las tablas; el tipo hadoop basta para un solo clúster.

Las tablas de este catálogo se nombran con tres partes: lago.bitlogistica.envios es la tabla envios del espacio de nombres bitlogistica del catálogo lago.

# 1. Librerías del notebook
import datetime
import os
import platform

import matplotlib
import matplotlib.pyplot as plt
import pandas as pd
from pyspark.sql import SparkSession
from pyspark.sql import functions as F

# 2. Rutas: la plata del taller de PySpark y la bodega de tablas Iceberg
BASE = "hdfs://namenode:9000/bitlogistica"
PLATA = BASE + "/plata"
LAGO = BASE + "/lakehouse"            # aquí vivirán los datos y metadatos de las tablas Iceberg

# 3. El .jar de Iceberg: se descargó una vez en notebooks/jars (ver «Antes de empezar»)
JAR = os.path.abspath("jars/iceberg-spark-runtime-3.5_2.12-1.6.1.jar")
assert os.path.isfile(JAR), "Falta el .jar de Iceberg en notebooks/jars: revisa «Antes de empezar»"

# 4. La sesión: cuatro opciones agregan Iceberg a Spark
spark = (
    SparkSession.builder
    .appName("lakehouse-iceberg")
    .config("spark.ui.showConsoleProgress", "false")
    .config("spark.jars", JAR)                                    # el driver lo carga y YARN lo reparte
    .config("spark.sql.extensions",                               # habilita MERGE, CALL y ALTER de Iceberg
            "org.apache.iceberg.spark.extensions.IcebergSparkSessionExtensions")
    .config("spark.sql.catalog.lago", "org.apache.iceberg.spark.SparkCatalog")   # un catálogo llamado «lago»
    .config("spark.sql.catalog.lago.type", "hadoop")              # que guarda su registro en archivos de HDFS
    .config("spark.sql.catalog.lago.warehouse", LAGO)             # bajo esta carpeta
    .getOrCreate()
)
spark.sparkContext.setLogLevel("ERROR")
sc = spark.sparkContext
assert sc.master == "yarn", "La sesión no está en YARN: revisa el kernel (Python del clúster)"

# 5. Borrar la bodega de una ejecución anterior, para empezar siempre desde cero
Path = spark._jvm.org.apache.hadoop.fs.Path
CONF = sc._jsc.hadoopConfiguration()
carpeta = Path(LAGO)
print("Bodega de una ejecución anterior borrada:", carpeta.getFileSystem(CONF).delete(carpeta, True))

print("Python", platform.python_version(), "| Spark", spark.version, "| master:", sc.master)
print("Catálogo lago:", spark.conf.get("spark.sql.catalog.lago.type"), "en", spark.conf.get("spark.sql.catalog.lago.warehouse"))
26/11/08 05:01:49 WARN NativeCodeLoader: Unable to load native-hadoop library for your platform... using builtin-java classes where applicable
Setting default log level to "WARN".
To adjust logging level use sc.setLogLevel(newLevel). For SparkR, use setLogLevel(newLevel).
26/11/08 05:01:50 WARN Client: Neither spark.yarn.jars nor spark.yarn.archive is set, falling back to uploading libraries under SPARK_HOME.
Bodega de una ejecución anterior borrada: True
Python 3.11.10 | Spark 3.5.3 | master: yarn
Catálogo lago: hadoop en hdfs://namenode:9000/bitlogistica/lakehouse

La sesión quedó en YARN con el catálogo lago de tipo hadoop sobre /bitlogistica/lakehouse. La primera línea dice True si había una bodega de una ejecución anterior y la borró.

3. Crear la tabla con partición oculta

NotaPartición oculta

En el capítulo de almacenamiento, particionar por mes obligó a crear una columna mes y a filtrar por ella: quien consultaba con admision no aprovechaba la partición. Iceberg particiona con una transformación de una columna existente, como months(admision) o days(admision), y la guarda en los metadatos. Quien consulta filtra por admision, como pensaría cualquiera, e Iceberg traduce el filtro a particiones. Por eso se llama partición oculta: el lector no necesita conocerla.

La celda crea lago.bitlogistica.envios con los envíos de enero a mayo, particionada por el mes de admision. La columna mes de la plata se deja fuera, porque Iceberg la deriva. writeTo(...).create() es la forma de crear una tabla con la API de DataFrames; el equivalente en SQL es CREATE TABLE … USING iceberg PARTITIONED BY (months(admision)).

# 1. Un espacio de nombres (como una base de datos) dentro del catálogo
spark.sql("CREATE NAMESPACE IF NOT EXISTS lago.bitlogistica")
TABLA = "lago.bitlogistica.envios"

# 2. La plata de enero a mayo; «mes» sobra porque Iceberg la deriva de «admision»
plata = spark.read.parquet(PLATA)
enero_mayo = plata.filter(F.col("mes") <= 5).drop("mes")

# 3. Crear la tabla particionada por el MES de la fecha de admisión (partición oculta)
enero_mayo.writeTo(TABLA).partitionedBy(F.months("admision")).create()

# 4. Lo que quedó: filas y una fila por partición, desde las tablas de metadatos de Iceberg
print("Filas en la tabla:", spark.table(TABLA).count())
spark.sql(f"SELECT partition, record_count, file_count FROM {TABLA}.partitions ORDER BY partition").show()
Filas en la tabla: 26566
+---------+------------+----------+
|partition|record_count|file_count|
+---------+------------+----------+
|    {672}|        4941|         1|
|    {673}|        4721|         1|
|    {674}|        5285|         1|
|    {675}|        5100|         1|
|    {676}|        6519|         1|
+---------+------------+----------+

La tabla tiene 26 566 envíos en cinco particiones, una por mes, con un archivo de datos cada una. La partición aparece como un número: {672} es enero de 2026, porque months cuenta los meses desde enero de 1970. Mayo, {676}, es la más grande, con 6 519 envíos, la temporada alta del taller de PySpark.

La celda siguiente recorre la carpeta de la tabla en HDFS para ver qué escribió Iceberg.

# 1. Recorrer la carpeta de la tabla en HDFS y clasificar cada archivo
raiz = Path(LAGO + "/bitlogistica/envios")
iterador = raiz.getFileSystem(CONF).listFiles(raiz, True)
archivos = []
while iterador.hasNext():
    estado = iterador.next()
    ruta = estado.getPath().toString().split("/bitlogistica/envios/")[1]
    archivos.append((ruta.split("/")[0], ruta, estado.getLen()))

# 2. Resumen: cuántos archivos y bytes hay en metadata/ y en data/
tabla_archivos = pd.DataFrame(archivos, columns=["zona", "ruta", "bytes"])
print(tabla_archivos.groupby("zona").agg(archivos=("ruta", "count"), bytes=("bytes", "sum")).to_string())
print()

# 3. Los archivos de metadatos, uno por uno, y un archivo de datos de ejemplo
for ruta in sorted(tabla_archivos.loc[tabla_archivos["zona"] == "metadata", "ruta"]):
    print(ruta)
print(sorted(tabla_archivos.loc[tabla_archivos["zona"] == "data", "ruta"])[0])
          archivos   bytes
zona                      
data             5  640159
metadata         4   18499

metadata/74fb51da-f99e-4d3d-8baa-cf43881e4a7a-m0.avro
metadata/snap-2512792261418552131-1-74fb51da-f99e-4d3d-8baa-cf43881e4a7a.avro
metadata/v1.metadata.json
metadata/version-hint.text
data/admision_month=2026-01/00001-4-3ace7777-b46c-4259-b803-4dff037df7eb-0-00003.parquet

Hay 5 archivos de datos, unos 640 KB, y 4 archivos de metadatos, unos 18 KB: los metadatos ocupan el 3 % de la tabla. Cada archivo de metadatos es una pieza de la figura de la sección 1:

  • v1.metadata.json es la primera versión de los metadatos de la tabla, y version-hint.text le dice al catálogo hadoop cuál es la versión vigente.
  • snap-….avro es la lista de manifiestos de la primera instantánea.
  • …-m0.avro es el manifiesto con la lista de los 5 archivos de datos y sus estadísticas.

Los datos quedan en carpetas por partición, data/admision_month=2026-01/, igual que con partitionBy. La diferencia es que Spark no lee la carpeta para saber qué archivos hay: lo lee en los metadatos.

4. MERGE: insertar y actualizar en una sola operación

Llega el lote de junio, y con él una noticia: el sistema de admisión registró mal la hora de entrega de 300 envíos de mayo, que en realidad se entregaron 12 horas más tarde. Las 300 cifras son una muestra de los envíos entregados en mayo, elegida con semilla fija para que la ejecución sea reproducible; las 12 horas bastan para que algunos pasen de «a tiempo» a «tarde».

NotaMERGE INTO

MERGE INTO destino USING origen ON condición compara cada fila del origen con el destino. WHEN MATCHED THEN UPDATE dice qué hacer con las que ya existen; WHEN NOT MATCHED THEN INSERT, con las nuevas. Se conoce también como upsert (actualizar o insertar). La operación es una sola transacción: termina completa o no cambia nada.

La celda arma el lote del día: los envíos de junio, que son nuevos, más las 300 correcciones, que ya están en la tabla.

# 1. Las 300 correcciones: envíos de mayo cuya entrega se registró 12 horas antes de lo real
correcciones = (
    plata.filter((F.col("mes") == 5) & (F.col("estado") == "entregado"))
    .sample(fraction=0.06, seed=24).limit(300)
    .withColumn("entrega", F.col("entrega") + F.expr("INTERVAL 12 HOURS"))
    .withColumn("horas_transito", F.round(F.col("horas_transito") + 12, 1))
    .withColumn("a_tiempo", F.col("horas_transito") <= F.col("promesa_horas"))
)

# 2. El lote del día: todos los envíos de junio (nuevos) más las correcciones (ya existen)
lote = plata.filter(F.col("mes") == 6).unionByName(correcciones).drop("mes")
lote.createOrReplaceTempView("lote")

# 3. Cuántas guías del lote ya están en la tabla y cuántas son nuevas
existentes = lote.join(spark.table(TABLA).select("guia"), "guia", "left_semi").count()
print(f"Filas del lote: {lote.count()} | ya están en la tabla: {existentes} | nuevas: {lote.count() - existentes}")
print("Correcciones que pasan de a tiempo a tarde:",
      correcciones.join(plata.select("guia", F.col("a_tiempo").alias("antes")), "guia")
      .filter(F.col("antes") & ~F.col("a_tiempo")).count())
Filas del lote: 5798 | ya están en la tabla: 300 | nuevas: 5498
Correcciones que pasan de a tiempo a tarde: 52

El lote tiene 5 798 filas: 300 guías que ya están en la tabla y 5 498 nuevas, los envíos de junio. De las 300 correcciones, 52 pasan de «a tiempo» a «tarde» con las 12 horas reales.

La celda siguiente guarda la instantánea inicial y ejecuta el MERGE. La condición ON t.guia = s.guia usa la guía como llave, porque identifica a cada envío. La cláusula WHEN MATCHED AND (t.entrega <> s.entrega OR t.estado <> s.estado) solo actualiza las filas que cambiaron de verdad, para que repetir el lote no cuente como cambio.

# 1. Guardar el estado antes del MERGE para compararlo después
filas_antes = spark.table(TABLA).count()
INSTANTANEA_INICIAL = spark.sql(f"SELECT snapshot_id FROM {TABLA}.snapshots").first()[0]

# 2. Una sola instrucción: actualiza las guías que existen y agrega las nuevas
MERGE = f"""
MERGE INTO {TABLA} AS t
USING lote AS s
ON t.guia = s.guia
WHEN MATCHED AND (t.entrega <> s.entrega OR t.estado <> s.estado) THEN UPDATE SET *
WHEN NOT MATCHED THEN INSERT *
"""
spark.sql(MERGE)

# 3. Resultado
print(f"Filas antes: {filas_antes} | después: {spark.table(TABLA).count()}")
print("Instantánea inicial:", INSTANTANEA_INICIAL)
Filas antes: 26566 | después: 32064
Instantánea inicial: 2512792261418552131

La tabla pasó de 26 566 a 32 064 filas: entraron los 5 498 envíos de junio y las 300 correcciones reemplazaron a sus versiones de mayo sin agregar filas. En el capítulo de ingesta, lo mismo exigía recalcular las fechas afectadas a partir de todo el bronce; aquí es una instrucción.

El historial de instantáneas dice qué hizo cada operación.

RESUMEN = f"""
SELECT snapshot_id,
       operation                              AS operacion,
       summary['added-records']               AS filas_agregadas,
       summary['deleted-records']             AS filas_quitadas,
       summary['added-data-files']            AS archivos_agregados,
       summary['deleted-data-files']          AS archivos_quitados,
       summary['changed-partition-count']     AS particiones_tocadas
FROM {TABLA}.snapshots ORDER BY committed_at
"""
spark.sql(RESUMEN).show(truncate=False)
+-------------------+---------+---------------+--------------+------------------+-----------------+-------------------+
|snapshot_id        |operacion|filas_agregadas|filas_quitadas|archivos_agregados|archivos_quitados|particiones_tocadas|
+-------------------+---------+---------------+--------------+------------------+-----------------+-------------------+
|2512792261418552131|append   |26566          |NULL          |5                 |NULL             |5                  |
|5083678134533792060|overwrite|12017          |6519          |2                 |1                |2                  |
+-------------------+---------+---------------+--------------+------------------+-----------------+-------------------+

Hay dos instantáneas. La primera es la creación, un append de 26 566 filas en 5 archivos. La segunda, el MERGE, es un overwrite que agregó 12 017 filas y quitó 6 519, en 2 archivos agregados y 1 quitado, tocando 2 particiones. Las cuentas cuadran: el archivo de mayo, con sus 6 519 filas, se reemplazó por uno nuevo con las mismas 6 519 filas, 300 de ellas corregidas; y junio agregó un archivo de 5 498 filas. 6 519 + 5 498 = 12 017.

NotaCopiar al escribir

Iceberg no modifica archivos Parquet: cuando una fila cambia, reescribe el archivo completo que la contiene. Esta estrategia se llama copiar al escribir (copy-on-write) y es la que usa por defecto MERGE en Spark. Es rápida para leer y lenta para escribir cambios pequeños sobre archivos grandes. La alternativa, fusionar al leer (merge-on-read), escribe solo archivos pequeños que marcan las filas borradas, y deja la combinación para la lectura; se activa con la propiedad de tabla write.merge.mode.

¿Qué pasa si el mismo lote llega dos veces, como en el capítulo de ingesta?

# 1. El mismo lote, otra vez: ¿se duplica algo?
spark.sql(MERGE)
print("Filas después de repetir el MERGE:", spark.table(TABLA).count())
print("Guías distintas:", spark.table(TABLA).select("guia").distinct().count())
spark.sql(RESUMEN).show(truncate=False)
Filas después de repetir el MERGE: 32064
Guías distintas: 32064
+-------------------+---------+---------------+--------------+------------------+-----------------+-------------------+
|snapshot_id        |operacion|filas_agregadas|filas_quitadas|archivos_agregados|archivos_quitados|particiones_tocadas|
+-------------------+---------+---------------+--------------+------------------+-----------------+-------------------+
|2512792261418552131|append   |26566          |NULL          |5                 |NULL             |5                  |
|5083678134533792060|overwrite|12017          |6519          |2                 |1                |2                  |
|7185803558959816085|overwrite|12017          |12017         |2                 |2                |2                  |
+-------------------+---------+---------------+--------------+------------------+-----------------+-------------------+

La tabla sigue con 32 064 filas y 32 064 guías distintas: el MERGE repetido no duplicó nada, porque las guías de junio ya existen y la condición de actualización no encontró cambios. Pero el historial muestra un costo: una tercera instantánea que agregó y quitó 12 017 filas, reescribiendo los archivos de mayo y junio con los mismos datos. Con copiar al escribir, basta con que una fila del archivo coincida con el origen para reescribirlo, aunque la condición WHEN MATCHED no la cambie. En un pipeline real conviene dejar en el lote solo las filas que de verdad cambiaron, con una unión anti contra la tabla, antes del MERGE; es uno de los ejercicios de la Práctica.

5. Viaje en el tiempo

Como las instantáneas viejas no se borran, la tabla se puede consultar como estaba en cualquiera de ellas. La celda calcula el cumplimiento de mayo con la tabla actual y con la instantánea inicial, antes de las correcciones. VERSION AS OF recibe el número de una instantánea; TIMESTAMP AS OF recibe una fecha y hora, y usa la instantánea vigente en ese momento.

CUMPLIMIENTO_MAYO = """
SELECT COUNT(*) AS envios_mayo,
       ROUND(100 * AVG(CAST(a_tiempo AS INT)), 2) AS pct_a_tiempo
FROM {origen}
WHERE admision >= '2026-05-01' AND admision < '2026-06-01'
"""
# 1. La tabla como está ahora
spark.sql(CUMPLIMIENTO_MAYO.format(origen=TABLA)).show()

# 2. La misma tabla como estaba en la instantánea inicial, antes de las correcciones
spark.sql(CUMPLIMIENTO_MAYO.format(origen=f"{TABLA} VERSION AS OF {INSTANTANEA_INICIAL}")).show()

# 3. También se puede viajar con DataFrames, por instantánea
antes = spark.read.option("snapshot-id", INSTANTANEA_INICIAL).table(TABLA)
print("Filas en la instantánea inicial:", antes.count(), "| filas hoy:", spark.table(TABLA).count())
+-----------+------------+
|envios_mayo|pct_a_tiempo|
+-----------+------------+
|       6519|       84.36|
+-----------+------------+

+-----------+------------+
|envios_mayo|pct_a_tiempo|
+-----------+------------+
|       6519|       85.16|
+-----------+------------+

Filas en la instantánea inicial: 26566 | filas hoy: 32064

Mayo tiene 6 519 envíos en las dos versiones, pero su cumplimiento bajó de 85.16 % a 84.36 % con las correcciones: 0.80 puntos, los 52 envíos que pasaron a «tarde» de 6 519. Si un informe de la semana pasada mostró 85.16 %, el viaje en el tiempo permite reproducirlo exactamente y explicar la diferencia con el de hoy. La instantánea inicial tiene 26 566 filas y la actual 32 064: con la API de DataFrames, la opción snapshot-id da el mismo viaje.

6. Transacciones: una escritura que falla no deja rastro

NotaTransacción atómica

Una operación es atómica si se aplica completa o no se aplica: no existe un estado intermedio visible. En Iceberg, una escritura escribe primero todos sus archivos y al final cambia el puntero a la nueva instantánea. Si falla antes de ese último paso, el puntero no se mueve y la tabla queda exactamente como estaba; los archivos que alcanzó a escribir quedan huérfanos, fuera de cualquier instantánea, hasta que el mantenimiento los borra.

La celda prepara un lote dañado: sube 1 kg el peso de todo junio, pero una fila provoca un error a mitad del trabajo con raise_error, como haría un dato que no se puede convertir. Antes y después del intento compara la instantánea actual y la suma de pesos de toda la tabla. Los mensajes de error de los executors se silencian durante el intento, para que el notebook quede legible; el error llega igual al driver.

# 1. Un lote dañado: aumenta 1 kg el peso de todo junio, pero una fila provoca un error a mitad del trabajo
guia_mala = lote.orderBy("guia").first()["guia"]
lote_malo = lote.withColumn(
    "peso_kg",
    F.when(F.col("guia") == guia_mala, F.raise_error(F.lit("fila inválida en el lote")))
     .otherwise(F.col("peso_kg") + 1),
)
lote_malo.createOrReplaceTempView("lote_malo")

# 2. Estado antes del intento
actual_antes = spark.sql(f"SELECT snapshot_id FROM {TABLA}.snapshots ORDER BY committed_at DESC").first()[0]
peso_antes = spark.table(TABLA).agg(F.round(F.sum("peso_kg"), 2)).first()[0]

# 3. El MERGE falla: los errores del executor se silencian para que el notebook quede legible
sc.setLogLevel("OFF")
try:
    spark.sql(MERGE.replace("USING lote", "USING lote_malo").replace("t.estado <> s.estado", "t.peso_kg <> s.peso_kg"))
except Exception as error:
    print("El MERGE falló:", "fila inválida en el lote" in str(error))
sc.setLogLevel("ERROR")

# 4. Estado después del intento
actual_despues = spark.sql(f"SELECT snapshot_id FROM {TABLA}.snapshots ORDER BY committed_at DESC").first()[0]
print("¿Cambió la instantánea actual?", actual_antes != actual_despues)
print("Suma de pesos antes y después:", peso_antes, spark.table(TABLA).agg(F.round(F.sum("peso_kg"), 2)).first()[0])
El MERGE falló: True
¿Cambió la instantánea actual? False
Suma de pesos antes y después: 85483.92 85483.92

El MERGE falló con el error esperado, la instantánea actual no cambió (False) y la suma de pesos es la misma antes y después, 85 483.92 kg: ningún envío de junio quedó con el peso aumentado, aunque algunas tareas alcanzaron a escribir sus archivos antes del error. Con los archivos Parquet simples del capítulo de ingesta, un fallo a mitad de la escritura de la plata podía dejar unas fechas nuevas y otras viejas; aquí no hay estado intermedio.

7. Deshacer un error

Los errores de operación son más comunes que los fallos técnicos. Alguien quiere borrar unos envíos Express de prueba y escribe un DELETE sin la condición completa. La celda lo simula, mide el daño y vuelve a la instantánea anterior con el procedimiento rollback_to_snapshot. Los procedimientos de Iceberg se ejecutan con CALL lago.system.<nombre>(…).

# 1. La instantánea buena, antes del error
buena = spark.sql(f"SELECT snapshot_id FROM {TABLA}.snapshots ORDER BY committed_at DESC").first()[0]

# 2. El error: alguien borra todos los Express, cuando quería borrar solo los de prueba
spark.sql(f"DELETE FROM {TABLA} WHERE servicio = 'Express'")
print("Filas después del DELETE:", spark.table(TABLA).count())

# 3. Volver a la instantánea buena: no se copian datos, solo se mueve el puntero
spark.sql(f"CALL lago.system.rollback_to_snapshot('bitlogistica.envios', {buena})").show()
print("Filas después de deshacer:", spark.table(TABLA).count())

# 4. El historial conserva el DELETE, pero ya no forma parte de la línea actual
spark.sql(f"""
SELECT h.snapshot_id, s.operation AS operacion, h.is_current_ancestor AS en_la_linea_actual
FROM {TABLA}.history h JOIN {TABLA}.snapshots s ON h.snapshot_id = s.snapshot_id
ORDER BY h.made_current_at
""").show(truncate=False)
Filas después del DELETE: 24219
+--------------------+-------------------+
|previous_snapshot_id|current_snapshot_id|
+--------------------+-------------------+
| 8688154552080599216|7185803558959816085|
+--------------------+-------------------+

Filas después de deshacer: 32064
+-------------------+---------+------------------+
|snapshot_id        |operacion|en_la_linea_actual|
+-------------------+---------+------------------+
|2512792261418552131|append   |true              |
|5083678134533792060|overwrite|true              |
|7185803558959816085|overwrite|true              |
|8688154552080599216|overwrite|false             |
|7185803558959816085|overwrite|true              |
+-------------------+---------+------------------+

El DELETE dejó la tabla con 24 219 filas: se fueron los 7 845 envíos Express. El procedimiento devolvió el puntero a la instantánea anterior, y la tabla volvió a 32 064 filas en una fracción de segundo, porque no copió datos: los archivos de esa instantánea nunca se borraron. La tabla history lo cuenta así: la instantánea del DELETE sigue registrada, pero con en_la_linea_actual en false, y la instantánea buena aparece otra vez como actual.

Deshacer solo es posible mientras la instantánea buena exista. La sección 9 muestra cuándo deja de existir.

8. Evolución del esquema y de la partición

NotaEvolución del esquema y de la partición

Iceberg identifica cada columna por un número interno, no por su nombre ni por su posición. Por eso puede agregar, renombrar o borrar columnas cambiando solo los metadatos: los archivos viejos no tienen la columna nueva y se leen con nulos. De la misma forma, la especificación de partición (partition spec) puede cambiar: los archivos viejos conservan la que tenían y los nuevos usan la nueva. Las consultas funcionan sobre las dos a la vez.

El área comercial quiere marcar la prioridad de los envíos. La celda agrega la columna prioridad, le da el valor alta a los Express de junio y compara el esquema actual con el de la instantánea inicial.

# 1. Agregar una columna: solo cambia los metadatos, no reescribe ningún archivo
archivos_antes = spark.sql(f"SELECT count(*) FROM {TABLA}.files").first()[0]
spark.sql(f"ALTER TABLE {TABLA} ADD COLUMN prioridad STRING")
print("Archivos de datos antes y después de ALTER TABLE:", archivos_antes,
      spark.sql(f"SELECT count(*) FROM {TABLA}.files").first()[0])

# 2. Darle valor solo a los Express de junio
spark.sql(f"UPDATE {TABLA} SET prioridad = 'alta' WHERE servicio = 'Express' AND admision >= '2026-06-01'")
spark.sql(f"SELECT prioridad, COUNT(*) AS envios FROM {TABLA} GROUP BY prioridad ORDER BY prioridad").show()

# 3. Una instantánea anterior conserva su esquema: no tiene la columna nueva
print("Columnas hoy:", len(spark.table(TABLA).columns), "| en la instantánea inicial:",
      len(spark.sql(f"SELECT * FROM {TABLA} VERSION AS OF {INSTANTANEA_INICIAL}").columns))
Archivos de datos antes y después de ALTER TABLE: 6 6
+---------+------+
|prioridad|envios|
+---------+------+
|     NULL| 30756|
|     alta|  1308|
+---------+------+

Columnas hoy: 23 | en la instantánea inicial: 22

ALTER TABLE no reescribió nada: la tabla tenía 6 archivos de datos antes y después. Después del UPDATE, 1 308 envíos Express de junio tienen prioridad alta y los otros 30 756 la tienen nula, incluidos todos los anteriores a junio, que nunca se reescribieron. La tabla actual tiene 23 columnas; la instantánea inicial, 22: cada instantánea conserva el esquema con el que se escribió.

Ahora la partición. Con más envíos por día, un mes completo por archivo se vuelve demasiado grande, y BITLogística decide particionar por día desde julio. La celda cambia la especificación y simula diez lotes pequeños de julio, como si llegaran cada pocas horas. Como el caso solo tiene datos hasta junio, el experimento usa copias de los envíos del 1 al 3 de junio corridas 30 días, con la guía marcada -JUL; sirven para ver cómo se guardan, no para sacar conclusiones de negocio.

# 1. Desde julio la tabla se particiona por día; lo anterior queda como estaba, por mes
spark.sql(f"ALTER TABLE {TABLA} REPLACE PARTITION FIELD admision_month WITH days(admision)")

# 2. Diez lotes pequeños de «julio», como si llegaran cada pocas horas:
#    para el experimento, copias de los envíos del 1 al 3 de junio corridas 30 días
base_julio = (plata.drop("mes")
              .filter("admision >= '2026-06-01' AND admision < '2026-06-04'")
              .withColumn("prioridad", F.lit(None).cast("string"))
              .withColumn("guia", F.concat("guia", F.lit("-JUL")))
              .withColumn("admision", F.col("admision") + F.expr("INTERVAL 30 DAYS"))
              .withColumn("entrega", F.col("entrega") + F.expr("INTERVAL 30 DAYS"))
              .withColumn("lote", (F.abs(F.hash("guia")) % 10).cast("int")))
for numero in range(10):
    base_julio.filter(F.col("lote") == numero).drop("lote").writeTo(TABLA).append()

# 3. Los archivos de datos según su especificación de partición: por mes (spec 0) o por día (spec 1)
spark.sql(f"""
SELECT spec_id, COUNT(DISTINCT partition) AS particiones, SUM(record_count) AS filas, COUNT(*) AS archivos
FROM {TABLA}.files GROUP BY spec_id ORDER BY spec_id
""").show()

# 4. Una consulta por fecha usa las dos particiones sin que quien consulta sepa cuál
spark.sql(f"""
SELECT date_format(admision, 'yyyy-MM') AS mes, COUNT(*) AS envios
FROM {TABLA} WHERE admision >= '2026-06-01' GROUP BY 1 ORDER BY 1
""").show()
+-------+-----------+-----+--------+
|spec_id|particiones|filas|archivos|
+-------+-----------+-----+--------+
|      0|          6|32064|       6|
|      1|          3|  622|      30|
+-------+-----------+-----+--------+

+-------+------+
|    mes|envios|
+-------+------+
|2026-06|  5498|
|2026-07|   622|
+-------+------+

Los archivos de la tabla quedaron con dos especificaciones de partición. La 0, por mes, conserva los 6 archivos de enero a junio, con 32 064 filas en 6 particiones. La 1, por día, tiene las 622 filas de julio en 3 particiones diarias, pero en 30 archivos: cada uno de los diez lotes escribió un archivo en cada día. La consulta por mes no sabe nada de eso: filtra por admision y cuenta 5 498 envíos en junio y 622 en julio.

Treinta archivos para 622 filas es el problema de los archivos pequeños del capítulo de almacenamiento, ahora causado por cargas frecuentes. La sección siguiente lo resuelve.

9. Mantenimiento: compactar y expirar

Una tabla Iceberg acumula dos cosas con el tiempo: archivos pequeños, por las cargas frecuentes, e instantáneas, una por escritura, con todos los archivos que cada una mantiene vivos. Dos procedimientos las controlan:

  • rewrite_data_files compacta: junta los archivos pequeños de cada partición en archivos más grandes, en una nueva instantánea, sin cambiar los datos. La celda lo limita a julio con where, porque en una tabla grande se compacta lo reciente y no todo; y usa min-input-files en 2 porque, por defecto, Iceberg solo compacta una partición si tiene al menos 5 archivos en un mismo grupo de reescritura, un umbral pensado para tablas mucho más grandes.
  • expire_snapshots expira las instantáneas anteriores a una fecha y borra los archivos que solo ellas usaban. La celda conserva solo la última para que el efecto se vea completo; en producción se conservan varios días, para poder viajar en el tiempo y deshacer errores dentro de ese plazo.
DESDE_JULIO = "admision >= '2026-07-01'"

# 1. Antes: archivos de julio e instantáneas acumuladas
def contar():
    archivos_julio = spark.sql(f"SELECT count(*) FROM {TABLA}.files WHERE spec_id = 1").first()[0]   # spec 1 = julio
    instantaneas = spark.sql(f"SELECT count(*) FROM {TABLA}.snapshots").first()[0]
    return archivos_julio, instantaneas

print("Antes de mantener  -> archivos de julio: %d | instantáneas: %d" % contar())
POR_DIA = (f"SELECT date_format(partition.admision_day, 'dd-MM') AS dia, COUNT(*) AS file_count "
           f"FROM {TABLA}.files WHERE spec_id = 1 GROUP BY 1 ORDER BY 1")
por_dia_antes = spark.sql(POR_DIA).toPandas()

# 2. Compactar solo julio: juntar los archivos pequeños de cada partición diaria
spark.sql(f"""
CALL lago.system.rewrite_data_files(
    table => 'bitlogistica.envios',
    where => "{DESDE_JULIO}",
    options => map('min-input-files', '2'))
""").show()

# 3. Expirar instantáneas: conservar solo la última
ahora = datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")
spark.sql(f"""
CALL lago.system.expire_snapshots(
    table => 'bitlogistica.envios',
    older_than => TIMESTAMP '{ahora}',
    retain_last => 1)
""").select("deleted_data_files_count", "deleted_manifest_files_count", "deleted_manifest_lists_count").show()
print("Después de mantener -> archivos de julio: %d | instantáneas: %d" % contar())

# 4. El costo: la instantánea inicial ya no existe
try:
    spark.sql(f"SELECT COUNT(*) FROM {TABLA} VERSION AS OF {INSTANTANEA_INICIAL}").show()
except Exception as error:
    print("Viaje a la instantánea inicial:", str(error).split("\n")[0][:110])
Antes de mantener  -> archivos de julio: 30 | instantáneas: 15
+--------------------------+----------------------+---------------------+-----------------------+
|rewritten_data_files_count|added_data_files_count|rewritten_bytes_count|failed_data_files_count|
+--------------------------+----------------------+---------------------+-----------------------+
|                        30|                     3|               238938|                      0|
+--------------------------+----------------------+---------------------+-----------------------+

+------------------------+----------------------------+----------------------------+
|deleted_data_files_count|deleted_manifest_files_count|deleted_manifest_lists_count|
+------------------------+----------------------------+----------------------------+
|                      40|                          20|                          15|
+------------------------+----------------------------+----------------------------+

Después de mantener -> archivos de julio: 3 | instantáneas: 1
Viaje a la instantánea inicial: Cannot find snapshot with ID 2512792261418552131

Antes del mantenimiento, julio tenía 30 archivos y la tabla, 15 instantáneas: la creación, los dos MERGE, el DELETE, el UPDATE y los diez lotes de julio. El rollback no creó una instantánea, solo movió el puntero, y los ALTER TABLE cambiaron metadatos sin escribir datos.

La compactación reescribió los 30 archivos de julio, unos 239 KB, en 3, uno por día. La expiración borró 40 archivos de datos que ya no pertenecían a ninguna instantánea conservada (las versiones viejas de mayo y junio, el DELETE deshecho y los 30 archivos pequeños de julio), 20 manifiestos y 15 listas de manifiestos. Quedó 1 instantánea. El costo se ve en la última línea: la instantánea inicial ya no existe, y el viaje en el tiempo de la sección 5 ahora falla con Cannot find snapshot.

antes_compactar = por_dia_antes.rename(columns={"file_count": "antes"})
antes_compactar["despues"] = spark.sql(POR_DIA).toPandas()["file_count"].values
figura, eje = plt.subplots(figsize=(7, 3.2))
x = range(len(antes_compactar))
eje.bar([i - 0.2 for i in x], antes_compactar["antes"], width=0.4, label="Antes de compactar")
eje.bar([i + 0.2 for i in x], antes_compactar["despues"], width=0.4, label="Después", hatch="//", edgecolor="white")
for i, (a, d) in enumerate(zip(antes_compactar["antes"], antes_compactar["despues"])):
    eje.text(i - 0.2, a + 0.2, str(a), ha="center", fontsize=9)
    eje.text(i + 0.2, d + 0.2, str(d), ha="center", fontsize=9)
eje.set_xticks(list(x), antes_compactar["dia"])
eje.set_xlabel("Partición diaria (día-mes)")
eje.set_ylabel("Archivos de datos")
eje.set_ylim(0, antes_compactar["antes"].max() * 1.35)
eje.legend(frameon=False, loc="upper center", ncol=2)
plt.tight_layout()
plt.show()
Barras agrupadas para el 1, el 2 y el 3 de julio, con los archivos de datos de cada día antes y después de compactar.
Figura 24.1: Archivos de datos de cada partición diaria de julio antes y después de compactar

En la figura, cada día de julio pasó de 10 archivos a 1. La regla práctica es compactar las particiones recientes con frecuencia, por ejemplo cada noche, y expirar instantáneas con un plazo acordado con el negocio: tantos días como se quiera poder reproducir un informe o deshacer un error. Un tercer procedimiento, remove_orphan_files, borra los archivos huérfanos de escrituras fallidas, como las de la sección 6.

10. Parquet simple frente a Iceberg

Necesidad Parquet simple (capítulo de ingesta) Iceberg
Actualizar unas filas Recalcular particiones completas MERGE, UPDATE y DELETE
Escritura que falla a la mitad Puede quedar a medias La tabla no cambia
Ver la tabla como estaba No VERSION AS OF y TIMESTAMP AS OF
Deshacer un error Restaurar un respaldo, si existe rollback_to_snapshot
Agregar una columna mergeSchema en cada lectura ALTER TABLE, sin reescribir
Cambiar la partición Reescribir toda la tabla Cambiar la especificación; lo viejo queda como estaba
Filtrar por fecha Hay que conocer la columna de partición Partición oculta
Qué archivos forman la tabla Lo que haya en la carpeta Lo que digan los metadatos
Costo Ninguno adicional Un .jar, metadatos y mantenimiento periódico

Los archivos Parquet simples siguen siendo una buena opción para datos que solo se agregan, nunca se corrigen y tienen un solo escritor, como un registro de eventos crudos en la zona de llegada. Para las capas que se corrigen y que leen muchos (plata y oro), un formato de tabla evita la mayor parte de los problemas que el capítulo de ingesta resolvió con código propio.

Limpiar

La celda cierra la sesión. La tabla lago.bitlogistica.envios queda en /bitlogistica/lakehouse para los capítulos siguientes. Para borrarla a mano: dc exec spark-client /opt/hadoop/bin/hdfs dfs -rm -r /bitlogistica/lakehouse.

spark.stop()
print("Sesión cerrada. La tabla Iceberg queda en /bitlogistica/lakehouse para los capítulos siguientes.")
Sesión cerrada. La tabla Iceberg queda en /bitlogistica/lakehouse para los capítulos siguientes.

La sesión quedó cerrada. En la siguiente sesión, la tabla se lee con el mismo catálogo lago: basta con repetir las cuatro opciones de la sesión de la sección 2.

Práctica

Para hacer estos ejercicios, ejecuta de nuevo las celdas de las secciones 2 a 4 (la sesión, la tabla y el lote).

  1. MERGE sin reescrituras inútiles. Antes de repetir el MERGE de la sección 4, quita del lote las filas que ya están iguales en la tabla con una unión anti por guía, entrega y estado. ¿Cuántas filas quedan? ¿Qué muestra el historial?
  2. Viajar por fecha. Usa TIMESTAMP AS OF con la hora de la instantánea inicial (columna committed_at de la tabla snapshots) y comprueba que da el mismo cumplimiento de mayo que VERSION AS OF.
  3. Borrar con condición correcta. Borra solo los envíos de julio de prueba (guia LIKE '%-JUL') y comprueba en el historial cuántas filas quitó la operación.
  4. Fusionar al leer. Crea una copia de la tabla con TBLPROPERTIES ('write.merge.mode' = 'merge-on-read') y repite el MERGE de las correcciones. Compara en la tabla files cuántos archivos de datos y de borrados se escribieron.
  5. Renombrar una columna. Renombra prioridad a nivel_servicio con ALTER TABLE … RENAME COLUMN y comprueba que las filas conservan sus valores.
  6. Expirar con un plazo. En lugar de conservar solo la última instantánea, expira las de más de una hora. ¿Cuántas quedan?
  1. Con lote.join(spark.table(TABLA).select("guia", "entrega", "estado"), ["guia", "entrega", "estado"], "left_anti") no queda ninguna fila después del primer MERGE, porque todo el lote ya está igual en la tabla. Con un lote vacío, el MERGE no reescribe nada; según la versión, Iceberg no crea instantánea o crea una sin archivos agregados ni quitados.
  2. SELECT … FROM tabla TIMESTAMP AS OF '<committed_at>' da 85.16 % para mayo, igual que la versión inicial. Si la hora pedida es anterior a la primera instantánea, Iceberg responde que no hay instantánea en esa fecha.
  3. El historial muestra una operación delete u overwrite que quita 622 filas, las de julio. Con particiones diarias y todas las filas de un día por borrar, Iceberg puede quitar archivos completos sin reescribir ninguno.
  4. Con fusionar al leer, el MERGE escribe un archivo de borrados pequeño (en la tabla files, content = 1) y un archivo con las 300 filas nuevas, en lugar de reescribir las 6 519 filas de mayo. La lectura combina los dos; por eso conviene compactar más seguido.
  5. ALTER TABLE lago.bitlogistica.envios RENAME COLUMN prioridad TO nivel_servicio. Los 1 308 valores alta siguen ahí: Iceberg los encuentra por el número interno de la columna, no por el nombre.
  6. Depende de cuánto tardaste: quedan las instantáneas de la última hora. Si todas son de la última hora, expire_snapshots no borra ninguna.

Errores frecuentes

Síntoma Causa Arreglo
Falta el .jar de Iceberg en notebooks/jars No se descargó la librería o quedó en otra carpeta. Repetir la descarga de «Antes de empezar».
ClassNotFoundException: org.apache.iceberg.spark.SparkCatalog La sesión se creó antes de agregar spark.jars, o el kernel tenía otra sesión abierta. Reiniciar el kernel y crear la sesión con las cuatro opciones.
UnsupportedClassVersionError: … class file version 55.0 … up to 52.0 al crear la tabla Se descargó Iceberg 1.7 o posterior, compilado para Java 11, y los executors de los NodeManagers corren con Java 8. Usar iceberg-spark-runtime-3.5_2.12-1.6.1.jar, reiniciar el kernel y volver a ejecutar.
MERGE INTO TABLE is not supported temporarily Falta spark.sql.extensions de Iceberg. Agregar la opción y reiniciar el kernel.
Cannot find snapshot with ID La instantánea se expiró. Expirar con un plazo que cubra los viajes en el tiempo que se necesiten.
La tabla acumula cientos de archivos pequeños Cargas frecuentes con pocas filas por partición. rewrite_data_files periódico sobre las particiones recientes.
Un MERGE que no cambia nada reescribe archivos Copiar al escribir reescribe todo archivo con filas que coinciden. Dejar en el lote solo las filas que cambiaron.
MERGE falla con cannot be performed with multiple matches El origen tiene la misma guía dos veces. Quitar duplicados del lote antes, como en el capítulo de ingesta.

Preguntas de comprensión

  1. ¿Por qué una escritura que falla no cambia una tabla Iceberg, aunque haya alcanzado a escribir archivos?
  2. ¿Qué diferencia hay entre la partición oculta de Iceberg y la columna mes del capítulo de almacenamiento?
  3. Si el MERGE de la sección 4 solo cambió 300 filas, ¿por qué el historial dice que quitó 6 519?
  4. ¿Qué se gana y qué se pierde al expirar instantáneas?
  5. ¿Cuándo bastan los archivos Parquet simples, sin formato de tabla?
  1. Porque la tabla es lo que dicen sus metadatos, y los metadatos solo cambian en el último paso, cuando el catálogo pasa a apuntar a la nueva versión. Los archivos escritos antes del fallo no figuran en ninguna instantánea: existen en HDFS, pero no forman parte de la tabla.
  2. La columna mes era una columna más, que había que crear, mantener y usar en los filtros para que la partición sirviera. La partición oculta se define como una transformación de admision en los metadatos; quien consulta filtra por admision e Iceberg aplica la partición por su cuenta, y la transformación se puede cambiar sin tocar las consultas.
  3. Por copiar al escribir: Iceberg no modifica archivos, así que reemplazó el archivo de mayo completo, con sus 6 519 filas, por uno nuevo con las 300 corregidas. En el historial cuenta como quitar 6 519 filas y agregar 6 519, más las 5 498 de junio.
  4. Se gana espacio y metadatos más livianos, porque se borran los archivos que solo usaban las instantáneas viejas. Se pierde la posibilidad de viajar en el tiempo y de deshacer operaciones anteriores al plazo de expiración.
  5. Cuando los datos solo se agregan, nunca se corrigen, hay un solo proceso que escribe y nadie necesita consultar versiones anteriores, como en una zona de llegada o un registro de eventos crudos.

Glosario

Término Significado en este capítulo
Formato de tabla Registro de qué archivos forman una tabla, con su esquema, particiones e historial.
Lakehouse Data lake con transacciones, actualizaciones e historial gracias a un formato de tabla.
Metadatos de la tabla Archivos JSON y Avro que describen la tabla y sus instantáneas.
Instantánea Estado completo de la tabla después de una escritura.
Manifiesto Archivo de metadatos con una lista de archivos de datos y sus estadísticas.
Partición oculta Partición definida como transformación de una columna, que el lector no necesita conocer.
MERGE INTO Instrucción que actualiza las filas existentes e inserta las nuevas en una sola operación.
Copiar al escribir Estrategia que reescribe completo cada archivo que tiene filas cambiadas.
Fusionar al leer Estrategia que escribe archivos de borrados y combina al leer.
Viaje en el tiempo Consulta de la tabla como estaba en una instantánea anterior.
Transacción atómica Operación que se aplica completa o no se aplica.
Rollback Volver a una instantánea anterior moviendo el puntero de la tabla.
Especificación de partición Forma de particionar vigente para un grupo de archivos.
Compactar Juntar archivos pequeños en archivos más grandes.
Expirar instantáneas Borrar instantáneas viejas y los archivos que solo ellas usaban.
Archivo huérfano Archivo en la carpeta de la tabla que no pertenece a ninguna instantánea.

Referencias para profundizar

Resumen

Con los envíos de BITLogística convertiste la plata en una tabla Iceberg sobre el mismo HDFS, sin servicios nuevos. La tabla nació con 26 566 envíos de enero a mayo, particionada por mes sin columna mes, y sus metadatos ocuparon el 3 % del tamaño de los datos. Un solo MERGE agregó los 5 498 envíos de junio y aplicó 300 correcciones de mayo; repetirlo no duplicó nada, aunque reescribió archivos sin necesidad. El viaje en el tiempo reprodujo el cumplimiento de mayo antes de las correcciones, 85.16 %, frente al 84.36 % de después. Un MERGE que falló a mitad de camino no cambió ni un kilo de la tabla, y un DELETE equivocado que borró 7 845 envíos se deshizo con un rollback. La columna prioridad y la partición diaria de julio llegaron sin reescribir los datos anteriores. La compactación juntó los 30 archivos de julio en 3 y la expiración dejó una sola instantánea, con el costo visible de perder el viaje al pasado.

El capítulo siguiente, Kafka y eventos, cambia de ritmo: en lugar de archivos que llegan cada día, envíos que se publican uno por uno en el momento en que se admiten.