Lee antes:
README.md. Capas del medallón enpipeline-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:
- resultado particionable por la columna de período (cada partición se calcula sola);
- la consulta ordena por la columna de período, ASC, como 1.ª clave (histórico + reciente ya salen en el orden del full);
- 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)#
- Estado — disponible. La elegibilidad y la igualdad de resultado entre incremental y full están cubiertas por pruebas automáticas.
- 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.
- Cómo funciona — full (fallback) · período (ventana reciente) · clave/watermark (delta + upsert) · backfill (ventana amplia / 1.ª extracción) · checkpoint (reanudación).
- 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.
- Costo — el incremental existe para reducir costos (menos bytes leídos → menor costo estimado); el tope de volumen por consulta siempre protege.
- 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.
- Seguridad — nombres de columna validados como identificadores; literal de cursor anti-inyección; alcance por workspace en la carga.
- 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).
- 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.