Lee antes: Modos de carga · Referencia: incremental y backfill.
Qué es#
Backfill es traer el histórico anterior a la ventana que el incremental normalmente cubre — por ejemplo, los últimos 24 meses cuando el refresh diario solo mira los últimos días.
Para qué sirve#
- Poblar una fuente recién conectada con todo el histórico.
- Reprocesar un período específico después de corregir una regla.
- Extender hacia atrás la serie temporal de un dashboard.
Cuándo usar / cuándo no usar#
- Úsalo cuando: acabas de conectar la fuente, cambiaste la lógica de negocio o necesitas un período antiguo que el incremental no alcanza.
- No lo uses cuando: el histórico ya está cargado y solo quieres el día a día — en ese caso el incremental por watermark es suficiente.
Plan y permisos#
- Núcleo · verificación de acceso · interruptores de apagado para ejecución de ingesta y actualización de paneles.
Requisitos previos#
- Una fuente conectada y probada.
- Claridad sobre el período o volumen que quieres traer.
Las tres formas de hacer backfill#
| Forma | Cómo | Cuándo |
|---|---|---|
| Full puntual | ejecuta una carga full una vez | cubre todo el histórico de una vez; ideal en la 1.ª carga |
| Ventana amplia (por período) | aumenta recentDays (hasta el tope de 400) | recalcula una ventana mayor sin un full completo |
| Primera extracción del conector | la 1.ª ejecución del pull recorre la paginación hasta el tope | la propia 1.ª ejecución ya es el backfill; las siguientes se reanudan por checkpoint/watermark |
Paso a paso#
- Decide el alcance. ¿Todo el histórico? Haz un full. ¿Un período específico? Amplía la ventana por período.
- Backfill por full: abre la fuente, asegúrate de que las tablas estén seleccionadas y ejecuta el pipeline en modo full (ver el tutorial de pipeline full).
- Backfill por ventana: aumenta
recentDayspara cubrir el período deseado (tope de 400 días) y ejecuta el refresh — recalcula la ventana ampliada. - Backfill de un conector nuevo: basta con ejecutar la primera extracción; recorre la paginación hasta el tope duro. Las ejecuciones siguientes continúan desde el checkpoint.
- Después del backfill, vuelve al incremental para el día a día (más barato).
Ejemplo (sintético)#
Conectaste una tabla pedidos nueva y quieres los últimos 2 años:
1) Ejecuta un FULL una vez → trae todo el histórico hasta el tope de paginación.
2) Activa el INCREMENTAL → columna de watermark = atualizado_em.
3) Refresh diario → trae solo el delta a partir de ahí.Si necesitas reprocesar solo enero de 2026 en un agregado por período:
Aumenta recentDays lo suficiente para que la ventana cubra 2026-01 y ejecuta el refresh.Cómo funciona la reanudación (checkpoint)#
En una extracción larga que se interrumpe, el SDK de conectores usa un checkpoint:
- lee el checkpoint antes de extraer;
- lo graba en cada lote entregado (solo cuentan los lotes aceptados);
- lo limpia al terminar → la próxima ejecución programada empieza desde cero.
Así la reanudación no duplica ni pierde filas. Conectores como Azure Blob omiten los blobs ya procesados (nombre ≤ último procesado) para no reprocesar.
Resultado esperado#
- El histórico deseado aparece en Bronze y, después del pipeline, en los marts Gold.
- Una extracción que llega al tope señala
hadMore(hay más en la origen) — entonces amplías el tope de forma consciente o pasas al incremental.
Límites y costos#
- Tope duro de paginación: 10.000 páginas / 5.000.000 filas.
- Ventana por período: tope de 400 días.
maxRowsdel pull: por defecto 200.000 (hasta 5.000.000).- El backfill lee mucho — es la operación más cara. Ejecútalo fuera del horario pico y vuelve al incremental después.
Seguridad#
- Alcance por workspace en toda la carga; secretos redactados en errores/logs.
- La reanudación por checkpoint está acotada a quien la llama; ningún estado se filtra entre clientes.
Errores comunes#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| Backfill "incompleto" | llegó al tope de paginación (hadMore) | Amplía el tope de forma consciente o divídelo por período |
| Los datos atrasados no entran | llegaron con una fecha fuera de la ventana | Amplía recentDays o haz un full |
| Se reprocesó dos veces | full disparado sobre un incremental | El full recrea todo (idempotente); revisa el historial de ejecuciones |
Solución de problemas#
- Revisa el historial de ejecuciones:
bronzeRows/silverRowsy si se señalóhadMore. - Para conectores, mira la observabilidad (ejecuciones, freshness) para confirmar que la fuente está "al día".
Relacionados#
Última revisión: 2026-09-08.