Explorar guías rápidas · Ingeniería de datos
Patrones de carga incremental
Diseña cargas incrementales seguras con watermarks, CDC, high-water marks, MERGE, escrituras idempotentes, gestión de datos tardíos y checkpoints reproducibles, sin omitir ni duplicar datos.
En esta página
- Problema
- Respuesta rápida
- Código / comandos
- 1. Referencia: la recarga completa
- 2. High-water mark con un ID creciente
- 3. No supongas que cualquier ID es un high-water mark válido
- 4. Watermark por marca de tiempo
- 5. Marca de tiempo + criterio de desempate único
- 6. El criterio de desempate debe coincidir con el orden de clasificación
- 7. No uses MAX(updated_at) por sí solo sin pensar en los empates
- 8. Ventanas de lote semiabiertas
- 9. Las ventanas semiabiertas no resuelven las llegadas tardías
- 10. Ventanas de solapamiento para llegadas tardías
- 11. Ejemplo de solapamiento deslizante
- 12. Persiste el checkpoint después del éxito
- 13. El checkpoint debe describir el alcance completado
- 14. Mantén el estado del checkpoint de forma duradera
- 15. Usa un checkpoint por flujo lógico
- 16. Carga incremental con manifiesto de archivos
- 17. El nombre de archivo por sí solo puede no demostrar unicidad
- 18. Particionar por ruta de archivo puede simplificar el descubrimiento incremental
- 19. Patrón CDC
- 20. CDC no implica automáticamente streaming
- 21. Usa la secuencia, el LSN o la versión nativos del origen cuando estén disponibles
- 22. No conviertas un checkpoint nativo del origen en una marca de tiempo menos fiable
- 23. Patrón de comparación de snapshots (snapshot diff)
- 24. Patrón de comparación por hash (hash-diff)
- 25. Calcula el hash solo sobre columnas relevantes
- 26. Normaliza los valores antes de calcular el hash
- 27. MERGE para inserciones y actualizaciones
- 28. Usa asignaciones explícitas para un MERGE controlado
- 29. Actualiza solo cuando el origen sea más reciente
- 30. Valida la unicidad del origen del MERGE
- 31. Deduplica la entrada incremental de forma determinista
- 32. Anexado incremental para eventos inmutables
- 33. El anexado también necesita una estrategia contra duplicados
- 34. Las eliminaciones requieren un diseño explícito
- 35. Patrón de eliminación lógica (soft delete)
- 36. Evita conciliar eliminaciones entre origen y destino con extracciones parciales del origen
- 37. La conciliación de snapshots puede detectar eliminaciones
- 38. Sobrescritura incremental de particiones
- 39. No sobrescribas toda la tabla por el cambio de una sola partición
- 40. Las cargas incrementales necesitan idempotencia
- 41. Los trabajos de solo anexado necesitan protección contra duplicados en los reintentos
- 42. MERGE no es automáticamente idempotente
- 43. Gestiona con cuidado los reintentos y el checkpoint
- 44. Una mentalidad parecida al commit en dos fases
- 45. Persiste los metadatos de los lotes
- 46. Concilia el número de filas
- 47. Concilia también los totales de negocio
- 48. No avances nunca el checkpoint si fallan controles de calidad bloqueantes
- 49. Separa los controles de calidad de advertencia de los bloqueantes
- 50. Patrón para datos que llegan tarde
- 51. El backfill no debe corromper el checkpoint en producción
- 52. El backfill debe ser explícito
- 53. El backfill puede reutilizar la misma lógica de transformación
- 54. Protégete del solapamiento de escrituras de producción y de backfill
- 55. Staging antes del MERGE
- 56. Asigna un ID de lote a los datos de staging
- 57. No vacíes a la ligera un staging compartido
- 58. Las actualizaciones del origen pueden llegar desordenadas
- 59. La hora de ingesta no indica la actualidad en el origen
- 60. El orden de las actualizaciones de CDC importa
- 61. Las lecturas incrementales por hora del evento son arriesgadas para entidades mutables
- 62. Un watermark por fecha de creación encaja con entidades de solo anexado
- 63. Usa la hora de commit del origen cuando esté disponible
- 64. El desfase de relojes puede romper los watermarks por marca de tiempo
- 65. Evita usar current_timestamp() como watermark del origen
- 66. Fija el corte del lote antes de leer el origen
- 67. Usa cortes con retraso cuando los commits del origen se asientan tarde
- 68. Paginación y carga incremental son cosas distintas
- 69. Conserva el cursor de paginación hasta completar la extracción acotada
- 70. Ejemplo de extracción incremental desde una API
- 71. Los cursores de API pueden caducar
- 72. Los límites de tasa afectan al diseño de la carga incremental
- 73. La carga incremental debe poder reanudarse
- 74. Persiste el alcance del fallo
- 75. No edites los checkpoints manualmente a la ligera
- 76. Reparar un checkpoint es un cambio en producción
- 77. Las cargas incrementales necesitan observabilidad
- 78. Que de repente no haya cambios puede ser sospechoso
- 79. Un volumen de cambios repentinamente enorme puede ser sospechoso
- 80. Monotonía del checkpoint
- 81. Mantén el alcance del checkpoint alineado con el filtro del origen
- 82. La deriva del esquema puede romper las cargas incrementales en silencio
- 83. Cambiar el campo de watermark es una migración
- 84. Cambiar la clave del MERGE es peligroso
- 85. La lógica incremental debe ser determinista
- 86. Patrón incremental SCD Type 1
- 87. Patrón incremental SCD Type 2
- 88. SCD Type 2 requiere disciplina con duplicados y versiones
- 89. Las cargas de hechos por snapshot pueden usar el reemplazo de particiones
- 90. Las cargas de hechos de auditoría suelen usar anexado
- 91. Separa el checkpoint de ingesta del checkpoint de transformación cuando sea necesario
- 92. Los checkpoints por capa pueden mejorar la recuperación
- 93. El avance del checkpoint forma parte de la frescura de los datos
- 94. Las lecturas incrementales deben estar acotadas siempre que sea posible
- 95. La extracción acotada permite reintentos reproducibles
- 96. Debe existir una estrategia de reconstrucción
- 97. Lo incremental es una optimización, no la fuente de verdad
- 98. Prueba los escenarios de fallo
- 99. Usa una lista de verificación de implementación repetible
- Qué significa el resultado
- Qué revisar
- Faltan filas tras un reinicio
- Aparecen filas duplicadas
- Valores antiguos sobrescriben otros más recientes
- Las eliminaciones nunca llegan al destino
- El trabajo incremental de repente lo lee todo
- El trabajo lee cero filas inesperadamente
- Notas de producción
- Los checkpoints son datos de producción
- La idempotencia es lo que hace seguros los reintentos
- Las marcas de tiempo del origen no siempre son fiables
- Los datos tardíos son normales en los sistemas distribuidos
- Las eliminaciones necesitan una semántica explícita
- Los backfills forman parte de la arquitectura
- Errores comunes
- 1. Usar MAX(updated_at) como único checkpoint
- 2. Avanzar el checkpoint antes de que la escritura tenga éxito
- 3. Suponer que MERGE hace seguro cualquier reintento
- 4. Usar la fecha de creación para registros mutables
- 5. Ignorar las eliminaciones
- 6. Tratar la hora de ingesta como versión del origen
- 7. Editar manualmente los watermarks sin un plan de reproducción
- 8. Dejar que los backfills modifiquen los checkpoints de producción
- 9. Usar solo el nombre de archivo como identidad de procesamiento
- 10. No tener un alcance acotado para los reintentos
- Siguiente paso
- Para profundizar
Problema
Una recarga completa se está volviendo demasiado cara, demasiado lenta o demasiado disruptiva, así que el pipeline debe procesar solo los datos nuevos o modificados.
Lo difícil no es leer menos filas.
Los verdaderos problemas de ingeniería son:
- elegir un límite de cambio fiable
- evitar que se omitan registros
- evitar cargas duplicadas
- gestionar empates de marcas de tiempo
- gestionar actualizaciones y eliminaciones
- recuperarse tras un fallo
- admitir datos que llegan tarde
- coordinar reintentos y recargas históricas (backfills)
- mantener coherente el estado del origen y del destino
El objetivo es que el límite incremental sea explícito, duradero y reproducible.
Respuesta rápida
Elige el patrón según lo que el origen pueda proporcionar de forma fiable:
El origen tiene un ID creciente inmutable
→ high-water mark
El origen tiene una marca de tiempo updated_at fiable
→ watermark por marca de tiempo + desempate determinista
El origen expone CDC/un feed de cambios
→ consumir los registros de cambio con un checkpoint duradero
El origen entrega archivos
→ manifiesto de archivos / checkpoint por lote
El origen solo puede devolver snapshots completos
→ comparación de snapshots / hash-diff / MERGE vía staging
El destino necesita inserciones + actualizaciones
→ MERGE / upsert
Las eliminaciones deben propagarse
→ tombstones de CDC o conciliación explícita origen-destino
La regla más importante:
avanzar el checkpoint solo después
de que la escritura en el destino y la validación requerida tengan éxito
Código / comandos
1. Referencia: la recarga completa
Antes de introducir la complejidad de lo incremental, comprueba si una reconstrucción completa sigue siendo viable.
Patrón conceptual:
leer todo el origen
→ transformar
→ validar
→ reemplazar el destino
La recarga completa suele ser más sencilla y fiable para:
- conjuntos de datos pequeños
- dimensiones que crecen lentamente
- trabajos poco frecuentes
- tablas Gold reconstruibles
No implementes lógica de CDC ni de watermark cuando una reconstrucción completa segura sea barata.
2. High-water mark con un ID creciente
Supón que el origen garantiza una clave creciente e inmutable:
order_event_id
Persiste:
last_successful_id = 450000
Consulta siguiente:
SELECT
order_event_id,
order_id,
event_type,
event_time
FROM source_order_events
WHERE order_event_id > @last_successful_id
ORDER BY order_event_id;
Tras un procesamiento correcto:
last_successful_id = max(order_event_id procesados)
Es sencillo y robusto cuando el origen garantiza de verdad ID monótonos.
3. No supongas que cualquier ID es un high-water mark válido
Una clave puede ser única sin estar ordenada.
Ejemplos:
UUID aleatorio
GUID
hash
referencia externa
No uses:
id > last_id
a menos que el origen garantice un orden significativo.
4. Watermark por marca de tiempo
Patrón habitual:
SELECT
order_id,
updated_at,
amount,
status
FROM source_orders
WHERE updated_at > @last_watermark;
Parece sencillo, pero puede omitir filas cuando varios registros comparten la misma marca de tiempo.
Usa un criterio de desempate.
5. Marca de tiempo + criterio de desempate único
Persiste:
last_updated_at
last_order_id
Consulta:
SELECT
order_id,
updated_at,
amount,
status
FROM source_orders
WHERE
updated_at > @last_updated_at
OR (
updated_at = @last_updated_at
AND order_id > @last_order_id
)
ORDER BY
updated_at,
order_id;
Así obtienes una continuación determinista aunque haya empates de marca de tiempo.
6. El criterio de desempate debe coincidir con el orden de clasificación
Ejemplo ascendente:
updated_at ASC
order_id ASC
entonces la continuación es:
updated_at > last_updated_at
OR
updated_at = last_updated_at AND order_id > last_order_id
Si cambia el sentido de la ordenación, también debe cambiar el sentido del predicado.
7. No uses MAX(updated_at) por sí solo sin pensar en los empates
Ejemplo de fallo:
fila A updated_at = 10:00:00
fila B updated_at = 10:00:00
el pipeline procesa solo A
el checkpoint pasa a 10:00:00
la siguiente consulta usa:
updated_at > 10:00:00
La fila B se omite.
Persiste suficiente estado para reanudar de forma determinista.
8. Ventanas de lote semiabiertas
Otro patrón:
[inicio, fin)
Consulta:
SELECT *
FROM source_orders
WHERE updated_at >= @start_time
AND updated_at < @end_time;
Tras un éxito:
siguiente inicio = fin anterior
Funciona bien cuando:
- el procesamiento se basa en ventanas de tiempo
- las marcas de tiempo del origen son fiables
- las llegadas tardías se gestionan por separado
9. Las ventanas semiabiertas no resuelven las llegadas tardías
Ejemplo:
el evento ocurrió a las 10:30
llega al origen a las 12:15
Si tu lote de 10:00–11:00 ya terminó, el registro puede perderse, salvo que la marca de tiempo del origen refleje la hora de llegada o de actualización, o que el pipeline vuelva a leer intencionadamente un solapamiento.
10. Ventanas de solapamiento para llegadas tardías
Patrón:
último fin correcto = 12:00
la siguiente lectura empieza a las 11:45
Después:
releer los datos recientes
→ deduplicar/upsert
El solapamiento puede mejorar la resiliencia ante actualizaciones retrasadas del origen.
Requiere escrituras idempotentes en el destino.
No elijas una duración de solapamiento arbitraria; básala en el retraso observado del origen.
11. Ejemplo de solapamiento deslizante
SELECT *
FROM source_orders
WHERE updated_at >= DATEADD(minute, -30, @last_successful_end)
AND updated_at < @current_end;
Esto es solo ilustrativo.
La duración del solapamiento debe derivarse del comportamiento del origen y del SLA de negocio.
12. Persiste el checkpoint después del éxito
Mal:
1. calcular el nuevo watermark
2. guardar el watermark
3. escribir en el destino
4. la escritura en el destino falla
La siguiente ejecución puede omitir datos.
Correcto:
1. leer un origen acotado
2. transformar
3. validar
4. escribir en el destino
5. conciliar
6. guardar el checkpoint
13. El checkpoint debe describir el alcance completado
Campos útiles:
pipeline_name
source_name
last_successful_watermark
last_successful_tiebreaker
batch_id
completed_at
row_count
status
Esto facilita la auditoría y la reproducción.
14. Mantén el estado del checkpoint de forma duradera
No guardes un estado de watermark crítico solo en:
variable del notebook
archivo temporal local
memoria
Usa almacenamiento duradero, como:
- una tabla de metadatos
- una tabla de control
- el estado del orquestador
- un almacenamiento de checkpoints duradero
15. Usa un checkpoint por flujo lógico
Mal:
todos los tenants comparten un mismo watermark
si los tenants avanzan de forma independiente.
Mejor:
pipeline + origen + tenant
→ checkpoint propio
solo cuando se necesite un avance separado.
16. Carga incremental con manifiesto de archivos
Para orígenes basados en archivos, registra los archivos procesados.
Metadatos de ejemplo:
source_file
file_size
checksum
received_at
processed_at
batch_id
status
Después procesa solo los archivos nuevos o no procesados.
17. El nombre de archivo por sí solo puede no demostrar unicidad
Un origen puede sobrescribir:
orders.csv
con contenido nuevo.
Usa una identidad más sólida cuando esté disponible:
- versión del origen
- suma de comprobación (checksum)
- metadatos de modificación del archivo
- ruta de entrega inmutable
- ID de manifiesto
18. Particionar por ruta de archivo puede simplificar el descubrimiento incremental
Ejemplo:
/landing/orders/2026/10/04/*.parquet
Si el origen garantiza carpetas de fecha inmutables, el pipeline puede descubrir particiones nuevas.
Aun así, registra el estado de procesamiento: que exista un directorio no demuestra por sí solo que la ingesta haya sido correcta.
19. Patrón CDC
CDC puede emitir:
INSERT
UPDATE
DELETE
con información de orden o de versión.
Evento conceptual:
{
"operation": "UPDATE",
"orderId": "123",
"commitVersion": 9001,
"updatedAt": "2026-10-04T14:00:00Z"
}
Persiste la posición o el checkpoint de CDC después de aplicarlo correctamente.
20. CDC no implica automáticamente streaming
Puedes consumir CDC:
de forma continua
o:
cada 5 minutos
cada hora
El mecanismo de cambios del origen y la cadencia de procesamiento son decisiones independientes.
21. Usa la secuencia, el LSN o la versión nativos del origen cuando estén disponibles
Un token de orden nativo y fiable del origen suele ser más seguro que las marcas de tiempo de la aplicación.
Ejemplos conceptuales:
LSN
versión de commit
número de secuencia de cambio
offset
Respeta la semántica de orden documentada por el origen.
22. No conviertas un checkpoint nativo del origen en una marca de tiempo menos fiable
Si el origen proporciona posiciones de CDC exactas y ordenadas, consérvalas.
Convertir:
LSN → marca de tiempo
puede hacer perder precisión en el orden.
23. Patrón de comparación de snapshots (snapshot diff)
Si el origen solo expone su estado completo actual:
snapshot actual
vs
snapshot de confianza anterior
Compara:
- filas nuevas
- filas modificadas
- filas que faltan / eliminaciones
Es más costoso, pero puede permitir actualizaciones incrementales del destino.
24. Patrón de comparación por hash (hash-diff)
Calcula un hash a partir de las columnas relevantes para el negocio:
from pyspark.sql import functions as F
snapshot = snapshot.withColumn(
"row_hash",
F.sha2(
F.concat_ws(
"||",
F.coalesce(F.col("status"), F.lit("<NULL>")),
F.coalesce(F.col("amount").cast("string"), F.lit("<NULL>")),
F.coalesce(F.col("currency"), F.lit("<NULL>")),
),
256,
)
)
Compara el hash por clave de negocio para detectar filas modificadas.
La canonicalización importa.
25. Calcula el hash solo sobre columnas relevantes
No incluyas metadatos volátiles como:
marca de tiempo de ingesta
ID de ejecución del pipeline
marca de tiempo de carga
o todas las filas parecerán modificadas.
Calcula el hash solo sobre los campos de origen o de negocio que definen un cambio.
26. Normaliza los valores antes de calcular el hash
Posible inestabilidad:
1
1.0
1.00
o:
NULL
cadena vacía
pueden representar estados de negocio distintos o idénticos según las reglas.
Canonicaliza de forma deliberada.
27. MERGE para inserciones y actualizaciones
PySpark + Delta:
from delta.tables import DeltaTable
target = DeltaTable.forName(
spark,
"silver.orders",
)
(
target.alias("t")
.merge(
source.alias("s"),
"t.order_id = s.order_id",
)
.whenMatchedUpdateAll()
.whenNotMatchedInsertAll()
.execute()
)
Valida primero la unicidad del origen.
28. Usa asignaciones explícitas para un MERGE controlado
Más seguro para esquemas gobernados:
(
target.alias("t")
.merge(
source.alias("s"),
"t.order_id = s.order_id",
)
.whenMatchedUpdate(
set={
"status": "s.status",
"amount": "s.amount",
"updated_at": "s.updated_at",
}
)
.whenNotMatchedInsert(
values={
"order_id": "s.order_id",
"status": "s.status",
"amount": "s.amount",
"updated_at": "s.updated_at",
}
)
.execute()
)
Esto reduce la propagación accidental de columnas no deseadas.
29. Actualiza solo cuando el origen sea más reciente
(
target.alias("t")
.merge(
source.alias("s"),
"t.order_id = s.order_id",
)
.whenMatchedUpdate(
condition="s.updated_at > t.updated_at",
set={
"status": "s.status",
"amount": "s.amount",
"updated_at": "s.updated_at",
},
)
.whenNotMatchedInsertAll()
.execute()
)
Úsalo solo si updated_at representa de forma fiable la actualidad en el origen.
30. Valida la unicidad del origen del MERGE
duplicates = (
source
.groupBy("order_id")
.count()
.filter(F.col("count") > 1)
)
if duplicates.limit(1).count() > 0:
raise ValueError(
"Incremental source contains duplicate order_id values"
)
Las versiones ambiguas del origen deben resolverse antes del MERGE.
31. Deduplica la entrada incremental de forma determinista
Ejemplo:
from pyspark.sql.window import Window
w = (
Window
.partitionBy("order_id")
.orderBy(
F.col("updated_at").desc(),
F.col("source_version").desc(),
F.col("_ingested_at").desc(),
)
)
latest = (
source
.withColumn(
"_rn",
F.row_number().over(w),
)
.filter(F.col("_rn") == 1)
.drop("_rn")
)
Usa columnas de ordenación fiables.
32. Anexado incremental para eventos inmutables
Si los datos nunca cambian:
(
events.write
.format("delta")
.mode("append")
.saveAsTable("bronze.events")
)
El anexado (append) es más sencillo que MERGE cuando el origen es realmente inmutable y los duplicados están controlados.
33. El anexado también necesita una estrategia contra duplicados
Los reintentos pueden reenviar el mismo evento.
Usa:
event_id estable
y deduplicación o idempotencia aguas abajo cuando sea necesario.
34. Las eliminaciones requieren un diseño explícito
Si el origen puede eliminar filas, una consulta de «filas actualizadas» basada solo en marcas de tiempo puede no decirte nunca qué ha desaparecido.
Opciones:
eliminación/tombstone de CDC
indicador de eliminación lógica
conciliación por snapshot del origen
feed de eliminaciones separado
No supongas que las filas que faltan son eliminaciones salvo que el contrato del origen lo indique.
35. Patrón de eliminación lógica (soft delete)
Origen:
is_deleted = 1
Después:
(
target.alias("t")
.merge(
source.alias("s"),
"t.order_id = s.order_id",
)
.whenMatchedDelete(
condition="s.is_deleted = true"
)
.whenMatchedUpdateAll()
.whenNotMatchedInsertAll()
.execute()
)
Elimina solo cuando el origen comunique explícitamente una semántica de eliminación.
36. Evita conciliar eliminaciones entre origen y destino con extracciones parciales del origen
Mal:
el origen de hoy tiene 1.000 filas
el destino tiene 1.000.000 filas
ausentes en el origen de hoy
→ eliminar del destino
Esto es incorrecto salvo que el origen de hoy sea un snapshot completo y autoritativo.
37. La conciliación de snapshots puede detectar eliminaciones
Si el snapshot del origen es autoritativo:
claves actuales del origen
vs
claves actuales del destino
Entonces las claves que solo existen en el destino pueden ser eliminaciones.
Valida el alcance:
tenant
fecha
sistema de origen
antes de aplicar las eliminaciones.
38. Sobrescritura incremental de particiones
Si los datos están particionados de forma natural por fecha y una fecha es autoritativa:
reconstruir la partición 2026-10-04
→ reemplazar solo esa partición
Esto puede ser más sencillo que un MERGE a nivel de fila.
Usa el mecanismo seguro de reemplazo de particiones de la plataforma.
39. No sobrescribas toda la tabla por el cambio de una sola partición
Mal:
leer toda la tabla
unir la fecha de reemplazo
sobrescribir toda la tabla
Esto aumenta el costo y el riesgo.
Usa un reemplazo dirigido.
40. Las cargas incrementales necesitan idempotencia
Propiedad deseada:
ejecutar dos veces la misma entrada
→ mismo estado final del destino
La idempotencia hace que los reintentos sean más seguros.
41. Los trabajos de solo anexado necesitan protección contra duplicados en los reintentos
Enfoques posibles:
unicidad de event_id
batch_id + clave de origen
seguimiento por manifiesto
deduplicación en Silver
Elige según la semántica del origen.
42. MERGE no es automáticamente idempotente
Si el origen contiene duplicados o valores inestables, repetir el MERGE puede seguir produciendo resultados incorrectos.
La idempotencia depende de:
- claves estables
- un ganador determinista en el origen
- las reglas de actualización
- la semántica del destino
43. Gestiona con cuidado los reintentos y el checkpoint
Escenario:
la escritura en el destino tiene éxito
la escritura del checkpoint falla
La siguiente ejecución puede volver a leer los mismos datos.
Tu escritura en el destino debe tolerar la reproducción.
Es otro motivo por el que la idempotencia importa.
44. Una mentalidad parecida al commit en dos fases
Un pipeline incremental robusto suele comportarse así:
preparar un lote acotado
→ escribir de forma idempotente
→ validar/conciliar
→ confirmar el checkpoint
No trates la actualización del checkpoint como un detalle secundario sin relación con el resto.
45. Persiste los metadatos de los lotes
Campos útiles para una tabla de control:
batch_id
source_start
source_end
source_row_count
target_row_count
status
started_at
completed_at
checkpoint_before
checkpoint_after
code_version
Esto permite la reproducción y la auditoría.
46. Concilia el número de filas
Ejemplo:
filas leídas del origen
duplicados del origen eliminados
filas no válidas en cuarentena
filas insertadas
filas actualizadas
filas eliminadas
filas del destino en el alcance
Haz que el movimiento sea explicable.
47. Concilia también los totales de negocio
Para datos financieros:
recuento
sum(amount)
sum(fees)
totales por moneda
por lote, fecha o tenant.
El número de filas por sí solo puede pasar por alto importes duplicados.
48. No avances nunca el checkpoint si fallan controles de calidad bloqueantes
Correcto:
lectura del origen
→ transformación
→ falla el quality gate
→ lote marcado como fallido
→ checkpoint sin cambios
Esto preserva la capacidad de reproducción.
49. Separa los controles de calidad de advertencia de los bloqueantes
Ejemplo:
falta la clave de negocio
→ bloqueante
variación inusual del número de filas
→ advertencia
No congeles todos los pipelines ante cualquier anomalía.
50. Patrón para datos que llegan tarde
Mide:
source_updated_at
vs
ingestion_time
Si las llegadas tardías son frecuentes:
- lee con solapamiento
- usa CDC nativo del origen
- revisa el campo de watermark
- programa conciliaciones
No las ignores.
51. El backfill no debe corromper el checkpoint en producción
Mantén:
checkpoint de producción
separado de:
inicio/fin del backfill
Una reproducción histórica no debe hacer retroceder el watermark de producción.
52. El backfill debe ser explícito
Ejemplo:
backfill_start = 2026-09-01
backfill_end = 2026-09-08
Registra el alcance y el motivo.
53. El backfill puede reutilizar la misma lógica de transformación
Patrón ideal:
misma transformación Silver
límite de entrada distinto
Evita mantener una ruta de código para las cargas de producción y otra para la reparación histórica, salvo que sea necesario.
54. Protégete del solapamiento de escrituras de producción y de backfill
Si ambos modifican las mismas claves o particiones:
- coordina las programaciones
- usa un MERGE que tenga en cuenta las versiones
- aísla el staging
- define reglas de ganador
No supongas que las garantías ACID a nivel de tabla bastan por sí solas para asegurar la corrección de negocio.
55. Staging antes del MERGE
Patrón útil:
extraer el origen incremental
→ escribir en una tabla de staging
→ validar
→ MERGE del staging en el destino
Ventajas:
- lote reproducible
- diagnóstico más sencillo
- snapshot del origen aislado
56. Asigna un ID de lote a los datos de staging
Ejemplo:
staging.orders_incremental
batch_id = 20261004_1400
Esto facilita los reintentos y las investigaciones.
57. No vacíes a la ligera un staging compartido
Si varias ejecuciones pueden solaparse, usa:
staging acotado al lote
en lugar de una única área de staging compartida y mutable.
58. Las actualizaciones del origen pueden llegar desordenadas
Ejemplo:
llega la versión 5
luego llega más tarde la versión 4
Si es posible, usa:
versión / secuencia del origen
en lugar de la hora de llegada para elegir al ganador.
59. La hora de ingesta no indica la actualidad en el origen
_ingested_at responde a:
cuándo vio la plataforma el registro
no a:
qué versión del origen es más reciente
Úsala solo como criterio de desempate final cuando sea apropiado.
60. El orden de las actualizaciones de CDC importa
Si el origen emite:
LSN 100
LSN 101
LSN 102
aplica y concilia según el orden del origen.
No ordenes solo por una marca de tiempo de negocio si el orden de CDC es el autoritativo.
61. Las lecturas incrementales por hora del evento son arriesgadas para entidades mutables
Si un pedido creado ayer se actualiza hoy, pero filtras solo por:
created_at > ayer
te pierdes la actualización.
Usa:
updated_at
CDC
versión
para los registros mutables.
62. Un watermark por fecha de creación encaja con entidades de solo anexado
Adecuado cuando:
los registros nunca cambian después de crearse
Por ejemplo, filas de auditoría o de eventos inmutables.
Aun así, ten en cuenta una visibilidad retrasada de las creaciones si existe latencia de commit o de replicación en el origen.
63. Usa la hora de commit del origen cuando esté disponible
Las marcas de tiempo de la aplicación pueden estar:
- proporcionadas por el usuario
- antedatadas
- desplazadas de zona horaria
Los metadatos de commit de la base de datos o del origen pueden ser más fiables para la captura incremental, cuando se admiten.
64. El desfase de relojes puede romper los watermarks por marca de tiempo
Los sistemas distribuidos pueden escribir marcas de tiempo desde máquinas con relojes distintos.
Si el orden fiable es importante, prefiere una secuencia o versión nativa del origen.
65. Evita usar current_timestamp() como watermark del origen
Esto registra la hora del pipeline, no necesariamente el límite del origen.
Usa un corte derivado del origen o explícitamente acotado.
66. Fija el corte del lote antes de leer el origen
Patrón:
fin = corte seguro del origen
leer [inicio, fin)
Esto evita una ventana de consulta móvil durante la ejecución.
67. Usa cortes con retraso cuando los commits del origen se asientan tarde
Concepto de ejemplo:
hora actual - retraso de asentamiento del origen
puede reducir la lectura de datos confirmados o replicados de forma parcial.
Úsalo solo si el comportamiento del origen lo justifica.
68. Paginación y carga incremental son cosas distintas
Paginación:
cómo recuperar un conjunto de resultados acotado por partes
Carga incremental:
qué cambios pertenecen a la siguiente ejecución del pipeline
Un pipeline puede necesitar ambas.
69. Conserva el cursor de paginación hasta completar la extracción acotada
Si un rango incremental de una API devuelve varias páginas:
ventana de watermark
→ página 1
→ página 2
→ página 3
No avances el watermark duradero del origen después de la página 1.
Termina primero todo el intervalo acotado.
70. Ejemplo de extracción incremental desde una API
Solicitud conceptual:
GET /orders?
updated_after=2026-10-04T10:00:00Z
&updated_before=2026-10-04T11:00:00Z
&cursor=...
Procesa todas las páginas de la ventana.
Después confirma:
watermark = 11:00
71. Los cursores de API pueden caducar
Si un cursor caduca a mitad de una ventana, el cliente necesita una estrategia de reinicio.
Opciones:
- reiniciar la ventana acotada de forma idempotente
- usar un token de página duradero si el proveedor lo admite
- dividir en ventanas más pequeñas
No uses como único checkpoint un cursor efímero sin entender su ciclo de vida.
72. Los límites de tasa afectan al diseño de la carga incremental
Un gran trabajo atrasado puede generar muchas llamadas a la API.
Respeta:
429Retry-After- los límites de concurrencia
No conviertas una ejecución de puesta al día en un patrón de denegación de servicio.
73. La carga incremental debe poder reanudarse
Un lote fallido debe tener un punto de recuperación conocido.
Pregúntate:
¿Qué rango exacto del origen leerá el reintento?
¿Qué estado del destino existe ya?
¿Se puede volver a aplicar el mismo origen de forma segura?
74. Persiste el alcance del fallo
Ejemplo:
batch_id
watermark inicial
watermark final
última página completada
estado de la escritura en el destino
estado de calidad
Esto mejora la recuperación controlada.
75. No edites los checkpoints manualmente a la ligera
Cambiar:
last_successful_watermark
puede omitir o duplicar datos.
Si se necesita una reparación manual:
- registra el valor original
- define el alcance de la reproducción
- verifica la idempotencia del destino
- documenta el motivo
76. Reparar un checkpoint es un cambio en producción
Trátalo como:
- una corrección de datos
- una migración
- un paso de un runbook operativo
no como una simple actualización de metadatos.
77. Las cargas incrementales necesitan observabilidad
Registra en cada ejecución:
filas del origen
filas insertadas
filas actualizadas
filas eliminadas
filas duplicadas
filas no válidas
duración
checkpoint antes/después
filas tardías
Esto ayuda a detectar desviaciones silenciosas.
78. Que de repente no haya cambios puede ser sospechoso
Posibles causas:
origen legítimamente sin actividad
watermark demasiado adelantado
bug en el filtro
caída del origen
problema de autenticación/API
error de zona horaria
Ten en cuenta el contexto antes de dar la ejecución por buena.
79. Un volumen de cambios repentinamente enorme puede ser sospechoso
Posibles causas:
reinicio del watermark
backfill en el origen
páginas de API duplicadas
cambio de esquema
bug del origen
posición de CDC reproducida
Investiga antes de aplicar a ciegas.
80. Monotonía del checkpoint
Para orígenes monótonos:
nuevo checkpoint
>=
checkpoint anterior
Un retroceso debe deberse a un backfill o a una recuperación intencionados, no a un cambio accidental del estado de producción.
81. Mantén el alcance del checkpoint alineado con el filtro del origen
Si el checkpoint es por tenant:
watermark del tenant A
watermark del tenant B
entonces las lecturas y escrituras deben respetar ese alcance.
No actualices un watermark global a partir del avance de un solo tenant.
82. La deriva del esquema puede romper las cargas incrementales en silencio
Ejemplo:
updated_at renombrado
El pipeline puede:
- fallar
- leer cero filas
- interpretar valores nulos
Valida las columnas de watermark necesarias antes de procesar.
83. Cambiar el campo de watermark es una migración
Pasar de:
updated_at
→ source_version
requiere una transición controlada.
Define:
- el checkpoint anterior
- la posición inicial del nuevo checkpoint
- el solapamiento
- la validación
No cambies la lógica de producción sin un análisis de la reproducción.
84. Cambiar la clave del MERGE es peligroso
Si la clave del destino cambia de:
order_id
a:
merchant_id + order_id
los datos existentes del destino y la lógica incremental deben migrar de forma coherente.
De lo contrario, las actualizaciones pueden afectar a filas equivocadas o duplicar entidades.
85. La lógica incremental debe ser determinista
El mismo:
lote del origen
+
versión del código
+
datos/versión de referencia
debería producir el mismo resultado en el destino siempre que sea posible.
Evita dependencias ocultas de la hora actual.
86. Patrón incremental SCD Type 1
Para dimensiones que sobrescriben el valor actual:
clave de negocio
→ MERGE de los últimos valores del origen en la fila actual
No se conserva historial.
Adecuado cuando no se necesita el historial de cambios de atributos.
87. Patrón incremental SCD Type 2
Conceptualmente:
atributo modificado
→ expirar la fila actual
→ insertar una nueva versión
Campos típicos:
effective_from
effective_to
is_current
Es más complejo que un MERGE normal.
Úsalo cuando el estado histórico sea un requisito real.
88. SCD Type 2 requiere disciplina con duplicados y versiones
Si llegan varios cambios del origen para una misma clave en un mismo lote, ordénalos según una secuencia de cambios fiable del origen.
No supongas que hay un único cambio por clave y por lote.
89. Las cargas de hechos por snapshot pueden usar el reemplazo de particiones
Para un snapshot diario autoritativo:
snapshot_date = 2026-10-04
reemplaza solo la partición de ese día.
Puede ser más sencillo que la detección de cambios a nivel de fila.
90. Las cargas de hechos de auditoría suelen usar anexado
Para eventos de transacciones o de auditoría inmutables:
añadir las filas nuevas
con claves de evento estables y protección contra duplicados.
91. Separa el checkpoint de ingesta del checkpoint de transformación cuando sea necesario
Ejemplo:
extracción en bruto de la API completada hasta las 11:00
procesamiento Silver completado hasta las 10:00
Son etapas distintas.
Un único watermark puede ocultar dónde está el trabajo atrasado.
92. Los checkpoints por capa pueden mejorar la recuperación
Ejemplo:
posición del origen en Bronze
posición procesada en Silver
posición publicada en Gold
Útil en plataformas de varias etapas.
No crees una complejidad de checkpoints innecesaria para pipelines sencillos.
93. El avance del checkpoint forma parte de la frescura de los datos
Si Bronze está al día pero el watermark de Gold está atrasado, los datos que ven los usuarios siguen desactualizados.
Monitorea el avance de extremo a extremo.
94. Las lecturas incrementales deben estar acotadas siempre que sea posible
Evita:
updated_at > last_watermark
sin un límite superior fijo en un trabajo de larga duración.
En su lugar, define:
inicio
fin
al inicio de la ejecución, cuando la semántica del origen lo permita.
Esto facilita la reproducción y la conciliación.
95. La extracción acotada permite reintentos reproducibles
Si el lote es:
[10:00, 11:00)
reintenta el mismo alcance.
No dejes que el reintento se desplace a:
[10:00, current_time)
salvo que sea intencionado.
96. Debe existir una estrategia de reconstrucción
Tarde o temprano puedes necesitar:
reprocesar un día
reprocesar un tenant
reconstruir toda la tabla Silver
Diseña la lógica incremental para que esto sea posible.
97. Lo incremental es una optimización, no la fuente de verdad
La fuente de verdad debe seguir estando clara:
base de datos de origen
log de eventos en bruto
capa Bronze
archivos de referencia autorizados
El checkpoint solo registra el avance.
98. Prueba los escenarios de fallo
Como mínimo, prueba:
el origen devuelve duplicados
la escritura en el destino tiene éxito pero el checkpoint falla
el checkpoint tiene éxito pero la publicación aguas abajo falla
llega un registro tardío después del watermark
aparece una eliminación
cambia el esquema
un backfill se solapa con una ejecución de producción
99. Usa una lista de verificación de implementación repetible
Antes de pasar a producción:
1. Definir la fuente de verdad
2. Elegir un indicador de cambio fiable
3. Definir un orden determinista
4. Definir un alcance de lectura acotado
5. Definir la estrategia de duplicados/idempotencia
6. Definir la semántica de inserción/actualización/eliminación
7. Definir la política de datos tardíos
8. Definir un checkpoint duradero
9. Definir el control de calidad/conciliación
10. Definir el procedimiento de reintento/backfill
Si alguno de estos puntos es desconocido, el diseño incremental está incompleto.
Qué significa el resultado
| Patrón | Mejor encaje | Riesgo principal |
|---|---|---|
| High-water mark con ID creciente | Eventos ordenados inmutables | El orden supuesto puede ser falso |
| Watermark por marca de tiempo | Registros mutables con hora de actualización fiable | Empates, actualizaciones tardías, problemas de reloj |
| Marca de tiempo + criterio de desempate | Registros mutables ordenados | Más estado de checkpoint |
| Secuencia CDC/LSN | Bases de datos / feeds de cambios | Semántica específica de cada origen |
| Manifiesto de archivos | Ingesta de archivos | Archivos reemplazados / identidad de archivo débil |
| Comparación de snapshots | Origen con el estado actual completo | Comparación costosa |
| Comparación por hash | Snapshots anchos | Errores de canonicalización |
| Reemplazo de particiones | Porciones acotadas autoritativas | Alcance de sobrescritura erróneo |
| MERGE/upsert | Inserciones + actualizaciones | Claves duplicadas en el origen / concurrencia |
| Ventana de solapamiento | Cambios del origen que llegan tarde | Requiere escrituras idempotentes |
El principio fundamental es:
la carga incremental es gestión de estado
no una simple consulta filtrada.
Qué revisar
Faltan filas tras un reinicio
Revisa:
- un checkpoint avanzado demasiado pronto
- empates de marcas de tiempo
- filas que llegaron tarde
- un orden no determinista
- el checkpoint de la paginación
Aparecen filas duplicadas
Revisa:
- una reproducción tras un fallo del checkpoint
- un reintento de solo anexado
- una clave de evento o de negocio ausente
- registros duplicados en el origen
- duplicados en el origen del MERGE
Valores antiguos sobrescriben otros más recientes
Revisa:
- actualizaciones del origen desordenadas
- el uso de la hora de ingesta en lugar de la versión del origen
- la falta de la condición «origen más reciente que el destino»
Las eliminaciones nunca llegan al destino
Comprueba si el origen expone:
- un indicador de eliminación
- un tombstone (marca de eliminación)
- una eliminación de CDC
- un snapshot autoritativo
Un simple watermark de actualizaciones puede no capturar las eliminaciones.
El trabajo incremental de repente lo lee todo
Revisa:
- un checkpoint reiniciado o ausente
- un filtro del origen modificado
- la conversión de tipo o de zona horaria de la marca de tiempo
- un error en la migración del watermark
El trabajo lee cero filas inesperadamente
Revisa:
- un watermark demasiado adelantado
- una caída del origen
- la zona horaria del filtro
- una columna de watermark ausente o renombrada
- un alcance de tenant o de origen incorrecto
Notas de producción
Los checkpoints son datos de producción
Protégelos con:
- durabilidad
- auditabilidad
- actualizaciones controladas
- copias de seguridad cuando corresponda
La idempotencia es lo que hace seguros los reintentos
Da por hecho que un lote puede reproducirse.
Diseña el destino para que la reproducción no corrompa el estado.
Las marcas de tiempo del origen no siempre son fiables
Prefiere la secuenciación nativa del origen cuando esté disponible.
Los datos tardíos son normales en los sistemas distribuidos
Define, con base en la evidencia, cuánto hacia atrás puedes necesitar volver a leer o conciliar.
Las eliminaciones necesitan una semántica explícita
No deduzcas una eliminación a partir de una ausencia salvo que el origen sea un snapshot completo y autoritativo.
Los backfills forman parte de la arquitectura
La reparación histórica no debería requerir apaños improvisados en los checkpoints.
Errores comunes
1. Usar MAX(updated_at) como único checkpoint
Los empates de marcas de tiempo pueden hacer que se omitan filas.
2. Avanzar el checkpoint antes de que la escritura tenga éxito
Esto puede omitir datos de forma permanente.
3. Suponer que MERGE hace seguro cualquier reintento
La unicidad del origen y unas reglas de actualización deterministas siguen siendo importantes.
4. Usar la fecha de creación para registros mutables
Se perderán las actualizaciones de filas antiguas.
5. Ignorar las eliminaciones
El estado del destino se va alejando poco a poco del origen.
6. Tratar la hora de ingesta como versión del origen
Datos más antiguos que llegan tarde pueden sobrescribir un estado más reciente.
7. Editar manualmente los watermarks sin un plan de reproducción
Esto crea huecos o duplicados silenciosos.
8. Dejar que los backfills modifiquen los checkpoints de producción
La reparación histórica debe estar aislada del estado de avance en producción.
9. Usar solo el nombre de archivo como identidad de procesamiento
Los orígenes pueden sobrescribir o reenviar el mismo nombre.
10. No tener un alcance acotado para los reintentos
Si un reintento lee un intervalo del origen distinto al de la ejecución fallida, la conciliación se vuelve difícil.
¿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.