Lee antes: Modos de carga · Referencia: incremental y backfill.
Qué es#
La carga incremental por watermark trae solo las filas nuevas desde la última
ejecución, usando una columna creciente (una fecha de actualización o un id) como marca
de agua. Es mucho más barata que el full y, por construcción, produce el mismo resultado.
Esto no es CDC. Es una comparación por marca de agua (
columna > última marca). El CDC real (INSERT/UPDATE/DELETE del log de la fuente) es Roadmap — no existe hoy.
Para qué sirve#
Mantener actualizada una tabla grande que crece/se actualiza (pedidos, eventos, asientos) sin releer todo el histórico en cada refresh.
Cuándo usar / cuándo no usar#
- Úsalo cuando: hay una columna creciente y confiable (ej.:
atualizado_em,id) y las filas antiguas no desaparecen de la origen. - No lo uses cuando: la fuente borra filas sin señal de borrado — usa el modo por período (vuelve a buscar días completos) o un full. Ver "Borrado" más abajo.
Plan y permisos#
- Núcleo · verificación de acceso · interruptores de apagado para ejecución de ingesta, actualización de paneles y consultas en la consola de datos.
Requisitos previos#
- Una fuente conectada con al menos una carga full ya hecha (el snapshot base).
- Una columna de watermark: creciente, sin huecos hacia atrás. Buenas opciones:
atualizado_em(timestamp) o unidsecuencial.
Cómo funciona por dentro#
- Pull de base de datos / BigQuery: paginación KEYSET (seek) —
WHERE wm > <última marca> ORDER BY wm ASC, avanzando la marca al mayor valor del último lote. Estable aunque la fuente cambie durante la extracción (a diferencia deOFFSET). El valor de la marca entra como parámetro nombrado según el engine (Postgres$1, SQL Server/BigQuery@since, MySQL?, Oracle:since), nunca concatenado. - Refresh de widget/mart: guarda la marca de agua del snapshot anterior y hace un UPSERT
por clave con el delta; el histórico se reaprovecha. El predicado es
>=a propósito (vuelve a buscar la fila exactamente en la marca; el upsert es idempotente y no pierde la frontera).
Paso a paso#
- Asegura una carga full inicial de la fuente/tabla (el snapshot base).
- En la configuración de la fuente/tabla (o del widget de serie temporal), activa el modo
incremental e indica la columna de watermark (ej.:
atualizado_em). - Guarda y ejecuta el refresh. Ingestia busca solo el delta (
> marca) y hace upsert. - Valida la identidad: ejecuta un refresh incremental y un refresh completo y confirma que los números cuadran. Si no pueden cuadrar con seguridad, el producto rechaza el incremental y hace el full (con el motivo en el log) — eso es lo esperado.
Ejemplo (sintético)#
Tabla pedidos con id y atualizado_em:
Modo: incremental
Coluna de watermark: atualizado_em
Chave de upsert: idConsulta de delta que arma Ingestia (PostgreSQL, conceptual):
SELECT * FROM "public"."pedidos"
WHERE "atualizado_em" > $1 -- $1 = última marca de agua
ORDER BY "atualizado_em" ASC
LIMIT 5000; -- un fragmentoLa marca de agua avanza al mayor atualizado_em del lote; el siguiente fragmento
continúa donde se quedó.
Resultado esperado#
- Cada refresh lee muchos menos datos (solo el delta) y el resultado es idéntico al full — mismas filas, mismo orden.
- Sin un cursor utilizable en el snapshot anterior, Ingestia graba
nully el siguiente refresh pasa al full (seguro).
Semántica de borrado (limitación asumida)#
El merge es un UPSERT. Sin señal de borrado, el incremental no elimina una clave que desapareció de la origen (el mismo contrato de dbt/Power BI). Para restaurar la exactitud ante borrados:
- usa particiones completas (vuelve a buscar la partición entera y elimina la clave ausente); o
- proporciona tombstones (claves borradas explícitas); o
- usa el modo por período (vuelve a buscar días completos); o
- haz un full periódico.
Límites y costos#
- Ventana por período (cuando aplica): por defecto 7 días, tope 400.
- Paginación: tope de 10.000 páginas / 5.000.000 filas.
- Literal de cursor: ≤ 64 caracteres, sin comillas/barra/salto de línea.
- El incremental existe para reducir costos; el tope de bytes facturables protege siempre.
Seguridad#
- Los nombres de columna (clave/cursor) se validan como identificadores simples antes del SQL.
- Valor del cursor por bind (parámetro nombrado); el literal rechaza comillas/barra/salto de línea.
- Compatibilidad N−1: un lector nuevo lee un snapshot antiguo (sin cursor) sin romperse — y, ante él, rechaza el incremental y hace full.
Errores comunes#
| Síntoma | Causa probable | Qué hacer |
|---|---|---|
| Siempre pasa al full | sin snapshot anterior, o sin cursor válido | Haz la 1.ª carga full; elige una columna realmente creciente |
| Faltan las filas borradas en la origen | el watermark no ve borrados | Usa período/particiones completas/tombstones o full |
| Los números no cuadran con el full | orden/clave incorrectos | Asegura ORDER BY = clave ASC; revisa la clave de upsert |
| Cursor rechazado | valor > 64 caracteres o con comillas | Usa una columna de watermark simple (fecha/id) |
Solución de problemas#
- Compara lado a lado el resultado del refresh incremental y el del full.
- Lee el motivo en el log cuando el producto recurre al full — dice exactamente qué condición de elegibilidad no se cumplió.
Relacionados#
Última revisión: 2026-09-08.