Explorar guías rápidas · PySpark
Leer y escribir tablas Delta
Lee y escribe tablas Delta con PySpark usando patrones seguros de append, overwrite, merge, evolución del esquema, particionamiento y mantenimiento para pipelines de datos en producción.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Leer una tabla Delta registrada
- 2. Leer una tabla Delta por ruta
- 3. Leer solo las columnas necesarias
- 4. Filtrar lo antes posible
- 5. Anexar filas inmutables
- 6. Añadir metadatos de lote antes del append
- 7. Sobrescribir una tabla completa de forma intencionada
- 8. Sobrescribir con reemplazo del esquema solo de forma deliberada
- 9. Añadir columnas compatibles con la evolución del esquema
- 10. Hacer upsert con MERGE
- 11. Preferir asignaciones explícitas de actualización/inserción para contratos estables
- 12. Deduplicar las filas de origen antes del merge
- 13. Validar la unicidad del origen
- 14. Hacer merge con claves de negocio compuestas
- 15. Actualizar solo cuando el origen sea más reciente
- 16. Insertar solo las claves que faltan
- 17. Gestionar de forma explícita las eliminaciones que vienen del origen
- 18. Usar MERGE en SQL cuando sea más claro
- 19. Leer el historial de la tabla
- 20. Leer una versión anterior de Delta
- 21. Leer la tabla en una marca de tiempo concreta
- 22. Validar la granularidad del destino después de las escrituras
- 23. Conciliar recuentos de filas
- 24. Conciliar totales de negocio
- 25. Particionar una tabla cuando el patrón de acceso lo justifique
- 26. Evitar el sobreparticionamiento
- 27. Evitar repartition(1) antes de escribir en Delta
- 28. Reducir con cuidado las particiones de salida
- 29. Compactar archivos pequeños con OPTIMIZE
- 30. Usar Z-Order para patrones de acceso selectivos repetidos
- 31. Usar VACUUM para limpiar el almacenamiento
- 32. No reducir la retención a la ligera
- 33. Usar staging para productores concurrentes
- 34. Reintentar solo los conflictos de concurrencia que entiendas
- 35. Inspeccionar la configuración de low shuffle merge cuando sea relevante
- 36. Evitar reescribir toda la tabla para un cambio incremental pequeño
- 37. Mantener Bronze como solo anexado cuando sea posible
- 38. Hacer que las reejecuciones sean seguras
- 39. Registrar metadatos de escritura
- 40. Inspeccionar el plan antes de escrituras costosas
- Qué significa el resultado
- Qué revisar
- El destino crece con cada reejecución
- El merge es más lento de lo esperado
- El merge falla de forma intermitente con concurrencia
- Las lecturas se ralentizan después de muchas actualizaciones
- Las versiones antiguas dejan de funcionar
- El esquema de la tabla cambia de forma inesperada
- Notas de producción
- Delta ofrece transacciones ACID a nivel de tabla
- La idempotencia es responsabilidad de la aplicación
- El rendimiento del merge depende de cuántos datos del destino se toquen
- Las operaciones de mantenimiento consumen recursos
- El particionamiento es opcional
- La evolución del esquema debe estar gobernada
- Errores comunes
- 1. Hacer append a ciegas con datos que pueden reprocesarse
- 2. Usar overwrite en cada reejecución
- 3. Hacer merge con claves duplicadas en el origen
- 4. Usar updateAll() / insertAll() sin revisar el acoplamiento de esquemas
- 5. Particionar por claves de alta cardinalidad
- 6. Usar repartition(1) para la salida Delta de producción
- 7. Ejecutar VACUUM para mejorar la velocidad de las consultas
- 8. Reducir la retención sin planificar la recuperación
- 9. Tratar una escritura correcta como prueba de una granularidad correcta
- 10. Reintentar cada fallo de escritura
- Siguiente paso
- Para profundizar
Problema
Necesitas leer, anexar, sobrescribir o hacer upsert en tablas Delta desde PySpark sin introducir filas duplicadas, deriva del esquema, reescrituras completas accidentales ni un comportamiento inseguro al volver a ejecutar.
La sintaxis es sencilla.
Las decisiones de producción no lo son.
Tienes que responder:
- ¿Esta carga es de solo anexado o modificable?
- ¿Se puede reprocesar el mismo lote?
- ¿Cuál es la clave de negocio?
- ¿La tabla debe reconstruirse o actualizarse de forma incremental?
- ¿Pueden aparecer cambios de esquema automáticamente?
- ¿Habrá trabajos concurrentes escribiendo en el mismo destino?
- ¿La tabla está particionada de forma adecuada?
- ¿Cómo validarás la escritura?
El objetivo es que el patrón de escritura se ajuste al contrato de datos.
Respuesta rápida
Usa este modelo de decisión:
Leer una tabla Delta existente
→ spark.read.table(...) o format("delta").load(...)
Filas nuevas inmutables
→ append
Reconstrucción completa y determinista
→ overwrite
Insertar + actualizar claves existentes
→ MERGE
Origen que puede reprocesarse
→ MERGE idempotente o lógica de lote segura ante reprocesamientos
Productores concurrentes
→ append a staging y después conciliación en el destino
Leer una tabla registrada:
df = spark.read.table("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 overwrite como estrategia predeterminada de reejecución para datos de producción modificables.
Código / comandos
1. Leer una tabla Delta registrada
df = spark.read.table(
"sales"
)
Equivalente:
df = spark.sql(
"SELECT * FROM sales"
)
Usa nombres de tablas registradas cuando el contexto del catálogo/Lakehouse sea estable y claro.
2. Leer una tabla Delta por ruta
df = (
spark.read
.format("delta")
.load("Tables/sales")
)
Usa lecturas por ruta cuando la propia ruta forme parte del contrato.
Evita mezclar a la ligera el acceso por nombre y el acceso por ruta para la misma tabla.
3. Leer solo las columnas necesarias
df = (
spark.read.table("sales")
.select(
"sale_id",
"merchant_id",
"sale_date",
"amount",
)
)
La poda de columnas reduce la memoria en las etapas posteriores y el ancho del shuffle.
4. Filtrar lo antes posible
from pyspark.sql import functions as F
df = (
spark.read.table("sales")
.filter(
F.col("sale_date") >= "2026-10-01"
)
.select(
"sale_id",
"merchant_id",
"sale_date",
"amount",
)
)
Filtra pronto cuando eso no cambie la semántica de negocio prevista.
5. Anexar filas inmutables
(
new_rows.write
.format("delta")
.mode("append")
.saveAsTable("sales")
)
Usa append cuando:
- las filas sean nuevas
- las filas existentes no deban cambiar
- la gestión del reprocesamiento ya esté diseñada
Append no es idempotente automáticamente.
6. Añadir metadatos de lote antes del append
output = (
new_rows
.withColumn(
"_batch_id",
F.lit(batch_id),
)
.withColumn(
"_ingested_at_utc",
F.current_timestamp(),
)
)
Esto ayuda con:
- la detección de reprocesamientos
- el linaje
- la investigación de incidentes
Por sí solo no evita los duplicados.
7. Sobrescribir una tabla completa de forma intencionada
(
rebuilt.write
.format("delta")
.mode("overwrite")
.saveAsTable("sales_summary")
)
Úsalo solo cuando el reemplazo completo sea realmente el contrato de la tabla.
Ejemplos:
- dimensiones pequeñas y deterministas
- resúmenes que se pueden reconstruir
- recargas históricas (backfills) controladas
8. Sobrescribir con reemplazo del esquema solo de forma deliberada
(
rebuilt.write
.format("delta")
.mode("overwrite")
.option(
"overwriteSchema",
"true",
)
.saveAsTable("sales_summary")
)
Esto puede cambiar el esquema del destino.
No lo actives de forma global.
9. Añadir columnas compatibles con la evolución del esquema
(
new_rows.write
.format("delta")
.mode("append")
.option(
"mergeSchema",
"true",
)
.saveAsTable("sales")
)
Úsalo solo cuando la evolución del esquema sea una política operativa aceptada.
No lo uses para ocultar una deriva del esquema no controlada en el origen.
10. Hacer upsert con MERGE
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()
)
Úsalo cuando las filas entrantes puedan actualizar claves de negocio existentes.
11. Preferir asignaciones explícitas de actualización/inserción para contratos estables
(
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()
)
Esto reduce el acoplamiento accidental entre los esquemas de origen y destino.
12. Deduplicar las filas de origen antes del merge
from pyspark.sql import Window
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")
)
Usa un orden determinista cuando varias filas de origen puedan apuntar a la misma clave.
13. Validar la unicidad del origen
duplicates = (
source
.groupBy("sale_id")
.count()
.filter(
F.col("count") > 1
)
)
Haz que falle si no se permiten duplicados:
if duplicates.limit(1).count() > 0:
raise RuntimeError(
"Duplicate sale_id values in merge source"
)
14. Hacer merge con claves de negocio compuestas
condition = """
t.member_id = s.member_id
AND t.merchant_id = s.merchant_id
AND t.site_id = s.site_id
"""
Después:
(
target.alias("t")
.merge(
source.alias("s"),
condition,
)
.whenMatchedUpdateAll()
.whenNotMatchedInsertAll()
.execute()
)
Usa la clave de negocio completa.
15. Actualizar solo cuando el origen 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()
)
Úsalo solo cuando updated_at sea lo bastante fiable para definir la precedencia entre versiones.
16. Insertar solo las claves que faltan
(
target.alias("t")
.merge(
source.alias("s"),
"t.sale_id = s.sale_id",
)
.whenNotMatchedInsertAll()
.execute()
)
Esto puede hacer que los lotes repetidos sean idempotentes por clave de negocio.
17. Gestionar de forma explícita las eliminaciones que vienen del origen
(
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()
)
Elimina solo cuando el contrato del origen indique explícitamente que la fila se ha eliminado.
Que una fila no aparezca en un lote incremental no demuestra que se haya eliminado.
18. Usar MERGE en SQL cuando 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
);
Elige la forma de API o de SQL que sea más fácil de revisar.
19. Leer el historial de la tabla
history = spark.sql(
"DESCRIBE HISTORY sales"
)
history.show(
truncate=False
)
Usa el historial para investigar:
- appends
- overwrites
- merges
- optimizaciones
- cambios operativos relacionados con VACUUM
- modificaciones inesperadas
20. Leer una versión anterior de Delta
older = (
spark.read
.format("delta")
.option(
"versionAsOf",
42,
)
.table("sales")
)
Úsalo para:
- depuración
- comparación
- análisis de recuperación
La disponibilidad depende del historial y de los archivos que se conserven.
21. Leer la tabla en una marca de tiempo concreta
older = (
spark.read
.format("delta")
.option(
"timestampAsOf",
"2026-10-03T12:00:00Z",
)
.table("sales")
)
Sé explícito con la semántica de zona horaria al comparar versiones históricas.
22. Validar la granularidad del destino después de las escrituras
Si sale_id debe ser único:
duplicates = (
spark.table("sales")
.groupBy("sale_id")
.count()
.filter(
F.col("count") > 1
)
)
Después:
if duplicates.limit(1).count() > 0:
raise RuntimeError(
"Target grain validation failed"
)
Una transacción Delta correcta no garantiza la unicidad de la clave de negocio.
23. Conciliar recuentos de filas
source_count = source.count()
target_count = (
spark.table("sales")
.count()
)
print(
"Source:",
source_count,
)
print(
"Target:",
target_count,
)
El recuento de filas por sí solo no demuestra que los datos sean correctos.
Úsalo junto con:
- claves de negocio distintas
- identificadores de lote
- recuentos de nulos
- totales de negocio
24. Conciliar totales de negocio
source_total = (
source
.agg(
F.sum("amount").alias("amount")
)
.first()["amount"]
)
Compáralo con el segmento adecuado del destino.
Usa tipos decimales exactos para los datos financieros siempre que sea práctico.
25. Particionar una tabla cuando el patrón de acceso lo justifique
(
df.write
.format("delta")
.mode("append")
.partitionBy(
"sale_year",
"sale_month",
)
.saveAsTable("sales")
)
El particionamiento puede ayudar con:
- la poda
- el aislamiento entre escritores
- la gestión del ciclo de vida
No particiones por identificadores de alta cardinalidad.
26. Evitar el sobreparticionamiento
Malos candidatos:
transaction_id
customer_id con millones de valores
marca de tiempo exacta
Demasiadas particiones pueden generar:
- muchos archivos pequeños
- sobrecarga de metadatos
- lecturas ineficientes
Particiona solo según patrones reales de acceso/escritura.
27. Evitar repartition(1) antes de escribir en Delta
Arriesgado:
(
df.repartition(1)
.write
.format("delta")
.mode("append")
.saveAsTable("sales")
)
Esto crea un único cuello de botella de escritura.
Se espera que las tablas Delta contengan varios archivos.
28. Reducir con cuidado las particiones de salida
Si la salida es pequeña:
small = df.coalesce(20)
Después:
(
small.write
.format("delta")
.mode("append")
.saveAsTable("sales_summary")
)
Mide primero.
Muy pocas particiones también pueden crear tareas sobredimensionadas y lentas.
29. Compactar archivos pequeños con OPTIMIZE
spark.sql(
"OPTIMIZE sales"
)
Úsalo cuando las escrituras repetidas creen muchos archivos pequeños y afecten al rendimiento de lectura.
No lo ejecutes por defecto después de cada escritura pequeña.
30. Usar Z-Order para patrones de acceso selectivos repetidos
spark.sql(
"""
OPTIMIZE sales
ZORDER BY (merchant_id, sale_date)
"""
)
Úsalo cuando las consultas filtren con frecuencia por esas columnas y la tabla sea lo bastante grande como para beneficiarse.
No apliques Z-Order a todas las columnas.
31. Usar VACUUM para limpiar el almacenamiento
spark.sql(
"VACUUM sales"
)
O con una retención explícita:
spark.sql(
"VACUUM sales RETAIN 168 HOURS"
)
VACUUM elimina los archivos antiguos sin referencias una vez superado el umbral de retención.
No sustituye a OPTIMIZE para el rendimiento de las consultas.
32. No reducir la retención a la ligera
Los archivos antiguos pueden seguir siendo necesarios para:
- time travel (viaje en el tiempo)
- lectores de larga duración
- recuperación ante incidentes
- análisis de reversiones
Una vez eliminados, desaparecen.
Trata la retención como una decisión operativa de recuperación.
33. Usar staging para productores concurrentes
Un patrón más seguro:
- Productor A
- Productor B
- Productor C
- Delta de staging
- Merge controlado
- Delta de destino
Esto reduce el solapamiento entre escritores independientes.
34. Reintentar solo los conflictos de concurrencia que entiendas
Patrón conceptual:
import time
for attempt in range(3):
try:
run_merge()
break
except Exception as exc:
if not is_expected_delta_conflict(exc):
raise
if attempt == 2:
raise
time.sleep(2 ** attempt)
No reintentes:
- errores de esquema
- datos incorrectos
- lógica de merge no válida
- fallos de permisos
35. Inspeccionar la configuración de low shuffle merge cuando sea relevante
En plataformas/runtimes que lo admitan:
print(
spark.conf.get(
"spark.microsoft.delta.merge.lowShuffle.enabled"
)
)
No trates la configuración de optimización del runtime como sustituto de unas claves de merge correctas y una buena organización de los datos.
36. Evitar reescribir toda la tabla para un cambio incremental pequeño
Patrón deficiente:
target = spark.table("sales")
combined = (
target
.unionByName(source)
)
# global dedupe
# full overwrite
Mejor:
origen incremental
→ deduplicación determinista
→ MERGE específico
Usa reconstrucciones completas solo cuando sean realmente adecuadas.
37. Mantener Bronze como solo anexado cuando sea posible
Un patrón habitual:
Bronze
→ append del historial bruto del origen
Silver
→ MERGE del estado actual
Gold
→ capa de consumo curada
Así se conserva la capacidad de reprocesamiento y se simplifica la recuperación ante incidentes.
38. Hacer que las reejecuciones sean seguras
Antes de permitir reejecuciones, decide:
¿Qué pasa si el mismo lote se ejecuta dos veces?
Entre los buenos patrones están:
MERGE por clave de negocio
protección contra el reprocesamiento de lotes
reemplazo de particiones
staging + promoción
Mala opción predeterminada:
append a ciegas
para feeds modificables que pueden reprocesarse.
39. Registrar metadatos de escritura
Campos útiles:
pipeline_run_id
batch_id
source_system
ingested_at_utc
source_modified_at
Ejemplo:
output = (
output
.withColumn(
"_pipeline_run_id",
F.lit(pipeline_run_id),
)
.withColumn(
"_batch_id",
F.lit(batch_id),
)
.withColumn(
"_ingested_at_utc",
F.current_timestamp(),
)
)
Mantén los metadatos operativos seguros y sin información sensible.
40. Inspeccionar el plan antes de escrituras costosas
output.explain("formatted")
Antes de una escritura grande, confirma que la transformación no está haciendo por accidente:
- un shuffle innecesario
- un cross join
- escaneos repetidos
- una ordenación global enorme
- una UDF de Python costosa
El ajuste de la escritura no puede arreglar un mal plan previo.
Qué significa el resultado
| Patrón | Úsalo cuando |
|---|---|
read.table() |
Tabla Delta registrada |
format("delta").load() |
Ruta Delta explícita |
| append | Filas nuevas inmutables |
| overwrite | Reconstrucción completa intencionada |
MERGE |
Upsert / conciliación incremental |
mergeSchema |
Evolución aditiva y controlada del esquema |
overwriteSchema |
Reemplazo intencionado del esquema |
OPTIMIZE |
Compactar/reorganizar los archivos de datos activos |
| Z-Order | Mejorar el salto de archivos para filtros repetidos |
VACUUM |
Eliminar archivos antiguos sin referencias |
| time travel | Leer el estado histórico de la tabla |
| staging + merge | Patrón más seguro para productores concurrentes |
La distinción clave es:
transacción Delta correcta
!=
corrección a nivel de negocio
Valida el contrato de datos resultante.
Qué revisar
El destino crece con cada reejecución
Causa probable:
- append a ciegas
- falta de protección contra reprocesamientos
- clave de negocio incorrecta
El merge es más lento de lo esperado
Revisa:
- el tamaño del origen
- la selectividad de la condición de merge
- la organización del destino
- la poda de particiones
- el número de archivos
- el sesgo de datos (skew)
El merge falla de forma intermitente con concurrencia
Revisa los escritores que se solapan y el solapamiento de archivos del destino.
Considera staging + merge controlado.
Las lecturas se ralentizan después de muchas actualizaciones
Revisa:
- la acumulación de archivos pequeños
- la organización
- la necesidad de
OPTIMIZE
Las versiones antiguas dejan de funcionar
Comprueba si la retención/VACUUM eliminó archivos antiguos.
El esquema de la tabla cambia de forma inesperada
Revisa:
mergeSchema- la deriva del origen
- el comportamiento de sobrescritura del esquema
- los cambios de despliegue
Notas de producción
Delta ofrece transacciones ACID a nivel de tabla
Esto protege la integridad de los commits.
No impone automáticamente:
- unicidad
- claves foráneas
- reglas de una fila por clave de negocio
Valídalas tú mismo.
La idempotencia es responsabilidad de la aplicación
Una escritura Delta puede ser válida a nivel transaccional y aun así duplicar datos al volver a ejecutarse.
Diseña de forma deliberada el comportamiento ante reprocesamientos.
El rendimiento del merge depende de cuántos datos del destino se toquen
Un origen muy pequeño puede provocar igualmente un trabajo costoso en el destino si la condición de merge o la organización de los datos es demasiado amplia.
Las operaciones de mantenimiento consumen recursos
OPTIMIZE y VACUUM deben programarse de forma intencionada.
No los ejecutes a ciegas después de cada escritura.
El particionamiento es opcional
No des por hecho que toda tabla Delta necesita particionamiento físico.
Úsalo solo cuando ayude con:
- la poda
- el ciclo de vida
- el aislamiento entre escritores
La evolución del esquema debe estar gobernada
El crecimiento automático del esquema puede ser cómodo, pero también puede romper a los consumidores.
Trata el esquema como un contrato.
Errores comunes
1. Hacer append a ciegas con datos que pueden reprocesarse
Esto genera duplicados.
2. Usar overwrite en cada reejecución
Esto convierte pequeñas actualizaciones incrementales en reescrituras completas costosas.
3. Hacer merge con claves duplicadas en el origen
Deduplica primero de forma determinista.
4. Usar updateAll() / insertAll() sin revisar el acoplamiento de esquemas
Lo que hoy es cómodo puede volverse frágil mañana.
5. Particionar por claves de alta cardinalidad
Esto produce muchas particiones/archivos pequeños.
6. Usar repartition(1) para la salida Delta de producción
Esto crea un cuello de botella de una sola tarea.
7. Ejecutar VACUUM para mejorar la velocidad de las consultas
Usa OPTIMIZE y el ajuste de la organización de los datos para el rendimiento de lectura.
8. Reducir la retención sin planificar la recuperación
Puedes perder la posibilidad de usar time travel.
9. Tratar una escritura correcta como prueba de una granularidad correcta
Valida las claves de negocio y los totales.
10. Reintentar cada fallo de escritura
Reintenta solo los fallos transitorios o de concurrencia que entiendas.
¿Te resultó útil este contenido?
¿Qué podríamos mejorar?
Gracias — esto me ayuda a mejorar Javi Builds.
Mantente al día
Recibe solo las novedades de Javi Builds que realmente te interesan.
Revisa tu bandeja de entrada
Te he enviado un enlace de confirmación. Tu suscripción se activará cuando la confirmes.