Saltar al contenido

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

Actualizado el 2026-09-08

Tutorial — crear un pipeline incremental por watermark

Paso a paso para configurar una carga incremental por marca de agua (watermark), trayendo solo el delta con la garantía de cuadrar con el full.

En esta página (15)

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#

  1. Una fuente conectada con al menos una carga full ya hecha (el snapshot base).
  2. Una columna de watermark: creciente, sin huecos hacia atrás. Buenas opciones: atualizado_em (timestamp) o un id secuencial.

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 de OFFSET). 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#

  1. Asegura una carga full inicial de la fuente/tabla (el snapshot base).
  2. 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).
  3. Guarda y ejecuta el refresh. Ingestia busca solo el delta (> marca) y hace upsert.
  4. 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:

código
Modo: incremental
Coluna de watermark: atualizado_em
Chave de upsert: id

Consulta de delta que arma Ingestia (PostgreSQL, conceptual):

sql
SELECT * FROM "public"."pedidos"
WHERE "atualizado_em" > $1 -- $1 = última marca de agua
ORDER BY "atualizado_em" ASC
LIMIT 5000; -- un fragmento

La 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 null y 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íntomaCausa probableQué hacer
Siempre pasa al fullsin snapshot anterior, o sin cursor válidoHaz la 1.ª carga full; elige una columna realmente creciente
Faltan las filas borradas en la origenel watermark no ve borradosUsa período/particiones completas/tombstones o full
Los números no cuadran con el fullorden/clave incorrectosAsegura ORDER BY = clave ASC; revisa la clave de upsert
Cursor rechazadovalor > 64 caracteres o con comillasUsa 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.

Enlaces relacionados