Data 360 Query e Insights: Style Guide | Cleon

Esta es la página donde Cleon deja de describir qué es el query de Data 360 (antes Data Cloud) y empieza a decir qué hacemos con él. Salesforce define las superficies. Las páginas de referencia de esta subcategoría documentan cada una — el dialecto SQL, la Query API, los Calculated Insights, quién consume un resultado — y los gotchas documentan dónde engaña el instinto de SQL. Este Style Guide es la disciplina que mantiene confiable a un número una vez que un segmento, una activación y un agente están todos parados sobre él.

Usalo como checklist antes de que cualquier query o Calculated Insight 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 decisión está por encima de todas las demás, así que va primero.

La decisión central: Calculated Insight vs. Query en vivo

Casi toda elección de query en Data 360 se reduce a una bifurcación: ¿computás esta métrica una vez como un Calculated Insight y dejás que todos la recuperen, o la corrés en vivo a través de la Query API cada vez que se pide? Acertá esto y el resto de la subcategoría es detalle. Erralo y o pagás por recomputar el mismo número en cada consumidor, o congelás un pull de una sola vez en infraestructura que nadie mantiene.

Tres preguntas lo deciden. Respondelas en orden.

1. ¿Esta métrica la recupera más de un consumidor, o un solo consumidor repetidamente?

Un número que un segmento, una activación y un agente leen es un número que computás una vez y servís — un Calculated Insight. También lo es un número que un consumidor lee en cada refresh. En el momento en que "quién necesita esto" tiene más de una respuesta, o "cada cuánto" es "una y otra vez", ya pasaste el umbral de un CI. Un pull que pasa una vez, para un caller, sin plan de repetirse, es una llamada a la Query API — en vivo, no persistida, ida cuando vuelve.

2. ¿Necesita historia o un join al perfil, o es una métrica por ventana sobre eventos entrantes?

Lifetime value, cantidad de órdenes de todos los tiempos, un engagement score sobre meses — estos necesitan la historia completa y un join de vuelta al perfil resuelto. Eso es un Calculated Insight batch, y solo batch lo puede expresar. "Clicks en los últimos 30 minutos", un pico sobre el stream de eventos entrante sin atributo de perfil — esa es la ventana angosta que cubre un CI streaming, y agarrarlo sin conocer sus límites es el error clásico (ver Calculated Insights sobre batch vs. streaming). Si la métrica no es ninguna de las dos — una forma genuinamente ad-hoc que no conocés de antemano — es una llamada Query API en vivo, no un CI en absoluto.

3. ¿Qué tan fresca tiene que ser?

La frescura no es "lo más fresca posible". Es tan fresca como la decisión más fresca que el número alimenta. Una métrica que un humano revisa una vez al día no necesita un recompute por hora; un trigger en tiempo real no puede esperar a un batch diario. El requisito de frescura setea la cadencia del CI — o, si la respuesta es "exactamente ahora, cada vez", te empuja a un query en vivo. Decidilo a propósito y dejalo por escrito.

Esto es el principio 7 (data-cloud-principles) planteado como una decisión que tomás en el teclado: computá una vez, recuperá muchas. La Query API es para preguntas hechas una vez, por código; un Calculated Insight es para una respuesta recuperada muchas veces, por todos.

Convenciones de SQL

Las convenciones que mantienen legible y correcto a un query de Data 360 un año después de escrito. Cada una es una regla; la página del dialecto carga el detalle.

Consultá DMOs, no DLOs

Construí cada query sobre el DMO armonizado, no sobre el DLO crudo. Un query contra un DLO hereda el naming y el desorden del sistema source, y se rompe en silencio el día que ese source renombra una columna (ver gotchas — gotcha 1). El lake es una zona de aterrizaje, no una superficie de query.

Usá identificadores con namespace `ssot__`, sin comillas — entrecomillá solo cuando tenés que

Los identificadores de Data 360 cargan el namespace ssot__ y los sufijos __dlm / __dll / __cio, y son case-mixed. Escribilos sin comillas por legibilidad; agarrá las comillas dobles solo cuando un nombre de otro modo plegaría su case o colisiona con una palabra reservada. Entrecomillá la excepción, no la regla.

Preferí agregaciones de un solo objeto

Un Calculated Insight, y la mayoría de los queries, leen más limpio como una agregación sobre un objeto en el grain correcto. Los CIs multi-objeto son reales y necesarios, pero cada join es una dependencia de una relación modelada — mantené la forma tan plana como la métrica lo permita, y agregá objetos solo cuando el número genuinamente lo requiere.

Traversá source → unified a través de `IndividualIdentityLink__dlm` — nunca un join directo

Un objeto source-aligned no se une directo a UnifiedIndividual__dlm. El camino pasa por el bridge IndividualIdentityLink__dlm que mantiene la resolución de identidad (los nombres exactos de link y campo source siguen el modelo de tu org). Un join directo no es un camino que el motor ofrezca — y un traversal que nadie modeló es una pregunta que el query simplemente no puede hacer (ver gotchas — gotcha 8).

Acordate de que crear un CI usa un dialecto distinto que leer el CIO

Crear un Calculated Insight usa un dialecto SQL distinto del que usás para leerlo de vuelta. Salesforce lo documenta sin vueltas. Crear un CI tiene sus propias reglas y — para streaming — la sintaxis WINDOW; leer el CIO resultante es Data Cloud SQL común. Una función que anda en uno puede no existir en el otro. No los confundas.

Disciplina de costo

Procesá menos — el costo escala con lo que procesás, no con lo que almacenás

Data 360 factura el trabajo: las filas que un query escanea, la data que un CI recomputa — mucho más que la data en reposo (principio 11). Un CI que re-agrega el perfil entero cada hora, o un segmento que escanea todo en cada refresh, es una decisión de costo disfrazada de decisión de lógica. Diseñá para cuánto procesás, y revisá los caros. El query más barato es el que no corriste — y el segundo más barato es el Calculated Insight que computaste una vez en lugar de re-derivar en cada consumidor.

Disciplina de frescura

Seteá la cadencia de un CI a la decisión más fresca que alimenta — y dejá la cadencia por escrito

Un Calculated Insight está exactamente tan fresco como su última corrida, y la obsolescencia es silenciosa: entre corridas sirve el último número que computó, con nada en el consumidor que diga que el mundo se movió (principio 6). Seteá la cadencia a la decisión más fresca que el CI alimenta — no a "lo más seguido posible", que paga por frescura que nadie consume, y no a un batch diario detrás de un trigger en tiempo real. Después dejá la cadencia por escrito al lado del CI, para que el próximo no asuma real-time donde hay un lag de 24 horas.

Patrones a preferir

Un Calculated Insight para cualquier número leído por más de un consumidor — computá una vez, recuperá muchas.
CIs batch por default, streaming solo cuando la métrica es genuinamente una reacción por ventana sobre el stream de eventos.
Agregaciones de un solo objeto en el grain en el que la métrica es realmente verdadera.
Identificadores ssot__ sin comillas, entrecomillando solo la excepción case-mixed o reservada.
El loop de recuperación completo en cada llamada a la Query API — paginá hasta done, o polleá el queryId hasta el final — escrito incluso cuando el resultado de hoy entra en una página.
La cadencia escrita al lado del CI, en la doc del modelo, no en la memoria de alguien.

Patrones a rechazar

Un query en vivo re-corrido en cada consumidor para un número que debería ser un CI.
Streaming agarrado porque "real-time es mejor" antes de chequear que no puede hacer join al perfil ni sostener un horizonte de lifetime.
Un query o CI contra un DLO cuando un DMO expresa el significado.
Un join directo de un objeto source a UnifiedIndividual__dlm en lugar del traversal por IndividualIdentityLink__dlm.
Leer la página uno de la Query API y frenar — el peor tipo de error, porque los números se ven plausibles.
Una cadencia de CI seteada a "lo más fresca posible" en lugar de a la decisión que alimenta — un recompute demasiado ansioso es una factura recurrente.
"El grain lo vemos después". El grain es la métrica; erralo y cada consumidor hereda el número equivocado, en silencio.

El chequeo de agent-readiness

El lector más moderno de tu capa de query es un agente — Agentforce o un LLM externo. No recomputa una métrica; recupera el Calculated Insight que definiste, heredando su grain, su frescura y su correctitud exactamente (principio 10). Un CI equivocado no hace dudar a un agente; lo vuelve confiadamente incorrecto, que es peor que un agente que no puede responder en absoluto. Antes de dejar que un agente se fundamente sobre un resultado de query, confirmá:

[ ] Las métricas compartidas que el agente va a citar existen como Calculated Insights que recupera — no valores que él (o una tool) recomputa en vivo.
[ ] Cada uno de esos CIs está definido en el grain en el que la métrica es realmente verdadera.
[ ] La cadencia de refresh de cada CI coincide con la frescura que implica la respuesta del agente.
[ ] Cada traversal que la métrica necesita corre por una relación modelada (source → unified vía IndividualIdentityLink__dlm).
[ ] El número reconcilia — estás contando unified individuals o filas source a propósito, no por accidente.

El test honesto debajo de los cinco: ¿un analista humano citaría este número sin una salvedad? Si no, un agente tampoco debería. "Query agent-ready" no es una feature que activás — es el estado en el que ya estás cuando los CIs son correctos, frescos y definidos en el grain correcto.

El checklist de pre-ship antes de que cualquier query o CI se publique

[ ] La decisión computar-vs-recuperar se tomó a propósito — CI si es recuperado-muchas o histórico, Query API si es de una sola vez o en vivo.
[ ] CI: batch vs. streaming elegido por la métrica (historia/join al perfil vs. eventos por ventana), no por la aspiración.
[ ] CI: el grain está declarado y es correcto — las dimensiones expresan exactamente el grain en el que la métrica es verdadera.
[ ] CI: la cadencia de refresh está seteada a la decisión más fresca que alimenta, y escrita al lado.
[ ] El query lee DMOs, no DLOs; los identificadores tienen namespace ssot__ y van sin comillas salvo donde deben entrecomillarse.
[ ] Cada traversal source → unified corre por IndividualIdentityLink__dlm, y cada join corresponde a una relación modelada.
[ ] Query API: el caller maneja el loop de recuperación completo — paginá hasta done o polleá el queryId hasta el final — incluso si el resultado entra en una página hoy.
[ ] El número reconcilia contra el objeto que quisiste contar (unified individuals vs. filas source).
[ ] El chequeo de agent-readiness de arriba sigue pasando.

Cuando todas tildan, el query o el CI está listo para publicar.

Relacionado

Gotchas de Query e Insights — dónde engaña el instinto de SQL, la versión de producción
Data Cloud SQL — el dialecto al que aplican estas convenciones
Bridging desde Marketing Cloud SQL — el crosswalk para el veterano de MC SQL
Calculated Insights — el lado "computá una vez, recuperá muchas" de la decisión central
La Query API — el lado "consultá en vivo cada vez" de la decisión central
Consumir resultados de query — quién recupera un CI, y por qué todos leen el mismo
Debuggear resultados de query — cuando un número vuelve mal, en blanco, o corto
Principios de Data 360 desde producción — las meta-reglas por encima de estos específicos (6, 7, 10, 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.