Saltar al contenido

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

Actualizado el 2026-10-05

Modos de carga — full, incremental por watermark y backfill

Cuándo usar carga completa, carga incremental por marca de agua (watermark) y backfill — y por qué la captura continua (CDC) todavía no está disponible.

En esta página (12)

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ónModo recomendado
Primera carga de una fuenteFull (es el backfill inicial)
Tabla grande que solo crece, con fecha/id crecienteIncremental por watermark
Tabla pequeña (pocos miles de filas)Full (simple y suficientemente barato)
Fuente que borra filas sin señal de borradoFull (o período volviendo a buscar días enteros)
Necesitas reprocesar un histórico antiguoBackfill (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: batchSize default 5.000 (entre 100 y 50.000); maxRows default 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#


Última revisión: 2026-10-05.

Enlaces relacionados