Previsualizar

Previsualizar

Ejecuta una audience criteria contra BigQuery (acotada por limit) y devuelve una muestra de las filas reales que matchea más el total del universo. Un mismo motor sirve dos entradas:

• POST /api/audience-criterias/preview-from-body — ejecuta una definición enviada en el cuerpo (aún no persistida).
• POST /api/audience-criterias/:id/preview — ejecuta un criterio ya guardado, referenciado por su id.

Ambos devuelven la misma forma de respuesta: IPreviewAudienceCriteriaResult.

A diferencia de Generar SQL, preview no devuelve SQL; y a diferencia de Validar (que solo hace un dry-run), preview sí trae datos: corre la consulta y te muestra filas.

Auth: Requerida — permiso audience-criteria:view-sql (ambos endpoints).

POST /api/audience-criterias/preview-from-body

Ejecuta una definición enviada en el cuerpo, sin persistirla.

Auth: Requerida — permiso audience-criteria:view-sql

Cuerpo de la solicitud

Nivel raíz (PreviewFromBodyDto): la definición del criterio (CriteriaDefinitionDto) más el campo limit.

Definición del criterio

Es el mismo árbol que recibe Crear, sin los campos name/description. Se documenta aquí de forma autocontenida.

queryBlocks[] — bloque de consulta

Cada elemento de queryBlocks (CreateQueryBlockDto) es un statement SQL completo:

ColumnRefDto — referencia a columna

Se usa en todo el árbol (select, filtros, group by, joins, agregados, ventana temporal):

Toda columna se cualifica siempre con su table para evitar ambigüedad.

from — fuente de datos (FromDto)

Cada JoinDto:

Cada JoinPredicateDto es un par de columnas: { left: ColumnRefDto, right: ColumnRefDto }.

select — proyección (SelectDto)

Los items se discriminan por kind:

• Columna — kind: "column":

  Campo	Tipo	Requerido	Descripción
  kind	"column"	Sí	Discriminador.
  column	ColumnRefDto	Sí	Columna proyectada.
  alias	string	No	Debe matchear ^[A-Za-z_][A-Za-z0-9_]*$.

• Agregado — kind: "aggregate":

  Campo	Tipo	Requerido	Descripción
  kind	"aggregate"	Sí	Discriminador.
  aggregate	AggregateDto	Sí	Expresión de agregación.
  alias	string	Sí	Aquí el alias es obligatorio. Mismo regex de identificador.

AggregateDto:

where — árbol de predicados (WhereDto)

El where es un árbol recursivo. El nodo raíz es siempre un grupo:

• Grupo — { kind: "group", logicalOperator: LogicalOperatorEnum, children: (Predicado | Grupo)[] }. Se permiten grupos anidados (AND/OR a varios niveles).
• Predicado (hoja) — { kind: "predicate", column: ColumnRefDto, comparisonOperator: ComparisonOperatorEnum, value?: PredicateValue }.

Forma de value según comparisonOperator

ScalarValue = string | number | boolean. Además, cada operador debe ser compatible con el tipo de la columna (ver reglas de validación).

groupBy — columnas de agrupación

Lista opcional de ColumnRefDto[]. Cuando el bloque agrega (declara groupBy o tiene un agregado en el select), el groupBy debe coincidir exactamente con las columnas no agregadas del select (ver reglas de validación).

having — filtro sobre agregados (HavingDto)

Misma estructura recursiva que where (grupos AND/OR anidados y misma regla de value por operador), pero la hoja opera sobre un agregado, no sobre una columna:

• Predicado (hoja) — { kind: "predicate", aggregate: AggregateDto, comparisonOperator: ComparisonOperatorEnum, value?: PredicateValue }.
• Grupo — idéntico al de where.

timeWindow — ventana temporal (TimeWindowDto)

Unión discriminada por timeOperator. Acota el bloque a un período de tiempo sobre una columna TIMESTAMP del catálogo (reference). Es un campo hermano del where, no un nodo del árbol de filtros.

TimeUnitEnum: DAYS | WEEKS | MONTHS | YEARS.

Semántica de negocio de cada operador:

• ALL_TIME — sin ventana; considera todo el histórico.
• IN_THE_LAST — ventana rodante relativa a "ahora": los últimos value unit (p. ej. últimos 30 DAYS). Se recomputa en cada corrida.
• IN_THE_FIRST — ventana relativa al origen del ciclo de vida del usuario (su fecha de alta): los primeros value unit de vida de cada usuario. Se ancla por usuario, no a una fecha fija.
• SINCE — desde la fecha civil from (inclusiva) en adelante.
• BETWEEN — entre from y to, ambas fechas civiles inclusivas de su día completo.

composedWith[] — composición con otras audiencias

Cada elemento (CreateCompositionDto) combina esta definición con otra audiencia vía una operación de conjunto:

Ejemplo

Audiencia de usuarios con al menos una orden pagada en Chile o México, proyectando user_id y country. Se pide una muestra de 50 filas (limit).

curl -X POST https://api.reten.ai/api/audience-criterias/preview-from-body \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "AUDIENCE",
    "queryBlocks": [
      {
        "order": 0,
        "from": { "table": "orders", "joins": [] },
        "select": {
          "distinct": true,
          "items": [
            {
              "kind": "column",
              "column": { "table": "orders", "column": "user_id" },
              "alias": "user_id"
            },
            {
              "kind": "column",
              "column": { "table": "orders", "column": "country" },
              "alias": "country"
            }
          ]
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "orders", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "paid"
            },
            {
              "kind": "predicate",
              "column": { "table": "orders", "column": "country" },
              "comparisonOperator": "IN",
              "value": ["CL", "MX"]
            }
          ]
        }
      }
    ],
    "limit": 50
  }'

import axios from 'axios';

const body = {
  type: 'AUDIENCE',
  queryBlocks: [
    {
      order: 0,
      from: { table: 'orders', joins: [] },
      select: {
        distinct: true,
        items: [
          {
            kind: 'column',
            column: { table: 'orders', column: 'user_id' },
            alias: 'user_id',
          },
          {
            kind: 'column',
            column: { table: 'orders', column: 'country' },
            alias: 'country',
          },
        ],
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'orders', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'paid',
          },
          {
            kind: 'predicate',
            column: { table: 'orders', column: 'country' },
            comparisonOperator: 'IN',
            value: ['CL', 'MX'],
          },
        ],
      },
    },
  ],
  limit: 50, // opcional; por defecto 100
};

const response = await axios.post(
  'https://api.reten.ai/api/audience-criterias/preview-from-body',
  body,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>' } },
);
const preview = response.data; // IPreviewAudienceCriteriaResult

La respuesta se documenta en IPreviewAudienceCriteriaResult, con un ejemplo de rows no vacío.

POST /api/audience-criterias/:id/preview

Ejecuta un criterio ya guardado, referenciado por su id. La definición no viaja en el cuerpo: se toma del criterio persistido en el tenant. El cuerpo solo lleva limit.

Auth: Requerida — permiso audience-criteria:view-sql

Parámetros de ruta

Cuerpo de la solicitud

PreviewQueryDto — un único campo, opcional:

Un cuerpo vacío ({}) es válido: usa el limit por defecto (100).

Ejemplo

curl -X POST https://api.reten.ai/api/audience-criterias/f47ac10b-58cc-4372-a567-0e02b2c3d479/preview \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 50 }'

import axios from 'axios';

const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await axios.post(
  `https://api.reten.ai/api/audience-criterias/${id}/preview`,
  { limit: 50 }, // opcional; por defecto 100
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>' } },
);
const preview = response.data; // IPreviewAudienceCriteriaResult

limit — tamaño de la muestra

limit acota solo cuántas filas trae la respuesta en rows (la muestra que ves), no el universo que matchea la audiencia.

• Rango: entero 1..500 (menor a 1 o mayor a 500 ⇒ 400).
• Default: 100 (PREVIEW_ROW_LIMIT_DEFAULT) cuando se omite.

Respuesta — IPreviewAudienceCriteriaResult

Ejemplo

Respuesta 201 al ejemplo de arriba (limit: 50). La audiencia matchea 4821 usuarios; rows muestra los primeros 50 (aquí se recortan a 3 por brevedad), cada uno con las columnas proyectadas (user_id, country):

{
  "rows": [
    { "user_id": "u_9f3a1c", "country": "CL" },
    { "user_id": "u_2b7e04", "country": "MX" },
    { "user_id": "u_c081ff", "country": "CL" }
  ],
  "totalCount": 4821,
  "bytesProcessed": 5242880
}

Las claves de cada objeto en rows (user_id, country) salen de los alias del select: otra definición produciría otras columnas. totalCount (4821) es el universo completo, mayor que las 50 filas de la muestra.

Reglas de validación

Antes de ejecutar, la definición pasa por las mismas dos capas de validación que Crear, y ambas devuelven 400 Bad Request:

1. Validación del DTO (estructura, tipos, enums, campos requeridos, limit en rango). message es un arreglo de strings y se rechazan propiedades desconocidas (incluidos name/description).
2. Validación de negocio (la definición debe generar SQL válido y coherente contra el catálogo). message es un string único con la regla incumplida.

Respuestas de error