Lee antes:
conceitos-fluxo-de-dados.md. Referencia detallada:ingestao-incremental-backfill.md.
La regla que no se puede romper#
Existe una única invariante detrás de todos los modos incrementales: 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 el motivo en el log).
"Un refresh caro es un problema de costo; un número equivocado es un problema de producto."
Los tres modos, en lenguaje de negocio#
Full (completa)
Recalcula todo, desde cero. Es el fallback seguro siempre disponible: cualquier rechazo de un modo incremental cae aquí. Correcta por definición, es la más cara.
- Úsala cuando: es la 1.ª carga; la tabla es pequeña; la fuente borra filas y no tienes señal de borrado; o quieres la máxima garantía de exactitud.
Incremental por watermark (marca de agua)
Guarda la marca de agua — el mayor valor de una columna que solo crece (una fecha de
actualización, un id secuencial) — y, en la próxima ejecución, busca solo las filas nuevas
(columna > marca). El resto del histórico se reutiliza intacto.
En el pull de base de datos, esto se hace por KEYSET (seek): la consulta ordena por la columna de
watermark (ORDER BY wm ASC) y filtra WHERE wm > <última marca>, avanzando la marca
al mayor valor del último lote. A diferencia de paginar por OFFSET, el KEYSET es
estable incluso si la fuente cambia durante la extracción.
- Úsalo cuando: la tabla es grande y solo crece/se actualiza (pedidos, eventos, asientos) y existe una columna creciente confiable.
- No lo uses cuando: la fuente elimina filas físicamente sin dejar rastro (consulta "Semántica de borrado" más abajo) o no hay una columna creciente estable.
Backfill (carga histórica)
Traer el histórico anterior a la ventana incremental — por ejemplo, los últimos 24 meses cuando el incremental solo mira los últimos días.
- Cómo: ampliar la ventana reciente (en el incremental por período) o ejecutar un full una vez. En el pull de base de datos/BigQuery, la primera extracción ya es el backfill: recorre la paginación hasta el tope y las ejecuciones siguientes retoman desde el watermark.
- Úsalo cuando: acabas de conectar una fuente, cambiaste la regla de negocio o necesitas reprocesar un período específico.
Cuál elegir (guía rápida)#
| Situación | Modo recomendado |
|---|---|
| Primera carga de una fuente | Full (es el backfill inicial) |
Tabla grande que solo crece, con fecha/id creciente | Incremental por watermark |
| Tabla pequeña (pocos miles de filas) | Full (simple y suficientemente barato) |
| Fuente que borra filas sin señal de borrado | Full (o período volviendo a buscar días enteros) |
| Necesitas reprocesar un histórico antiguo | Backfill (ventana amplia o full puntual) |
Watermark no es CDC (honestidad)#
Esto es importante y el producto lo deja explícito:
- Watermark (lo que existe hoy): compara una columna creciente y trae el delta con
>. Es simple, robusto y barato — pero no ve los borrados y depende de que la columna realmente crezca. - CDC — Change Data Capture: leer el log de transacciones de la fuente para capturar cada INSERT/UPDATE/DELETE. Todavía no está disponible en Ingestia. No confundas los dos: cuando esta documentación habla de "carga incremental", es siempre por watermark.
¿Necesitas datos más frescos que el lote diario? El micro-lote ejecuta la carga incremental por watermark cada 5 o 15 minutos (planes Business y Scale) — es la opción de casi tiempo real del producto. Ver Micro-lote.
Semántica de borrado (limitación asumida)
En el refresh incremental de snapshot (widget/mart), el delta entra por UPSERT
por clave; en la capa Bronze no hay upsert ni MERGE — la ventana se borra en el
destino y se vuelve a agregar (DELETE de la ventana + agregado). En ninguno de los dos el
incremental elimina una clave que desapareció del origen sin una señal de borrado — el
mismo contrato de herramientas como dbt y Power BI. Dos señales opcionales restauran la exactitud ante borrados:
- particiones completas — dentro de una partición que se vuelve a buscar entera, la clave antigua ausente del delta se elimina;
- tombstones (claves borradas) — borrados explícitos, cuando el origen los proporciona.
Un dato cuyo origen borra filas no debe usar watermark puro. Usa el modo por período (vuelve a buscar días enteros) o haz un full.
Por qué el incremental "rechaza y hace full"#
El producto prefiere un refresh caro a un número equivocado. Recurre al full, con un motivo legible en el log, cuando: no hay snapshot anterior; el snapshot está truncado/vacío/con error; no hay columna de cursor utilizable; el orden no es exactamente la clave ASC; o el delta no se puede recortar con seguridad. Esto es una funcionalidad, no una falla.
Límites y costos#
- Ventana incremental por período: default 7 días, tope 400.
- Paginación de extracción: tope duro de 10.000 páginas / 5.000.000 filas.
- Fragmentación del pull de base de datos:
batchSizedefault 5.000 (entre 100 y 50.000);maxRowsdefault 200.000 (hasta 5.000.000). - Literal de cursor: ≤ 64 caracteres, sin comillas/barra/salto de línea (anti-inyección).
- El incremental existe para reducir costos (menos bytes leídos). Los valores de costo en pantalla son estimaciones; el monto cobrado es el de la factura.
Seguridad#
Los nombres de columna (clave/cursor) se validan como identificadores simples antes de entrar en el SQL; el valor del cursor usa bind por engine (parámetro nombrado), nunca concatenación. Alcance por workspace en toda la carga.
Relacionados#
- Referencia: full, incremental, backfill y checkpoint
- Tutorial: pipeline incremental por watermark
- Tutorial: ejecutar un backfill
- Cómo fluyen los datos (visión general)
- Micro-lote — actualizar cada 5 o 15 minutos
Última revisión: 2026-10-05.