Modos de refresh: full refresh vs upsert
El modo de refresh de un Data Stream decide cómo cada corrida reconcilia contra lo que ya aterrizó. El full refresh reemplaza el dataset entero en cada corrida y captura las bajas por ausencia; el upsert inserta-o-actualiza con una primary key — más liviano e incremental, pero una key equivocada o no única duplica o sobrescribe en silencio, y no elimina los registros borrados en el origen salvo que mandes las bajas explícitamente.
Todo Data Stream corre con un modo de refresh, y la elección es la decisión de correctitud de mayor riesgo en la ingesta. El modo decide una sola cosa: cómo una corrida nueva reconcilia contra los registros que el stream ya aterrizó en su Data Lake Object. Hay dos, y se comportan distinto justo en el lugar que duele — qué pasa con un registro que se fue del origen.
Esta página es la referencia de esa decisión en Data 360 (antes Data Cloud): qué hace cada uno, el full refresh y el upsert, por qué el upsert necesita una primary key, y el único comportamiento que convierte una ingesta de aspecto limpio en un perfil que miente — la forma en que las bajas se manejan, y no se manejan.
Full refresh: reemplazá el dataset entero en cada corrida
Un full refresh vuelve a aterrizar el dataset entero en cada corrida. El contenido previo del DLO queda reemplazado por lo que el origen devuelve esta vez; la corrida es la verdad nueva, completa.
Eso lo hace el modo más simple de razonar. No rastreás qué cambió — no hace falta, porque nada se arrastra. Lo que el origen tenga al momento de la corrida es lo que el DLO tiene después. El costo es el obvio: cada corrida mueve y procesa el dataset completo, aunque haya cambiado una fila, así que un origen grande en full refresh es más pesado que el cambio que capturó (principio 11 — el costo escala con lo que procesás).
La propiedad que más importa es cómo el full refresh maneja una baja: por ausencia. Un registro que existía en la corrida anterior y desapareció del origen en esta corrida simplemente no está en la carga nueva — así que después de la corrida, tampoco está en el DLO. Nunca mandás una señal de baja; la desaparición del registro del origen es la baja. Esta es la fuerza silenciosa del full refresh, y es exactamente lo que el upsert no te da gratis.
Upsert: insertar-o-actualizar sobre una primary key
Un upsert reconcilia de forma incremental. Cada corrida lleva un conjunto de registros, y por cada uno el stream hace una sola pregunta contra la primary key: ¿ya existe un registro con esta key? Si sí, actualizalo; si no, insertalo. Los registros que la corrida no menciona quedan intactos. Al upsert a veces se lo llama ingesta incremental por exactamente esto — aterrizás el delta, no el conjunto entero.
Eso es más liviano y rápido que un full refresh sobre un origen grande, porque movés solo lo que cambió. Pero todo el mecanismo descansa en que una cosa esté bien: la primary key. La key es lo que le dice al stream si un registro entrante es el mismo que ya tiene o uno nuevo. Acertá la key y el upsert es preciso. Erralá y las fallas son silenciosas.
La trampa: el upsert no elimina
Este es el único comportamiento para internalizar, porque es donde un error de modo de refresh aparece tres capas más abajo como datos que están, lisa y llanamente, mal.
Un full refresh captura las bajas por ausencia. Un upsert no. Un upsert solo inserta o actualiza — por definición toca un registro únicamente cuando ese registro está en la corrida. Un registro borrado del origen simplemente deja de llegar, y "deja de llegar" es justo el caso que el upsert deja intacto. Así que el registro borrado se queda en el DLO indefinidamente, con aspecto tan válido como uno vigente.
Así que la pregunta de las bajas no es un detalle que resolvés después — es la mitad de la decisión del modo de refresh. Antes de elegir upsert, contestala en voz alta: ¿este origen puede borrar registros, y si puede, cómo llega la baja a Data 360? Si la respuesta es "puede borrar y no hay señal de baja", el upsert va a retener fantasmas en silencio y un full refresh es el modo más seguro a pesar de su costo.
Cómo elegir
El intercambio es legible una vez que lo enunciás como las dos cosas que difieren:
- Peso y frecuencia. El full refresh mueve el dataset entero en cada corrida; el upsert mueve solo el delta. Sobre un origen grande y refrescado seguido, la diferencia es costo de procesamiento real (principio 11) — los full refresh demasiado frecuentes son una decisión de costo disfrazada de setting de schedule.
- Bajas y la key. El full refresh captura las bajas por ausencia y no necesita key para eso. El upsert necesita una primary key estable y única y una estrategia de bajas explícita si el origen puede remover registros. Nombrá las dos antes de comprometerte con upsert.
El default honesto: si no podés nombrar una key única y estable, no estás listo para upsert — usá full refresh. Si el origen puede borrar registros y no tenés forma de señalar esas bajas, un full refresh las captura gratis donde el upsert se quedaría con fantasmas en silencio. Agarrá el upsert cuando tenés una key confiable, el volumen hace que el full refresh sea un desperdicio, y ya decidiste cómo se manejan las bajas — no antes. El Style Guide de Ingestion recorre esto como la segunda de sus tres preguntas ordenadas.
Relacionado
- Data Streams — la unidad de ingesta sobre la que se configura el modo de refresh, y dónde se setea el modo
- Gotchas de ingestion — las fallas silenciosas, incluida la del upsert que retiene registros borrados y la de una key no única que duplica
- Relationships & keys — qué hace que una primary key sea única y estable, el prerrequisito del upsert
- Style Guide de Ingestion — "¿cómo debería aterrizar este origen?" — full refresh vs upsert como la segunda pregunta ordenada
Referencia: