Saltar al contenido

Traducción automática — la versión en portugués es la referencia. Ver en portugués

Ingesta — full, incremental, backfill y checkpoint

En esta página (7)

Lee antes: README.md. Capas del medallón en pipeline-medalhao.md.


La regla que no se puede romper#

En todos los modos incrementales vale una única invariante: el resultado incremental tiene que ser IDÉNTICO al refresh completo — mismas filas, mismo orden. Si hay la menor duda de elegibilidad, el producto rechaza el incremental y hace el full (con un motivo legible en el log).

"Un refresh caro es un problema de costo; un número equivocado es un problema de producto."


Modo 1 — Full (completo)#

Recalcula todo. Es el fallback seguro siempre disponible: cualquier rechazo de elegibilidad de un modo incremental cae aquí. Correcto por definición, más caro.

Modo 2 — Incremental por PERÍODO#

Para agregados por período (todo GROUP BY día/mes): recalcula solo la ventana reciente (default 7 días, tope 400) y reutiliza el histórico del snapshot anterior.

Tres condiciones que sostienen la identidad:

  1. resultado particionable por la columna de período (cada partición se calcula sola);
  2. la consulta ordena por la columna de período, ASC, como 1.ª clave (histórico + reciente ya salen en el orden del full);
  3. snapshot anterior no truncado.
  • Zona horaria: la clave de partición sale en la zona horaria del panel (America/Sao_Paulo), nunca UTC — la venta de las 22 h del día 31 en São Paulo es la 01 h del día 1 en UTC y caería en el mes equivocado.
  • Limitación asumida: un dato que llega con retraso con una fecha más vieja que la ventana no se recalcula (mismo contrato que Power BI/dbt).
  • Tipos de columna: date (compara directo) · timestamp (convierte a la zona horaria antes).

Modo 3 — Incremental por CLAVE / watermark#

Para tablas de detalle con id estable: guarda una marca de agua (el mayor valor de la columna-cursor en el snapshot anterior) y, en el próximo refresh, busca solo las filas con cursor >= marca (el delta). Cada fila del delta hace un UPSERT por clave sobre el snapshot; el resto del histórico se reutiliza intacto.

  • Predicado >= (no >) a propósito: vuelve a buscar la fila exactamente en la marca (el upsert es idempotente) y no pierde filas en la frontera del watermark.
  • Marca de agua = mayor valor del cursor entre las filas; sin cursor utilizable → escribe null → el próximo refresh cae en el full (seguro).

Semántica de borrado (limitación asumida): el merge por clave es UPSERT. Sin una señal de borrado, el incremental no elimina una clave que desapareció del origen (mismo contrato que cualquier watermark: dbt, Power BI). Dos señales opcionales restauran la identidad ante borrados:

  • completePartitions — dentro de una partición que se vuelve a buscar entera, la clave antigua ausente del delta SÍ se elimina;
  • deletedKeys — tombstones explícitos (CDC con borrado).

Un visual cuyo origen borra filas no debe usar mode:"key" puro — usa el modo por período (vuelve a buscar días enteros) o pasa una de las señales de arriba.

Rechazos → full (cada uno con motivo): widget sin incremental configurado · sin SQL · sin snapshot anterior · snapshot con error/truncado/vacío · sin cursor en el snapshot anterior (caso N−1) · el ORDER BY no es exactamente las claves ASC · clave ausente en alguna fila del histórico · delta que no se puede recortar con seguridad.

Anti-inyección: los nombres de columna (claves/cursor) se validan como identificadores simples antes de entrar crudos en el SQL; el literal del cursor rechaza comillas/barra/salto de línea y longitud > 64 (fuera de eso → hace full).

Compatibilidad N−1: un lector nuevo lee un snapshot antiguo (sin cursor) sin romperse; y ante un snapshot antiguo, rechaza el incremental y hace full.

Backfill (carga histórica)#

Backfill = traer el histórico anterior a la ventana incremental. En la práctica:

  • Por período: aumentar recentDays (hasta el tope de 400) fuerza el recálculo de una ventana mayor; un full cubre todo el histórico de una vez.
  • Por conector: la extracción inicial recorre la paginación hasta el tope duro (default 10.000 páginas / 5.000.000 filas) — la primera ejecución es el backfill; las siguientes retoman por checkpoint/watermark. Conectores como Azure Blob omiten los blobs ya procesados (nombre ≤ último procesado) para no reprocesar.

Checkpoint (reanudación sin duplicar ni perder)#

El SDK de conectores expone un contrato inyectable de checkpoint (dónde vive el estado — base de datos del producto/caché gestionada/memoria — es decisión de quien llama; ninguna tabla nace en el SDK):

  • lee el checkpoint antes de extraer;
  • escribe después de cada lote entregado (solo cuentan los lotes aceptados);
  • se limpia (null) al concluir → la próxima ejecución programada empieza desde cero.

Semántica: el checkpoint solo existe entre la interrupción y la reanudación. El reintento vive debajo de la extracción, así que cada lote nunca se entrega dos veces.


Ficha (plantilla de los 9 campos)#

  1. Estado — disponible. La elegibilidad y la igualdad de resultado entre incremental y full están cubiertas por pruebas automáticas.
  2. Qué hace — actualiza snapshots sin recalcular todo, con la garantía de que cada ejecución coincida con un resultado idéntico al del full.
  3. Cómo funciona — full (fallback) · período (ventana reciente) · clave/watermark (delta + upsert) · backfill (ventana amplia / 1.ª extracción) · checkpoint (reanudación).
  4. Plan · Permiso — núcleo · verificación de acceso · interruptores de apagado para ejecución de ingesta / actualización de paneles / consultas en la consola de datos.
  5. Costo — el incremental existe para reducir costos (menos bytes leídos → menor costo estimado); el tope de volumen por consulta siempre protege.
  6. Límites — ventana de período default 7 / tope 400 días; paginación con tope de 10.000 páginas / 5.000.000 filas; cursor ≤ 64 caracteres.
  7. Seguridad — nombres de columna validados como identificadores; literal de cursor anti-inyección; alcance por workspace en la carga.
  8. Cómo validar — en la consola, activa el incremental en un visual de serie temporal y confirma que el número del refresh incremental coincide con el del refresh completo; fuerza una condición no elegible y confirma que el producto recurre al full (por la seguridad del número).
  9. En resumen — incremental por período y por clave, con el mismo resultado que el full; cuando no se puede garantizar, el producto recurre al full.

Enlaces relacionados