Explorar guías rápidas · Microsoft Fabric

Tecnología: Microsoft FabricCategoría: Ingeniería de datosNivel: IntermedioActualizado

Patrones de lectura y escritura en Delta Lake

Lee y escribe tablas Delta en Microsoft Fabric de forma segura con append, overwrite, MERGE, particionamiento, control del esquema, patrones preparados para la concurrencia y mantenimiento de tablas.

En esta página
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Leer una tabla Delta administrada por su nombre
  5. 2. Leer una tabla Delta por ruta
  6. 3. Leer solo las columnas que necesitas
  7. 4. Filtrar pronto
  8. 5. Anexar filas nuevas inmutables
  9. 6. Añadir un identificador de lote de ingesta
  10. 7. Sobrescribir una tabla completa solo cuando el reemplazo total sea intencionado
  11. 8. Sobrescribir el esquema solo cuando el cambio de esquema sea deliberado
  12. 9. Usar mergeSchema con cuidado para la evolución aditiva del esquema
  13. 10. Hacer upsert con MERGE de Delta
  14. 11. Preferir asignaciones de actualización explícitas para contratos de producción estables
  15. 12. Deduplicar el origen antes de MERGE
  16. 13. Validar la unicidad del origen antes de un merge
  17. 14. Usar una clave de negocio compuesta cuando una sola columna no basta
  18. 15. Actualizar solo cuando la fila entrante sea más reciente
  19. 16. Insertar solo claves nuevas
  20. 17. Eliminar mediante MERGE solo con un contrato de origen deliberado
  21. 18. Usar MERGE en SQL cuando SQL sea más claro
  22. 19. Usar staging + merge para la ingesta concurrente
  23. 20. Diseñar la lógica de reintentos para conflictos concurrentes de Delta
  24. 21. Entender Low Shuffle Merge en Fabric
  25. 22. Particionar solo por dimensiones útiles de cardinalidad baja o moderada
  26. 23. No sobreparticionar las tablas pequeñas
  27. 24. Inspeccionar la distribución de particiones antes de cambiar la organización
  28. 25. Evitar repartition(1) antes de escribir en Delta
  29. 26. Reducir un exceso de particiones de escritura cuando la salida es pequeña
  30. 27. Compactar archivos pequeños con OPTIMIZE
  31. 28. Usar Z-Order solo para un patrón de acceso real
  32. 29. Entender V-Order en Fabric
  33. 30. Inspeccionar la configuración de optimización de Fabric antes de cambiarla
  34. 31. Usar VACUUM para limpiar el almacenamiento, no para ajustar consultas
  35. 32. Usar VACUUM LITE solo en runtimes de Fabric compatibles
  36. 33. No reducir la retención de VACUUM a la ligera
  37. 34. Leer una versión anterior de Delta para investigar
  38. 35. Inspeccionar el historial de Delta
  39. 36. Comparar recuentos antes y después de las escrituras
  40. 37. Conciliar las claves de negocio después de un upsert
  41. 38. Guardar metadatos de ejecución para las cargas incrementales
  42. 39. Evitar leer y reescribir todo el destino para un cambio incremental pequeño
  43. 40. Mantener la ingesta bruta como solo anexado cuando sea posible
  44. Qué significa el resultado
  45. Qué revisar
  46. El recuento de filas del destino crece con cada reejecución
  47. MERGE toca muchos más datos de lo esperado
  48. Los trabajos concurrentes fallan durante las escrituras
  49. La tabla tiene muchos archivos pequeños
  50. Las lecturas se ralentizan después de muchas actualizaciones o merges
  51. Las versiones antiguas de la tabla dejan de funcionar
  52. Notas de producción
  53. Delta ofrece transacciones ACID sobre la tabla, no restricciones de negocio arbitrarias
  54. Low Shuffle Merge de Fabric ya está activado por defecto
  55. Las escrituras concurrentes requieren un diseño que tenga en cuenta la organización de los datos
  56. OPTIMIZE y VACUUM resuelven problemas diferentes
  57. VACUUM afecta a la capacidad de recuperación
  58. Los valores predeterminados de V-Order han cambiado con el tiempo
  59. Mantén el mantenimiento de tablas fuera de las ventanas de escritura pico cuando sea práctico
  60. El particionamiento no es obligatorio
  61. Errores comunes
  62. 1. Usar append para un feed modificable que puede reprocesarse
  63. 2. Usar overwrite en cada reejecución
  64. 3. Usar whenMatchedUpdateAll() sin pensar en el esquema
  65. 4. Hacer merge con claves duplicadas en el origen
  66. 5. Particionar por un identificador de alta cardinalidad
  67. 6. Llamar a repartition(1) antes de cada escritura
  68. 7. Ejecutar VACUUM para que las consultas sean más rápidas
  69. 8. Reducir la retención de VACUUM sin entender el time travel
  70. 9. Tratar una transacción Delta correcta como prueba de que las métricas son correctas
  71. 10. Reintentar todas las excepciones de escritura
  72. Siguiente paso
  73. Para profundizar

Problema

Las tablas de Lakehouse de Microsoft Fabric usan Delta Lake, que ofrece a las cargas de trabajo de Spark una semántica de tabla transaccional sobre archivos Parquet en OneLake.

La sintaxis para leer y escribir tablas Delta es sencilla.

Las preguntas de producción son más difíciles:

  • ¿Esta carga debe hacer append, overwrite o merge?
  • ¿La operación es idempotente?
  • ¿Varios procesos de escritura concurrentes tocarán los mismos archivos?
  • ¿Se aceptarán o se rechazarán los cambios de esquema?
  • ¿El particionamiento ayuda o está creando archivos pequeños?
  • ¿Las actualizaciones repetidas están fragmentando los archivos?
  • ¿Cuándo deberías ejecutar OPTIMIZE o VACUUM?
  • ¿Cómo evitas reescribir muchos más datos de los necesarios?

El objetivo es elegir el patrón de escritura a partir del contrato de datos, no según el comando que resulte más fácil de volver a ejecutar.

Respuesta rápida

Usa este flujo de decisión:

Solo filas nuevas inmutables
→ APPEND

Reconstruir intencionadamente toda la tabla
→ OVERWRITE

Insertar + actualizar claves de negocio existentes
→ MERGE

Reemplazar solo un segmento/partición conocido
→ overwrite selectivo / patrón que tenga en cuenta las particiones

Muchos productores concurrentes
→ append a staging y después conciliación con un MERGE controlado

Leer una tabla Delta de un Lakehouse:

df = spark.read.table("sales")

o bien:

df = (
    spark.read
    .format("delta")
    .load("Tables/sales")
)

Append (anexar):

(
    df.write
    .format("delta")
    .mode("append")
    .saveAsTable("sales")
)

Upsert:

from delta.tables import DeltaTable

target = DeltaTable.forName(
    spark,
    "sales",
)

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

No uses la sobrescritura completa de la tabla como estrategia predeterminada para las reejecuciones.

Código / comandos

1. Leer una tabla Delta administrada por su nombre

sales = spark.read.table(
    "sales"
)

Equivalente en Spark SQL:

sales = spark.sql(
    "SELECT * FROM sales"
)

Usa nombres de tabla cuando la tabla esté registrada en el metastore del Lakehouse y el notebook esté asociado al Lakehouse previsto.


2. Leer una tabla Delta por ruta

sales = (
    spark.read
    .format("delta")
    .load("Tables/sales")
)

Usa lecturas por ruta cuando:

  • la propia ruta forme parte del diseño
  • trabajes con una ubicación explícita de OneLake
  • no quieras depender del espacio de nombres de tablas del Lakehouse predeterminado actual

En código de producción, evita mezclar a la ligera la semántica por nombre de tabla y por ruta.

Elige un patrón coherente para la carga de trabajo.


3. Leer solo las columnas que necesitas

sales = (
    spark.read.table("sales")
    .select(
        "sale_id",
        "merchant_id",
        "sale_date",
        "amount",
    )
)

La poda de columnas (column pruning) reduce la cantidad de datos que arrastran las transformaciones posteriores.

Esto importa en tablas Delta anchas.


4. Filtrar pronto

from pyspark.sql import functions as F

sales = (
    spark.read.table("sales")
    .filter(
        F.col("sale_date") >= "2026-10-01"
    )
    .select(
        "sale_id",
        "merchant_id",
        "sale_date",
        "amount",
    )
)

Filtrar antes de los joins y las agregaciones puede reducir:

  • el volumen escaneado
  • el volumen de shuffle
  • la presión de memoria
  • el tamaño de la salida

Que cada predicado pueda trasladarse a la lectura (pushdown) depende de la organización de la tabla y de la expresión.


5. Anexar filas nuevas inmutables

(
    new_sales.write
    .format("delta")
    .mode("append")
    .saveAsTable("sales")
)

Usa append cuando las filas sean realmente nuevas y las filas existentes no deban modificarse.

Ejemplos típicos:

  • ingesta de eventos inmutables
  • datos brutos de aterrizaje
  • historial de auditoría de solo anexado

Append no es idempotente automáticamente.

Si el mismo lote puede volver a procesarse, la prevención de duplicados debe diseñarse por separado.


6. Añadir un identificador de lote de ingesta

Para detectar reprocesamientos:

from pyspark.sql import functions as F

new_sales = (
    new_sales
    .withColumn(
        "ingestion_batch_id",
        F.lit("2026-10-04T1700Z"),
    )
)

Esto puede ayudar a identificar:

  • cargas de lotes duplicadas
  • reejecuciones
  • procesamiento parcial
  • linaje

Un identificador de lote no evita los duplicados por sí solo.

Te da evidencia para garantizar o auditar la idempotencia.


7. Sobrescribir una tabla completa solo cuando el reemplazo total sea intencionado

(
    rebuilt_table.write
    .format("delta")
    .mode("overwrite")
    .saveAsTable("sales_summary")
)

Úsalo para:

  • tablas derivadas pequeñas
  • reconstrucciones completas y deterministas
  • tablas cuyo contrato sea explícitamente reemplazarlo todo

No uses overwrite simplemente porque sea más fácil que implementar lógica incremental.

Una sobrescritura completa puede:

  • reescribir grandes cantidades de datos
  • aumentar el tiempo de ejecución
  • crear más archivos obsoletos
  • aumentar el riesgo de conflictos
  • afectar a lectores y escritores concurrentes según la operación

8. Sobrescribir el esquema solo cuando el cambio de esquema sea deliberado

(
    rebuilt_table.write
    .format("delta")
    .mode("overwrite")
    .option(
        "overwriteSchema",
        "true",
    )
    .saveAsTable("sales_summary")
)

Usa overwriteSchema solo cuando reemplazar el esquema de la tabla forme parte de la migración o de la reconstrucción.

No lo habilites de forma global.

Los cambios de esquema deben ser intencionados y validarse con los consumidores posteriores.


9. Usar mergeSchema con cuidado para la evolución aditiva del esquema

(
    new_data.write
    .format("delta")
    .mode("append")
    .option(
        "mergeSchema",
        "true",
    )
    .saveAsTable("sales")
)

Esto puede permitir que se añadan columnas nuevas compatibles.

No uses la evolución del esquema para ocultar la deriva de esquema en el origen.

Antes de habilitarlo en producción, decide:

¿Qué columnas pueden aparecer?
¿Quién es responsable de los cambios de esquema?
¿Cómo se notificará a los consumidores posteriores?

10. Hacer upsert con MERGE de Delta

from delta.tables import DeltaTable

target = DeltaTable.forName(
    spark,
    "sales",
)

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

Usa MERGE cuando la clave de negocio pueda existir ya y los datos entrantes puedan:

  • actualizar filas existentes
  • insertar filas nuevas

La condición de merge debe representar la verdadera clave de negocio.


11. Preferir asignaciones de actualización explícitas para contratos de producción estables

En lugar de:

.whenMatchedUpdateAll()

usa asignaciones explícitas cuando el control del esquema importe:

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdate(
        set={
            "merchant_id": "s.merchant_id",
            "sale_date": "s.sale_date",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        }
    )
    .whenNotMatchedInsert(
        values={
            "sale_id": "s.sale_id",
            "merchant_id": "s.merchant_id",
            "sale_date": "s.sale_date",
            "amount": "s.amount",
            "updated_at": "s.updated_at",
        }
    )
    .execute()
)

Las asignaciones explícitas reducen el acoplamiento accidental entre el esquema de origen y el de destino.


12. Deduplicar el origen antes de MERGE

Si el origen contiene varias filas para la misma clave de destino, decide cuál debe prevalecer.

Ejemplo:

from pyspark.sql import Window
from pyspark.sql import functions as F

w = (
    Window
    .partitionBy("sale_id")
    .orderBy(
        F.col("updated_at").desc(),
        F.col("source_sequence").desc(),
    )
)

source_deduped = (
    source
    .withColumn(
        "_rn",
        F.row_number().over(w),
    )
    .filter(
        F.col("_rn") == 1
    )
    .drop("_rn")
)

Después, haz el merge de source_deduped.

No confíes en un orden arbitrario de las filas del origen.


13. Validar la unicidad del origen antes de un merge

duplicate_keys = (
    source
    .groupBy("sale_id")
    .count()
    .filter(
        F.col("count") > 1
    )
)

duplicate_keys.show(
    50,
    truncate=False,
)

Si el origen debería ser único y esto devuelve filas, detente e investiga.

Las claves duplicadas en el origen pueden hacer que el comportamiento del merge sea ambiguo o que falle, según el patrón de coincidencia.


14. Usar una clave de negocio compuesta cuando una sola columna no basta

merge_condition = """
    t.member_id = s.member_id
    AND t.merchant_id = s.merchant_id
    AND t.site_id = s.site_id
"""

Luego:

(
    target.alias("t")
    .merge(
        source.alias("s"),
        merge_condition,
    )
    .whenMatchedUpdateAll()
    .whenNotMatchedInsertAll()
    .execute()
)

No simplifiques una clave compuesta real solo para acortar el código del merge.


15. Actualizar solo cuando la fila entrante sea más reciente

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedUpdateAll(
        condition="""
            s.updated_at > t.updated_at
        """
    )
    .whenNotMatchedInsertAll()
    .execute()
)

Esto evita que un reprocesamiento más antiguo sobrescriba un estado más reciente.

Úsalo solo cuando updated_at tenga una semántica de orden fiable.


16. Insertar solo claves nuevas

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenNotMatchedInsertAll()
    .execute()
)

Este patrón puede hacer que una ingesta de tipo append sea idempotente por clave de negocio.

Es más costoso que un append a ciegas porque el destino debe participar en la búsqueda de coincidencias.

Úsalo cuando la prevención de duplicados compense ese costo.


17. Eliminar mediante MERGE solo con un contrato de origen deliberado

Ejemplo:

(
    target.alias("t")
    .merge(
        source.alias("s"),
        "t.sale_id = s.sale_id",
    )
    .whenMatchedDelete(
        condition="s.is_deleted = true"
    )
    .whenMatchedUpdateAll(
        condition="s.is_deleted = false"
    )
    .whenNotMatchedInsertAll(
        condition="s.is_deleted = false"
    )
    .execute()
)

Usa la eliminación dirigida por el origen solo cuando el indicador de eliminación tenga una semántica de negocio fiable.

No deduzcas una eliminación solo porque una fila no aparece en un lote incremental del origen.


18. Usar MERGE en SQL cuando SQL sea más claro

MERGE INTO sales AS t
USING sales_stage AS s
ON t.sale_id = s.sale_id

WHEN MATCHED
    AND s.updated_at > t.updated_at
THEN UPDATE SET
    t.merchant_id = s.merchant_id,
    t.sale_date = s.sale_date,
    t.amount = s.amount,
    t.updated_at = s.updated_at

WHEN NOT MATCHED
THEN INSERT
(
    sale_id,
    merchant_id,
    sale_date,
    amount,
    updated_at
)
VALUES
(
    s.sale_id,
    s.merchant_id,
    s.sale_date,
    s.amount,
    s.updated_at
);

Tanto Spark SQL como la API de Delta funcionan bien.

Elige la forma que haga más fácil revisar la transformación.


19. Usar staging + merge para la ingesta concurrente

Una arquitectura más segura para alta concurrencia es:

    • Productor A
    • Productor B
    • Productor C
  1. solo anexado
    Staging Delta
  2. MERGE controlado
  3. Delta de destino
Staging y merge para la ingesta concurrente

Un staging de solo anexado reduce los conflictos entre productores independientes.

Después, un merge controlado realiza la conciliación del destino, que es propensa a conflictos.

Esto es especialmente útil cuando varias actividades de notebook o pipeline pueden llegar al mismo tiempo.


20. Diseñar la lógica de reintentos para conflictos concurrentes de Delta

Delta ofrece commits transaccionales, así que una transacción fallida no deja la tabla en un estado parcialmente confirmado.

En cargas de trabajo donde se esperan conflictos lógicos de escritura, reintenta solo los casos de fallo de concurrencia conocidos.

Patrón conceptual:

import time

max_retries = 3

for attempt in range(max_retries):
    try:
        run_merge()
        break
    except Exception as exc:
        if not is_expected_delta_conflict(exc):
            raise

        if attempt == max_retries - 1:
            raise

        time.sleep(2 ** attempt)

No captures todas las excepciones ni reintentes a ciegas.

Reintenta:

  • condiciones transitorias o de conflicto que entiendas

No reintentes automáticamente:

  • un esquema incorrecto
  • datos de origen mal formados
  • una lógica de merge no válida
  • fallos de permisos

21. Entender Low Shuffle Merge en Fabric

Fabric Spark incluye la optimización Low Shuffle Merge para MERGE de Delta.

Está activada por defecto en los runtimes de Fabric Spark.

Comprueba la configuración de la sesión actual:

print(
    spark.conf.get(
        "spark.microsoft.delta.merge.lowShuffle.enabled"
    )
)

Establécela explícitamente si lo necesitas para pruebas controladas:

spark.conf.set(
    "spark.microsoft.delta.merge.lowShuffle.enabled",
    True,
)

No trates esta optimización como sustituto de:

  • condiciones de merge selectivas
  • claves de negocio correctas
  • una buena organización de archivos
  • la reducción del volumen de origen

22. Particionar solo por dimensiones útiles de cardinalidad baja o moderada

Ejemplo:

(
    sales.write
    .format("delta")
    .mode("append")
    .partitionBy(
        "sale_year",
        "sale_month",
    )
    .saveAsTable("sales")
)

Los buenos candidatos de partición suelen coincidir con:

  • filtros de poda habituales
  • límites de ingesta
  • límites de aislamiento entre escritores

Entre los malos candidatos suelen estar:

  • identificadores de transacción
  • marcas de tiempo exactas
  • identificadores de cliente con millones de valores

El particionamiento de alta cardinalidad crea un número excesivo de directorios y archivos.


23. No sobreparticionar las tablas pequeñas

Una tabla no necesita particionamiento físico solo porque tenga una columna de fecha.

Para tablas pequeñas o medianas, una tabla Delta sin particionar puede ser más sencilla y rendir bien.

El particionamiento debe resolver un problema concreto, como:

  • la poda de datos
  • el aislamiento de escrituras
  • la gestión del ciclo de vida

24. Inspeccionar la distribución de particiones antes de cambiar la organización

(
    sales
    .groupBy(
        "sale_year",
        "sale_month",
    )
    .count()
    .orderBy(
        F.desc("count")
    )
    .show(
        100,
        truncate=False,
    )
)

Usa la distribución real de los datos para evaluar si las particiones propuestas estarían equilibradas y serían útiles.


25. Evitar repartition(1) antes de escribir en Delta

Arriesgado:

(
    df.repartition(1)
    .write
    .format("delta")
    .mode("append")
    .saveAsTable("sales")
)

Esto crea un cuello de botella de escritura en una sola partición.

Las tablas Delta están diseñadas para contener varios archivos Parquet.

Si un proceso posterior necesita un único archivo de exportación, resuélvelo como un requisito de exportación aparte.


26. Reducir un exceso de particiones de escritura cuando la salida es pequeña

Si el resultado final es pequeño pero sigue teniendo muchas particiones de Spark:

smaller = df.coalesce(20)

Después escribe:

(
    smaller.write
    .format("delta")
    .mode("append")
    .saveAsTable("sales_summary")
)

Hazlo solo después de medir.

Muy pocas particiones también pueden crear tareas grandes o lentas.


27. Compactar archivos pequeños con OPTIMIZE

Spark SQL:

OPTIMIZE sales;

Usa el mantenimiento de tablas cuando escrituras o merges repetidos hayan creado muchos archivos pequeños y el rendimiento de lectura se vea afectado.

OPTIMIZE reescribe los archivos de datos.

Prográmalo de forma deliberada en lugar de ejecutarlo después de cada escritura.


28. Usar Z-Order solo para un patrón de acceso real

Ejemplo:

OPTIMIZE sales
ZORDER BY
(
    merchant_id,
    sale_date
);

Usa Z-Order cuando las consultas filtren repetidamente por determinadas columnas y la tabla sea lo bastante grande como para que el salto de archivos (file skipping) y las mejoras de organización importen.

No apliques Z-Order a todas las columnas.

El mantenimiento tiene un costo de cómputo y de escritura.


29. Entender V-Order en Fabric

V-Order es una optimización de Fabric que se aplica en la escritura y afecta a la organización de los archivos Parquet.

Puede mejorar las lecturas en todos los motores de Fabric, sobre todo en cargas analíticas con mucha lectura, a cambio de un trabajo de escritura adicional.

El comportamiento actual de Fabric depende de la configuración del workspace y del runtime; los workspaces más recientes no tienen V-Order habilitado por defecto en todos los casos.

Comprueba tu carga de trabajo y tu runtime reales en lugar de suponer que está activado.

Usa V-Order cuando el rendimiento de lectura de los consumidores de Fabric justifique el compromiso en la escritura.


30. Inspeccionar la configuración de optimización de Fabric antes de cambiarla

Ejemplos:

keys = [
    "spark.sql.parquet.vorder.enabled",
    "spark.sql.parquet.vorder.default",
    "spark.databricks.delta.optimizeWrite.enabled",
]

for key in keys:
    try:
        print(
            key,
            spark.conf.get(key),
        )
    except Exception:
        print(
            key,
            "<not available>",
        )

Los nombres y la disponibilidad de los parámetros de configuración pueden depender del runtime de Fabric.

No copies recetas de ajuste antiguas sin comprobar el runtime activo.


31. Usar VACUUM para limpiar el almacenamiento, no para ajustar consultas

Estándar:

VACUUM sales;

Retención explícita:

VACUUM sales RETAIN 168 HOURS;

VACUUM elimina de forma permanente los archivos de datos antiguos sin referencias que superan el umbral de retención.

Es principalmente una operación de limpieza del almacenamiento.

No es lo mismo que OPTIMIZE.


32. Usar VACUUM LITE solo en runtimes de Fabric compatibles

Fabric Spark Runtime 2.0 / Delta 4.1 y versiones posteriores admiten VACUUM LITE.

Ejemplo:

VACUUM sales LITE RETAIN 168 HOURS;

o bien:

from delta.tables import DeltaTable

table = DeltaTable.forName(
    spark,
    "sales",
)

table.vacuum(
    168,
    mode="LITE",
)

VACUUM LITE usa la información del registro de Delta en lugar de un listado completo de directorios.

Si no hay suficiente historial disponible en el registro de Delta, puede fallar y requerir un vacuum estándar (completo).

Comprueba que el runtime lo admite antes de usarlo.


33. No reducir la retención de VACUUM a la ligera

Una retención corta puede eliminar archivos necesarios para:

  • time travel (viaje en el tiempo)
  • lectores de larga duración
  • recuperación operativa
  • investigación de reversiones

No desactives las comprobaciones de seguridad de la retención en el código de producción habitual.

Si de verdad necesitas una retención más corta, trátala como una decisión operativa con consecuencias conocidas.


34. Leer una versión anterior de Delta para investigar

Time travel por versión:

previous = (
    spark.read
    .format("delta")
    .option(
        "versionAsOf",
        42,
    )
    .table("sales")
)

Por marca de tiempo:

previous = (
    spark.read
    .format("delta")
    .option(
        "timestampAsOf",
        "2026-10-03T12:00:00Z",
    )
    .table("sales")
)

Usa time travel para:

  • depuración
  • comparación
  • análisis de recuperación

La disponibilidad depende del historial de transacciones y de los archivos de datos que se conserven.

VACUUM puede eliminar de forma permanente archivos que necesitan las versiones anteriores.


35. Inspeccionar el historial de Delta

DESCRIBE HISTORY sales;

Usa el historial para investigar:

  • escrituras
  • merges
  • sobrescrituras
  • operaciones de mantenimiento
  • marcas de tiempo
  • metadatos de las operaciones

Suele ser el primer lugar que hay que revisar cuando una tabla ha cambiado de forma inesperada.


36. Comparar recuentos antes y después de las escrituras

Antes:

source_count = source.count()

Después:

target_count = (
    spark.table("sales")
    .count()
)

El recuento de filas por sí solo rara vez demuestra que el resultado sea correcto, pero es una señal de conciliación útil.

En cargas de producción, valida también:

  • claves de negocio distintas
  • recuentos de nulos
  • identificadores de lote
  • importes agregados
  • rango de fechas afectado

37. Conciliar las claves de negocio después de un upsert

duplicate_target_keys = (
    spark.table("sales")
    .groupBy("sale_id")
    .count()
    .filter(
        F.col("count") > 1
    )
)

duplicate_target_keys.show(
    50,
    truncate=False,
)

Si el contrato del destino establece que sale_id es único, las filas duplicadas son un problema de corrección, independientemente de que la transacción de Delta en sí haya tenido éxito.

Delta ofrece transaccionalidad a nivel de archivo y de tabla, no restricciones automáticas de unicidad de claves de negocio para escrituras arbitrarias de Spark.


38. Guardar metadatos de ejecución para las cargas incrementales

Columnas de ejemplo:

output = (
    source
    .withColumn(
        "pipeline_run_id",
        F.lit(run_id),
    )
    .withColumn(
        "ingested_at_utc",
        F.current_timestamp(),
    )
)

Esto mejora:

  • la trazabilidad
  • la investigación de duplicados
  • el análisis de reprocesamientos
  • las decisiones de reversión

Evita incluir secretos o datos operativos sensibles en las columnas de metadatos.


39. Evitar leer y reescribir todo el destino para un cambio incremental pequeño

Patrón deficiente:

target = spark.table("sales")
combined = target.unionByName(source)
# dedupe everything
# overwrite whole table

Mejor:

origen incremental pequeño
→ deduplicar el origen
→ MERGE en el destino

Usa operaciones incrementales específicas siempre que sea práctico.

Las reescrituras completas de tablas generan sin necesidad:

  • E/S
  • shuffle
  • archivos obsoletos
  • trabajo de mantenimiento
  • exposición a la concurrencia

40. Mantener la ingesta bruta como solo anexado cuando sea posible

Una arquitectura robusta es:

Bronze
  eventos/archivos de origen de solo anexado

Silver
  MERGE / deduplicación / lógica de corrección

Gold
  tablas curadas listas para consumo

Así se conserva el historial del origen y, al mismo tiempo, se permiten transformaciones con estado controladas en las capas posteriores.

No modifiques repetidamente tablas brutas alineadas con el origen, salvo que el contrato del origen realmente lo requiera.

Qué significa el resultado

Patrón Uso más adecuado
append Filas nuevas inmutables
overwrite Reconstrucción completa intencionada
MERGE Upsert / conciliación incremental
staging + MERGE Ingesta concurrente en un destino compartido
particionamiento Poda, ciclo de vida o aislamiento entre escritores
OPTIMIZE Compactar/reorganizar archivos para lecturas más eficientes
Z-Order Mejorar el salto de archivos para filtros selectivos repetidos
V-Order Optimización de la organización Parquet de Fabric para consumidores con mucha lectura
VACUUM Eliminar de forma permanente los archivos antiguos sin referencias
time travel Investigar/leer versiones históricas de la tabla
DESCRIBE HISTORY Auditar las operaciones de Delta

La distinción importante es:

escritura correcta a nivel transaccional
!=
escritura correcta a nivel de negocio

Aun así, debes validar:

  • las claves de negocio
  • los recuentos de filas
  • los duplicados
  • los agregados
  • la ventana de carga

Qué revisar

El recuento de filas del destino crece con cada reejecución

Probablemente tu carga no es idempotente.

Revisa:

  • el reprocesamiento de appends
  • la falta de coincidencia por clave de negocio
  • identificadores de lote inestables

MERGE toca muchos más datos de lo esperado

Revisa:

  • la selectividad de la condición de merge
  • la poda de particiones
  • la organización de los datos
  • el tamaño del origen
  • la organización de los archivos del destino

Un merge correcto pero demasiado amplio puede seguir siendo costoso.

Los trabajos concurrentes fallan durante las escrituras

Comprueba si los escritores:

  • modifican archivos o particiones del destino que se solapan
  • ejecutan merges en conflicto
  • realizan mantenimiento durante la ingesta

Considera:

  • append en staging
  • aislamiento entre escritores
  • conciliación serializada
  • reintentos específicos

La tabla tiene muchos archivos pequeños

Causas probables:

  • appends pequeños y frecuentes
  • demasiadas particiones de escritura
  • efectos secundarios de low shuffle merge
  • patrones de microlotes

Mide el impacto y después considera el mantenimiento de la tabla.

Las lecturas se ralentizan después de muchas actualizaciones o merges

Inspecciona:

  • el número de archivos
  • el tamaño de los archivos
  • la organización
  • los vectores de eliminación (deletion vectors) y el comportamiento del runtime
  • la necesidad de OPTIMIZE
  • las columnas filtradas con frecuencia

Las versiones antiguas de la tabla dejan de funcionar

Comprueba si VACUUM eliminó archivos históricos necesarios.

Los metadatos del registro de Delta no pueden restaurar por sí solos archivos que se eliminaron de forma permanente.

Notas de producción

Delta ofrece transacciones ACID sobre la tabla, no restricciones de negocio arbitrarias

Delta protege los commits de la tabla frente a escrituras parciales.

No aplica automáticamente:

  • unicidad
  • integridad referencial
  • la semántica de una fila por clave de negocio

Valídalas tú mismo.

Low Shuffle Merge de Fabric ya está activado por defecto

No pierdas tiempo «optimizando» al activarlo, salvo que estés diagnosticando una diferencia de configuración o probando un comportamiento.

Céntrate primero en el tamaño del origen, las claves de merge, los archivos afectados y el sesgo (skew).

Las escrituras concurrentes requieren un diseño que tenga en cuenta la organización de los datos

Delta usa control de concurrencia optimista.

Los appends independientes son menos propensos a conflictos que las actualizaciones o merges que se solapan.

Para alta concurrencia:

staging de solo anexado
→ conciliación centralizada

suele ser más fácil de operar.

OPTIMIZE y VACUUM resuelven problemas diferentes

OPTIMIZE
→ reescribe/compacta/reorganiza los archivos actuales

VACUUM
→ elimina los archivos antiguos sin referencias

No uses uno como sustituto del otro.

VACUUM afecta a la capacidad de recuperación

Una vez eliminados los archivos obsoletos, las versiones históricas que los necesitan dejan de poder leerse.

La retención es una decisión de recuperación operativa, no solo un ajuste de costo de almacenamiento.

Los valores predeterminados de V-Order han cambiado con el tiempo

Los valores predeterminados de los workspaces y runtimes de Fabric han cambiado.

No supongas que las recomendaciones escritas para workspaces de Fabric más antiguos se ajustan a un runtime actual.

Inspecciona la configuración real.

Mantén el mantenimiento de tablas fuera de las ventanas de escritura pico cuando sea práctico

OPTIMIZE, VACUUM y los merges pesados consumen recursos y pueden interferir con las cargas de escritura concurrentes.

Programa el mantenimiento cuando minimice la contención operativa.

El particionamiento no es obligatorio

No copies automáticamente patrones de particionamiento de estilo Hive.

Delta puede rendir bien sin particionamiento físico en muchas cargas de trabajo.

Particiona solo cuando el tamaño de los datos y el patrón de acceso y escritura lo justifiquen.

Errores comunes

1. Usar append para un feed modificable que puede reprocesarse

Una reejecución puede crear duplicados.

Usa una estrategia de idempotencia duradera.

2. Usar overwrite en cada reejecución

Esto convierte pequeños cambios incrementales en costosas reescrituras completas de la tabla.

3. Usar whenMatchedUpdateAll() sin pensar en el esquema

Columnas del origen añadidas por comodidad pueden pasar a formar parte del contrato del destino sin querer.

Usa asignaciones explícitas cuando la estabilidad importe.

4. Hacer merge con claves duplicadas en el origen

El origen entrante debe tener una semántica de clave de negocio determinista.

Deduplica de forma intencionada antes del merge.

5. Particionar por un identificador de alta cardinalidad

Esto crea demasiados directorios y archivos diminutos y un mal comportamiento operativo.

6. Llamar a repartition(1) antes de cada escritura

Una sola partición de salida es un cuello de botella, no una optimización.

7. Ejecutar VACUUM para que las consultas sean más rápidas

VACUUM sirve principalmente para limpiar el almacenamiento.

Usa OPTIMIZE y el ajuste de la organización de los datos para mejorar el rendimiento de lectura.

8. Reducir la retención de VACUUM sin entender el time travel

Los archivos eliminados ya no pueden usarse después para las versiones históricas.

9. Tratar una transacción Delta correcta como prueba de que las métricas son correctas

Una transacción puede ser perfectamente válida aunque la clave de negocio o la lógica del origen sean incorrectas.

Concilia los datos.

10. Reintentar todas las excepciones de escritura

Reintenta solo los errores que sean realmente transitorios o relacionados con conflictos.

Un esquema incorrecto o una lógica de merge errónea deben fallar de forma visible.

Siguiente paso

Usa el patrón de escritura para elegir la siguiente acción.

  • Solo eventos nuevos inmutables → usa append y añade controles de reprocesamiento y de lote.
  • Las reejecuciones crean duplicados → implementa idempotencia basada en claves o MERGE.
  • Las filas existentes pueden cambiar → usa MERGE con una verdadera clave de negocio.
  • El origen contiene claves duplicadas → deduplica con un orden determinista antes de escribir.
  • Los escritores concurrentes entran en conflicto → haz append en staging y concilia con un merge controlado.
  • El merge escanea demasiados datos del destino → mejora la selectividad del merge, la estrategia de particionamiento y organización, y el filtrado del origen.
  • La tabla tiene muchos archivos pequeños → revisa el particionamiento de escritura y después considera OPTIMIZE.
  • El almacenamiento sigue creciendo tras actualizaciones o merges → revisa una retención segura de VACUUM.
  • Se necesitan versiones antiguas para la recuperación → protege la retención antes de ejecutar vacuum.
  • Las lecturas siguen siendo lentas con patrones de escritura correctos → pasa a Rendimiento de los notebooks de Fabric y al análisis de la organización de las tablas.

← Todas las guías rápidas