Explorar guías rápidas · Ingeniería de datos

Tecnología: Ingeniería de datosCategoría: Integración de datosNivel: IntermedioActualizado

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
  1. Problema
  2. Respuesta rápida
  3. Código / comandos
  4. 1. Referencia: la recarga completa
  5. 2. High-water mark con un ID creciente
  6. 3. No supongas que cualquier ID es un high-water mark válido
  7. 4. Watermark por marca de tiempo
  8. 5. Marca de tiempo + criterio de desempate único
  9. 6. El criterio de desempate debe coincidir con el orden de clasificación
  10. 7. No uses MAX(updated_at) por sí solo sin pensar en los empates
  11. 8. Ventanas de lote semiabiertas
  12. 9. Las ventanas semiabiertas no resuelven las llegadas tardías
  13. 10. Ventanas de solapamiento para llegadas tardías
  14. 11. Ejemplo de solapamiento deslizante
  15. 12. Persiste el checkpoint después del éxito
  16. 13. El checkpoint debe describir el alcance completado
  17. 14. Mantén el estado del checkpoint de forma duradera
  18. 15. Usa un checkpoint por flujo lógico
  19. 16. Carga incremental con manifiesto de archivos
  20. 17. El nombre de archivo por sí solo puede no demostrar unicidad
  21. 18. Particionar por ruta de archivo puede simplificar el descubrimiento incremental
  22. 19. Patrón CDC
  23. 20. CDC no implica automáticamente streaming
  24. 21. Usa la secuencia, el LSN o la versión nativos del origen cuando estén disponibles
  25. 22. No conviertas un checkpoint nativo del origen en una marca de tiempo menos fiable
  26. 23. Patrón de comparación de snapshots (snapshot diff)
  27. 24. Patrón de comparación por hash (hash-diff)
  28. 25. Calcula el hash solo sobre columnas relevantes
  29. 26. Normaliza los valores antes de calcular el hash
  30. 27. MERGE para inserciones y actualizaciones
  31. 28. Usa asignaciones explícitas para un MERGE controlado
  32. 29. Actualiza solo cuando el origen sea más reciente
  33. 30. Valida la unicidad del origen del MERGE
  34. 31. Deduplica la entrada incremental de forma determinista
  35. 32. Anexado incremental para eventos inmutables
  36. 33. El anexado también necesita una estrategia contra duplicados
  37. 34. Las eliminaciones requieren un diseño explícito
  38. 35. Patrón de eliminación lógica (soft delete)
  39. 36. Evita conciliar eliminaciones entre origen y destino con extracciones parciales del origen
  40. 37. La conciliación de snapshots puede detectar eliminaciones
  41. 38. Sobrescritura incremental de particiones
  42. 39. No sobrescribas toda la tabla por el cambio de una sola partición
  43. 40. Las cargas incrementales necesitan idempotencia
  44. 41. Los trabajos de solo anexado necesitan protección contra duplicados en los reintentos
  45. 42. MERGE no es automáticamente idempotente
  46. 43. Gestiona con cuidado los reintentos y el checkpoint
  47. 44. Una mentalidad parecida al commit en dos fases
  48. 45. Persiste los metadatos de los lotes
  49. 46. Concilia el número de filas
  50. 47. Concilia también los totales de negocio
  51. 48. No avances nunca el checkpoint si fallan controles de calidad bloqueantes
  52. 49. Separa los controles de calidad de advertencia de los bloqueantes
  53. 50. Patrón para datos que llegan tarde
  54. 51. El backfill no debe corromper el checkpoint en producción
  55. 52. El backfill debe ser explícito
  56. 53. El backfill puede reutilizar la misma lógica de transformación
  57. 54. Protégete del solapamiento de escrituras de producción y de backfill
  58. 55. Staging antes del MERGE
  59. 56. Asigna un ID de lote a los datos de staging
  60. 57. No vacíes a la ligera un staging compartido
  61. 58. Las actualizaciones del origen pueden llegar desordenadas
  62. 59. La hora de ingesta no indica la actualidad en el origen
  63. 60. El orden de las actualizaciones de CDC importa
  64. 61. Las lecturas incrementales por hora del evento son arriesgadas para entidades mutables
  65. 62. Un watermark por fecha de creación encaja con entidades de solo anexado
  66. 63. Usa la hora de commit del origen cuando esté disponible
  67. 64. El desfase de relojes puede romper los watermarks por marca de tiempo
  68. 65. Evita usar current_timestamp() como watermark del origen
  69. 66. Fija el corte del lote antes de leer el origen
  70. 67. Usa cortes con retraso cuando los commits del origen se asientan tarde
  71. 68. Paginación y carga incremental son cosas distintas
  72. 69. Conserva el cursor de paginación hasta completar la extracción acotada
  73. 70. Ejemplo de extracción incremental desde una API
  74. 71. Los cursores de API pueden caducar
  75. 72. Los límites de tasa afectan al diseño de la carga incremental
  76. 73. La carga incremental debe poder reanudarse
  77. 74. Persiste el alcance del fallo
  78. 75. No edites los checkpoints manualmente a la ligera
  79. 76. Reparar un checkpoint es un cambio en producción
  80. 77. Las cargas incrementales necesitan observabilidad
  81. 78. Que de repente no haya cambios puede ser sospechoso
  82. 79. Un volumen de cambios repentinamente enorme puede ser sospechoso
  83. 80. Monotonía del checkpoint
  84. 81. Mantén el alcance del checkpoint alineado con el filtro del origen
  85. 82. La deriva del esquema puede romper las cargas incrementales en silencio
  86. 83. Cambiar el campo de watermark es una migración
  87. 84. Cambiar la clave del MERGE es peligroso
  88. 85. La lógica incremental debe ser determinista
  89. 86. Patrón incremental SCD Type 1
  90. 87. Patrón incremental SCD Type 2
  91. 88. SCD Type 2 requiere disciplina con duplicados y versiones
  92. 89. Las cargas de hechos por snapshot pueden usar el reemplazo de particiones
  93. 90. Las cargas de hechos de auditoría suelen usar anexado
  94. 91. Separa el checkpoint de ingesta del checkpoint de transformación cuando sea necesario
  95. 92. Los checkpoints por capa pueden mejorar la recuperación
  96. 93. El avance del checkpoint forma parte de la frescura de los datos
  97. 94. Las lecturas incrementales deben estar acotadas siempre que sea posible
  98. 95. La extracción acotada permite reintentos reproducibles
  99. 96. Debe existir una estrategia de reconstrucción
  100. 97. Lo incremental es una optimización, no la fuente de verdad
  101. 98. Prueba los escenarios de fallo
  102. 99. Usa una lista de verificación de implementación repetible
  103. Qué significa el resultado
  104. Qué revisar
  105. Faltan filas tras un reinicio
  106. Aparecen filas duplicadas
  107. Valores antiguos sobrescriben otros más recientes
  108. Las eliminaciones nunca llegan al destino
  109. El trabajo incremental de repente lo lee todo
  110. El trabajo lee cero filas inesperadamente
  111. Notas de producción
  112. Los checkpoints son datos de producción
  113. La idempotencia es lo que hace seguros los reintentos
  114. Las marcas de tiempo del origen no siempre son fiables
  115. Los datos tardíos son normales en los sistemas distribuidos
  116. Las eliminaciones necesitan una semántica explícita
  117. Los backfills forman parte de la arquitectura
  118. Errores comunes
  119. 1. Usar MAX(updated_at) como único checkpoint
  120. 2. Avanzar el checkpoint antes de que la escritura tenga éxito
  121. 3. Suponer que MERGE hace seguro cualquier reintento
  122. 4. Usar la fecha de creación para registros mutables
  123. 5. Ignorar las eliminaciones
  124. 6. Tratar la hora de ingesta como versión del origen
  125. 7. Editar manualmente los watermarks sin un plan de reproducción
  126. 8. Dejar que los backfills modifiquen los checkpoints de producción
  127. 9. Usar solo el nombre de archivo como identidad de procesamiento
  128. 10. No tener un alcance acotado para los reintentos
  129. Siguiente paso
  130. 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:

  • 429
  • Retry-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.

Siguiente paso

Usa las capacidades del origen y el síntoma del fallo para elegir la siguiente acción.

  • Eventos ordenados inmutables → usa una secuencia del origen / high-water mark.
  • Marca de tiempo de actualización fiable → usa marca de tiempo + criterio de desempate determinista.
  • El origen proporciona CDC/LSN/versión → prefiere la posición de cambio nativa.
  • Origen de archivos → usa un manifiesto con una identidad de archivo duradera.
  • Solo snapshots completos → usa una comparación de snapshots o de hashes con staging.
  • Se necesitan inserciones y actualizaciones → usa un MERGE/upsert determinista.
  • Se necesitan eliminaciones → añade semántica de tombstone/CDC/conciliación de snapshots.
  • Se pierden filas tardías → añade solapamiento o pasa a una secuencia del origen más sólida.
  • Los reintentos crean duplicados → refuerza la idempotencia y la gestión de claves.
  • Se necesita un backfill → usa un alcance histórico explícito sin cambiar el checkpoint de producción.
  • La lógica incremental se está volviendo demasiado compleja → reevalúa si una reconstrucción acotada completa o por particiones sería más sencilla y segura.

← Todas las guías rápidas