Skip to main content

La Query API de Data 360: correr SQL sobre el modelo desde código

El lado programático de Data Cloud SQL: correr una query viva sobre el modelo unificado desde código y recibir filas de vuelta. Las dos superficies — la Query API v2 síncrona con su cursor nextBatchId, y la nueva Query Connect API asíncrona con un queryId y paginado por offset — el flujo de auth a alto nivel, las restricciones de tiempo que Salesforce impone, y cuándo una query viva le gana a un Calculated Insight.

Referencia·Actualizado 2026-06-01·Escrito por Lira · Editado por German Medina

La Query API es cómo corrés Data Cloud SQL desde código en vez de desde el Query Editor. El mismo dialecto, los mismos DMOs sobre el perfil unificado — la diferencia es que un programa envía la query y lee las filas de vuelta, así que puede exportar, integrar, o alimentar otro sistema. Este es el lado de "query viva cada vez" del ancla de la subcategoría; el otro lado es el Calculated Insight, que computa una métrica una vez y la sirve en todos lados. Esta página es la referencia del lado vivo: las superficies, el modo de falla, y la decisión de cuándo agarrarla.

Hay dos superficies, y cuál apuntás cambia cómo leés los resultados. Las dos hablan el dialecto Data Cloud SQL; ninguna cambia el modelo de abajo. Lo que cambia es si la llamada es síncrona o asíncrona — y ese solo hecho es donde se pierden las filas.

Las dos superficies

Query API v2 — POST /api/v2/query. La superficie clásica, síncrona: posteás un body con un string sql y la primera respuesta ya trae filas. Los resultados vuelven en batches de cursor. La respuesta incluye el array de data, un rowCount, un bloque metadata que describe las columnas, un nextBatchId, y un boolean done. Mientras done sea false, hay otro batch para traer vía nextBatchId; cuando done es true, tenés el result set completo. El cursor es forward-only — lo caminás hasta el final o te quedás corto.

// Query API v2 — forma de una respuesta paginada (conceptual, campos recortados)
{
  "data": [ /* un objeto por fila */ ],
  "rowCount": 5000,
  "done": false,          // hay más — seguí
  "nextBatchId": "abc123", // traé el próximo batch con esto
  "metadata": { /* tipos de columna y orden */ }
}

Query Connect API — /ssot/query-sql, introducida en agosto de 2025. La superficie nueva, hecha para trabajo más grande y de corrida más larga, y asíncrona en su forma: enviás la query y recibís un queryId, después polleás el status y recuperás las filas por separado. La paginación acá es por filas, no por cursor — pedís una ventana con un offset y un rowLimit (por ejemplo, 2.000 filas por vez de un result set de 100.000), y paginás avanzando el offset. Corre sobre el motor Hyper de Salesforce, mantiene los resultados disponibles hasta 24 horas para que paginés sobre ellos sin volver a correr, y Salesforce la posiciona como la superficie que las integraciones nuevas deberían apuntar.

// Query Connect API — submit devuelve un handle; polleás y paginás por filas
{
  "queryId": "f1e2d3...",  // trackeá el status y traé filas contra esto
  "done": false            // polleá hasta que la corrida termine, después paginá offset/rowLimit
}

La lectura práctica: v2 es el camino más corto para una query cuyo resultado entra en un puñado de batches síncronos; Query Connect es la que querés cuando el resultado es grande, la corrida es larga, o necesitás paginar sobre él de vuelta. De cualquier forma la obligación es la misma — leer más allá de la primera respuesta.

La paginación y el async son la superficie de falla

Este es el gotcha 7 de Query & Insights, y vale enunciarlo completo acá porque la Query API es justo donde muerde. El código que lee la primera respuesta y para no está consultando un resultado chico — está truncando silenciosamente uno grande. v2 te entrega el primer batch con done: false y confía en que vas a seguir nextBatchId; Query Connect te entrega un queryId y confía en que vas a pollear y paginar. En los dos casos el primer payload parece una respuesta válida y completa, porque estructuralmente es una respuesta válida — solo que parcial.

La disciplina es chica y no negociable: lo que sea que llame a la Query API maneja el loop de recuperación completo, no la primera página. Si un resultado es lo bastante chico para entrar en un batch síncrono de v2 hoy, escribí el loop igual — el día que la data crezca más allá de una página, el loop es la diferencia entre un export correcto y uno roto en silencio.

Qué enviás realmente

El request es un string SQL en el dialecto Data 360 (antes Data Cloud) — identificadores sin comillas, con namespace, DMOs sobre el perfil unificado. Aplica la misma disciplina de un solo objeto que usa el resto de esta subcategoría: consultá un objeto, contá lo correcto, y traversá a los registros de origen a través de IndividualIdentityLink__dlm en vez de unir UnifiedIndividual__dlm directo a un objeto de origen.

-- El tipo de SQL que corre la Query API: un solo objeto, perfil resuelto.
-- Contando individuos unificados, NO filas importadas crudas. El caller
-- igual pagina esto hasta el final aunque parezca chico — los resultados crecen.
SELECT
  i.ssot__Id__c          AS individual_id,
  i.ssot__FirstName__c   AS first_name
FROM UnifiedIndividual__dlm i
WHERE i.ssot__FirstName__c IS NOT NULL;

Fijate qué es cierto en las dos superficies: LIMIT en el SQL no te salva de la paginación. LIMIT acota el resultado que produce el motor; la paginación gobierna cómo ese resultado te lo entregan de vuelta. Un resultado con LIMIT 10000 igual llega en batches, y vos igual los caminás.

Auth, al nivel que necesitás

Te autenticás contra la Query API en dos movimientos, y la forma importa más que la sintaxis. Primero, una connected app te consigue un access token OAuth estándar de Salesforce — el scope cdp_query_api es el que autoriza correr ANSI SQL contra Data 360. Segundo, intercambiás ese token de Salesforce por un token de Data 360, y ese intercambio también te dice el endpoint propio de Data 360 de la org — un host único, generado por el sistema (el cdpInstanceUrl) que ninguna otra org comparte. Llamás a la Query API contra ese host, con el token de Data 360, y re-intercambiás antes de que el token expire en vez de por llamada.

Ese es el modelo conceptual entero: OAuth de entrada, token exchange a un token con scope de Data 360 más el endpoint de la org, después query. Los request bodies exactos, los nombres de header, y el manejo del refresh van en código que escribís contra la referencia de abajo, contra la connected app de tu org — no copiados y pegados de una página de docs. La forma es la parte durable; las teclas son tuyas.

Cuándo la Query API, y cuándo un Calculated Insight

Esta es la decisión ancla de toda la subcategoría, vista desde el lado vivo. Las dos superficies responden dos preguntas distintas, y el costo de confundirlas se acumula.

Agarrá la Query API cuando el trabajo es genuinamente vivo o de una sola vez: un pull ad-hoc que un humano pidió una vez, un export programático a un warehouse, una integración que necesita filas actuales on demand, una query cuya forma no sabés de antemano. No se persiste nada; obtenés exactamente las filas que el modelo tiene ahora mismo, y pagás el scan cada vez que la corrés.

Agarrá un Calculated Insight cuando la misma métrica la recuperan muchos consumidores — lifetime value, un engagement score, un conteo de órdenes por persona. Computarla una vez y dejar que segmentos, activaciones y agentes la recuperen es más barato, consistente y estable; correr esa misma agregación viva a través de la Query API en cada consumidor es más lento, cuesta más en cada llamada, y deriva a medida que dos callers la computan apenas distinto. La prueba honesta: si más de un consumidor necesita este número, o el mismo consumidor lo necesita repetidamente, es un Calculated Insight, no una query que volvés a correr. (El Style Guide encuadra este trade-off como convención; los principios de Data 360 — principio 7 — lo encuadran como la regla.)

Dicho sin vueltas: la Query API es para preguntas hechas una vez, por código; un Calculated Insight es para una respuesta recuperada muchas veces, por todos. Usá la superficie viva para trabajo vivo, y dejá de re-derivar al vuelo lo que podrías computar una vez.

Relacionado

Referencia: