Ingesta en Data 360: Style Guide | Cleon

Esta es la página donde Cleon deja de describir qué es la ingesta en Data 360 (antes Data Cloud) y empieza a decir qué hacemos con ella. Salesforce define las fuentes y los modos. Las páginas de referencia de esta subcategoría documentan cada una — el Data Stream, los connectors, la Ingestion API, full refresh versus upsert — y los gotchas documentan dónde una ingesta de apariencia limpia silenciosamente aterriza la data equivocada. Este Style Guide es la disciplina que mantiene confiable a un Data Stream, porque todo lo que está downstream — identidad, query, segmentación, los agentes que apoyás sobre él — hereda lo que sea que ingeriste.

Usalo como checklist antes de que cualquier Data Stream nuevo se publique. Las reglas son cortas a propósito — cuando una regla necesita explicación, la explicación está en la página que linkea. Una pregunta está en el centro, y se descompone en tres que respondés en orden.

La decisión central: ¿cómo debería aterrizar esta fuente?

Cada fuente nueva fuerza la misma decisión, y errarla es un rebuild, no un setting que cambiás. Un stream aterrizado en la cadencia equivocada es un bug de latencia o una factura desperdiciada; un stream aterrizado en el modo equivocado silenciosamente retiene registros que deberían haber desaparecido. La decisión tiene tres partes, y tienen un orden — frescura, después modo, después costo. Respondelas en voz alta antes de conectar el stream.

1. ¿Streaming o batch programado?

Decidí por la decisión downstream más fresca que la data alimenta — no por "más fresco es mejor" (principio 6). Si un consumidor downstream de verdad se equivoca con data obsoleta — una activación en tiempo real, un agente respondiendo sobre un cliente en medio de una sesión — la fuente necesita llegar de forma continua, y eso significa un camino de streaming: el patrón Streaming de la Ingestion API o el Web/Mobile SDK. Si la decisión más fresca que la data alimenta funciona bien en una agenda, es batch programado — un connector, un drop a S3 o cloud storage, o el patrón Bulk de la Ingestion API. Hacer streaming de una fuente que un batch nocturno serviría es costo desperdiciado; refrescar a diario detrás de una decisión en tiempo real es un bug de latencia. Nombrá la decisión más fresca primero, después elegí el camino que la cumple.

2. ¿Full refresh o upsert?

Esta es la bifurcación de corrección, y tiene un prerrequisito que la mayoría de los equipos saltean: no podés elegir upsert hasta que puedas nombrar la primary key y la historia de deletes (refresh modes). El upsert inserta-o-actualiza sobre una key estable y única — más liviano e incremental, pero una key equivocada o no única silenciosamente duplica o sobrescribe, y por sí solo el upsert no elimina los registros borrados en la fuente. Un registro que desapareció de la fuente simplemente deja de llegar, y "deja de llegar" es el único caso que el upsert deja intacto — así que el registro borrado queda colgado, indistinguible de uno vivo, hasta que mandás un delete explícito. El full refresh re-aterriza el conjunto entero en cada corrida: más simple, captura los deletes por ausencia, pero es más pesado en una fuente grande (principio 11). Así que antes de elegir: ¿podés nombrar una key que sea genuinamente única y estable, y si la fuente puede borrar registros, cómo llega ese delete a Data 360? Si no podés responder ambas, no estás listo para upsert.

3. ¿La cadencia matchea la decisión — y el costo de procesamiento está justificado?

Las primeras dos respuestas fijan una cadencia; esta pregunta te hace defenderla (principios 6 + 11). La cadencia tiene que matchear la decisión más fresca que la data alimenta — y el procesamiento que implica tiene que valer la pena. Un full refresh diario de una fuente de un millón de filas detrás de un reporte semanal es una decisión de costo disfrazada de setting de agenda; un refresh por hora alimentando una decisión que se revisa una vez al día paga por frescura que nadie consume. Seteá la cadencia a la decisión, confirmá que el modo y el volumen vuelven esa cadencia costeable, y dejá la cadencia por escrito al lado del stream para que el próximo no asuma que el DLO está actual cuando está en un reloj de 24 horas.

Esta es la misma disciplina de frescura que el Style Guide de Segmentación aplica una capa más afuera — seteá la cadencia a la decisión más fresca que la data alimenta, nunca a "lo más fresca posible" — aplicada al frente del ciclo de vida en lugar del fondo. La ingesta es donde empieza: una ingesta obsoleta o mal keyeada aparece como un bug downstream tres capas más allá (ingesta y el ciclo de vida).

Disciplina de modo

Nombrá la primary key antes de elegir upsert — es el contrato, no un detalle

La key es lo que le dice al stream si un registro entrante es uno que ya tiene o uno nuevo (refresh modes). Una key no única (dos registros reales comparten un valor) significa que un upsert silenciosamente sobrescribe al otro y perdés un registro sin error. Una key equivocada (un campo que en realidad no es estable) significa que el mismo registro llega pareciendo nuevo y silenciosamente duplica. Ambas parecen una corrida verde y sana. Verificá que la key sea genuinamente única y estable contra data real antes de que el stream salga a vivo — esto es el principio 1, modelá las keys, aplicado en la ingesta (relaciones y keys).

Resolvé la historia de deletes como mitad de la decisión de modo, no como un parche posterior

Un full refresh captura los deletes por ausencia; un upsert no los maneja para nada por sí solo. Si un stream está en upsert y la fuente puede borrar registros, necesitás una estrategia de deletes deliberada antes de que salga a vivo — de lo contrario el registro obsoleto fluye downstream hacia identity resolution, segmentos y activaciones, y alguien que debería haber sido removido termina contactado, sin error en todo el camino. Si la fuente puede borrar y no hay forma de señalar esos deletes, el full refresh es el modo más seguro a pesar de su costo.

Aterrizá la fuente cruda — no la reformes adentro del stream

Un Data Stream aterriza un DLO (__dll); no modela nada. El instinto de "arreglar" una fuente desprolija reformándola adentro del stream es la capa equivocada — aterrizala cruda, después reformá en el camino al DMO donde la transformación es visible y está documentada. Ese paso de modelado le pertenece a Data Architecture, no a la ingesta (mapping); un stream que silenciosamente limpia data es un stream cuya lógica nadie downstream puede ver (principio 2).

Disciplina de categoría y costo

Seteá la categoría del stream a lo que la data es, no a lo conveniente

La categoría de un stream — Profile, Engagement u Other — restringe cómo se comporta la data downstream, y es la primera decisión de modelado que tomás aunque ocurra en la ingesta (data streams). La data de eventos aterriza como Engagement (serie temporal, y requiere un campo de event-time), no como Profile. El error clásico es aterrizar eventos como un stream Profile: ingiere, parece bien, y después la segmentación por ventana de tiempo y las métricas de engagement no tienen sobre qué pararse. Elegí la categoría por la forma real de la data, antes de que el stream se conecte (principio 1).

Matcheá la cadencia a la decisión, y revisá los streams caros

El costo en Data 360 escala con lo que procesás, no con lo que almacenás (principio 11), y el procesamiento de un stream es lo que sea que cada refresh mueve. Una fuente grande en un full refresh frecuente es una factura recurrente; un stream demasiado frecuente alimentando una decisión que nadie revisa tan seguido es frescura pagada y no consumida. Seteá la cadencia a la decisión más fresca que la data alimenta, preferí el delta más liviano del upsert cuando tenés una key confiable y el volumen lo justifica, y revisá los streams que mueven más — el refresh más barato es el que no necesitaste correr.

Preferí un connector antes que la Ingestion API; verificá la lista de connectors de la org

Si un connector empaquetado cubre la fuente, usalo — está configurado, no codeado, y maneja la auth y el descubrimiento de schema por vos. Agarrá la Ingestion API solo cuando ningún connector encaja: una app custom, un servicio interno, un stream de eventos propio. Y como el catálogo de connectors se mueve release a release, confirmá lo que la org de verdad tiene antes de diseñar alrededor de cualquier connector; un diseño que nombra un connector que la org no puede habilitar es un rebuild que descubrís tarde.

Patrones a preferir

La decisión downstream más fresca nombrada primero, después el camino streaming-o-batch elegido para cumplirla — no "más fresco es mejor".
Batch programado en full refresh como default, del que te corrés solo cuando podés justificar streaming o nombrar una key para upsert.
La primary key nombrada y verificada única-y-estable antes de elegir upsert, contra data real.
La historia de deletes resuelta como mitad de la decisión de modo — cómo un delete de la fuente llega a Data 360, o full refresh en su lugar.
La categoría del stream seteada a la forma real de la data — data de eventos como Engagement con su campo de event-time, no Profile.
Un connector preferido por sobre la Ingestion API cuando existe uno, con la lista disponible de la org verificada primero.
La cadencia de refresh escrita al lado del stream, no guardada en la memoria de alguien.

Patrones a rechazar

Un stream refrescado a diario detrás de una decisión en tiempo real — un bug de latencia que aparece tres capas downstream.
Una fuente en streaming donde un batch nocturno serviría — costo pagado por frescura que nadie consume.
Upsert elegido sin una key nombrada — una corrida verde que silenciosamente duplica o sobrescribe y pierde registros sin error.
Upsert sobre una fuente que puede borrar, sin señal de delete — registros fantasma que quedan colgados y hacen que se contacte a alguien que debería haber sido removido.
Data de eventos aterrizada como un stream Profile — ingiere bien, después la segmentación por ventana de tiempo no tiene sobre qué pararse.
Una fuente reformada adentro del stream en lugar de aterrizada cruda y modelada en el camino al DMO, donde la lógica es visible.
Un build cableado a un connector que nadie confirmó que la org tenga habilitado.

El checklist de pre-ship antes de que cualquier Data Stream se publique

[ ] La decisión downstream más fresca que la data alimenta está nombrada, y el camino streaming-o-batch se eligió para cumplirla — no "lo más fresca posible".
[ ] El modo de refresh se eligió a propósito — upsert solo si hay una primary key única y estable nombrada; full refresh de lo contrario.
[ ] Si es upsert: la primary key está verificada como genuinamente única y estable contra data real, no asumida.
[ ] La historia de deletes está resuelta — el full refresh captura deletes por ausencia, o una estrategia de delete explícita llega a Data 360 para una fuente de upsert que puede borrar.
[ ] La categoría del stream matchea la forma real de la data — data de eventos como Engagement con un campo de event-time, no Profile.
[ ] La cadencia matchea la decisión más fresca que la data alimenta, el costo de procesamiento está justificado, y la cadencia está escrita al lado del stream.
[ ] Un connector empaquetado se prefiere por sobre la Ingestion API donde existe uno, y la lista de connectors disponible de la org se verificó — no se asumió de una página.
[ ] La fuente aterriza cruda como un DLO; cualquier reformado se difiere al mapping DLO→DMO en Data Architecture, donde es visible.

Cuando todas tildan, el Data Stream está listo para publicar.

Relacionado

Gotchas de ingesta — las fallas silenciosas que estas reglas previenen, la versión de producción
Data Streams — la unidad de ingesta sobre la que se configura cada regla de acá: fuente, categoría, agenda
Connectors — las fuentes desde las que un stream ingiere, y por qué verificás la lista de la org antes de diseñar
La Ingestion API — Streaming versus Bulk, el camino programático cuando ningún connector encaja
Refresh modes — full refresh versus upsert, la primary key, y la trampa de los deletes en profundidad
Ingesta y el ciclo de vida — por qué todo lo downstream hereda lo que ingerís acá
Debuggear ingesta — cuando un stream aterriza mal: registros faltantes o duplicados, conteos equivocados, un stream que no refresca
Principios de Data 360 desde producción — las meta-reglas por encima de estos específicos (1, 6, 11)

Si encontrás una regla que falta — o una de estas reglas violada en nuestro trabajo público — escribí a hello@wearecleon.com. La agregamos, o la arreglamos y lo decimos.