Crear Audience Criteria

POST /api/audience-criterias

Crea un Audience Criteria a partir de su definición completa. Es el endpoint central del recurso: recibe todo el árbol de la definición —bloques de consulta, proyección, filtros, ventana temporal, cruces, agregaciones y composiciones con otras audiencias— y lo persiste. La operación es transaccional: el criterio, sus query blocks y sus composiciones se crean juntos, o no se crea nada.

Auth: Requerida — permiso audience-criteria:create

Cuerpo de la solicitud

Nivel raíz (CreateAudienceCriteriaDto):

queryBlocks[] — bloque de consulta

Cada elemento de queryBlocks (QueryBlockDto) 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:

operand —lo que se agrega— se discrimina por kind:

ArithmeticOperatorEnum: ADD | SUBTRACT | MULTIPLY | SAFE_DIVIDE (una división que da NULL cuando el denominador es cero, en vez de hacer fallar la consulta). Las columnas de una expresión aritmética tienen que ser numéricas (INT64, NUMERIC, BIGNUMERIC, FLOAT64), y las expresiones se anidan hasta 3 niveles de arithmetic, contando el exterior.

where — árbol de predicados (WhereDto)

El where es un árbol recursivo. El nodo raíz es siempre un grupo, y sus hojas son de dos tipos:

Grupo — kind: "group"

Hoja de columna — kind: "predicate"

Compara una columna escalar cualificada por su tabla.

{
  "kind": "predicate",
  "column": { "table": "user_properties", "column": "country" },
  "comparisonOperator": "IN",
  "value": ["CL", "MX"]
}

Hoja de registro — kind: "recordPredicate"

Filtra por una columna RECORD REPEATED (un array de structs, como attributes). Significa existe al menos un elemento del array que cumple el sub-filtro.

{
  "kind": "recordPredicate",
  "column": { "table": "event_transactions", "column": "attributes" },
  "subWhere": {
    "kind": "group",
    "logicalOperator": "AND",
    "children": [
      { "kind": "predicate", "field": "key", "comparisonOperator": "EQUALS", "value": "canal" },
      { "kind": "predicate", "field": "value", "comparisonOperator": "EQUALS", "value": "web" }
    ]
  }
}

Qué columnas admiten un filtro de registro lo dice el catálogo: las que vienen con kind: "record".

Sub-árbol relativo

El subWhere es un grupo AND/OR cuyas hojas se resuelven contra los sub-campos que el registro declara.

La diferencia con el árbol de primer nivel es una sola, y es la fuente de error más común:

Hojas admitidas dentro de un sub-árbol relativo:

• Hoja escalar — { "kind": "predicate", "field": string, "comparisonOperator": …, "value"?: … }. El field debe ser un sub-campo escalar del registro.
• Registro anidado — { "kind": "recordPredicate", "field": string, "subWhere": … }. Un registro dentro de otro registro; se anida sin límite declarado, siempre que el catálogo declare cada nivel.
• Grupo — la misma forma de grupo, para combinar las hojas anteriores con AND/OR.

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 (hoy, 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 este criterio con otra audiencia vía una operación de conjunto:

Reglas de validación

La solicitud pasa por dos capas de validación, ambas devuelven 400 Bad Request:

1. Validación del DTO (estructura, tipos, enums, campos requeridos). En este caso message es un arreglo de strings y se rechazan propiedades desconocidas.
2. Validación de negocio (el criterio debe generar SQL válido y coherente contra el catálogo). En este caso message es un string único con el mensaje de la regla incumplida. La validación de negocio se detiene en el primer invariante violado.

Reglas de negocio verificadas (todas devuelven 400, con el mensaje exacto del API):

Reglas específicas de composedWith (también 400):

Ejemplo

Audiencia de usuarios que en los últimos 90 días completaron transacciones por más de 100000, cruzando event_transactions con user_properties para filtrar por país, e intersectada con otra audiencia existente que también proyecta solo user_id.

curl -X POST https://api.reten.ai/api/audience-criterias \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compradores VIP (últimos 90 días)",
    "queryBlocks": [
      {
        "order": 0,
        "from": {
          "table": "event_transactions",
          "joins": [
            {
              "type": "INNER",
              "table": "user_properties",
              "on": [
                {
                  "left":  { "table": "event_transactions", "column": "user_id" },
                  "right": { "table": "user_properties", "column": "user_id" }
                }
              ]
            }
          ]
        },
        "select": {
          "distinct": false,
          "items": [
            { "kind": "column", "column": { "table": "event_transactions", "column": "user_id" } }
          ]
        },
        "timeWindow": {
          "timeOperator": "IN_THE_LAST",
          "reference": { "table": "event_transactions", "column": "event_date" },
          "unit": "DAYS",
          "value": 90
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "event_transactions", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "completed"
            },
            {
              "kind": "predicate",
              "column": { "table": "user_properties", "column": "country" },
              "comparisonOperator": "IN",
              "value": ["CL", "MX"]
            }
          ]
        },
        "groupBy": [
          { "table": "event_transactions", "column": "user_id" }
        ],
        "having": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "aggregate": {
                "aggregationOperator": "SUM",
                "operand": { "kind": "column", "column": { "table": "event_transactions", "column": "pricing.final_amount" } }
              },
              "comparisonOperator": "GREATER_THAN",
              "value": 100000
            }
          ]
        }
      }
    ],
    "composedWith": [
      {
        "operandCriteriaId": "b2c3d4e5-6789-4abc-9def-0123456789ab",
        "setOperator": "INTERSECT_DISTINCT"
      }
    ]
  }'

import axios from 'axios';

const body = {
  name: 'Compradores VIP (últimos 90 días)',
  queryBlocks: [
    {
      order: 0,
      from: {
        table: 'event_transactions',
        joins: [
          {
            type: 'INNER',
            table: 'user_properties',
            on: [
              {
                left: { table: 'event_transactions', column: 'user_id' },
                right: { table: 'user_properties', column: 'user_id' },
              },
            ],
          },
        ],
      },
      select: {
        distinct: false,
        items: [
          { kind: 'column', column: { table: 'event_transactions', column: 'user_id' } },
        ],
      },
      timeWindow: {
        timeOperator: 'IN_THE_LAST',
        reference: { table: 'event_transactions', column: 'event_date' },
        unit: 'DAYS',
        value: 90,
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'event_transactions', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'completed',
          },
          {
            kind: 'predicate',
            column: { table: 'user_properties', column: 'country' },
            comparisonOperator: 'IN',
            value: ['CL', 'MX'],
          },
        ],
      },
      groupBy: [{ table: 'event_transactions', column: 'user_id' }],
      having: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            aggregate: {
              aggregationOperator: 'SUM',
              operand: { kind: 'column', column: { table: 'event_transactions', column: 'pricing.final_amount' } },
            },
            comparisonOperator: 'GREATER_THAN',
            value: 100000,
          },
        ],
      },
    },
  ],
  composedWith: [
    {
      operandCriteriaId: 'b2c3d4e5-6789-4abc-9def-0123456789ab',
      setOperator: 'INTERSECT_DISTINCT',
    },
  ],
};

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

Respuesta 201 Created

Devuelve el criterio creado como IAudienceCriteriaDetail — la misma forma que GET /audience-criterias/:id. Es el recurso base más el árbol completo: queryBlocks[] (con su id y order ya resueltos, ordenados por order ascendente) y compositions[] (con id y operandCriteriaName).

Campos base (IAudienceCriteria) — todos camelCase; los instantes se serializan a ISO 8601:

Relaciones anidadas:

• queryBlocks[] — cada bloque añade su id (UUID) y devuelve el árbol tal como se envió (from, select, timeWindow, where, groupBy, having). Los campos opcionales ausentes se devuelven como null (setOperator, timeWindow, groupBy, having) y from.joins como [] si no había joins; from.unnests viene siempre como [].
• compositions[] — cada composición: id (UUID), operandCriteriaId, operandCriteriaName (nombre del operando resuelto; "" si no resuelve) y setOperator.

{
  "id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "projectId": "3f6c2b1a-8d4e-4f7a-9b2c-5e1d0a7f6c34",
  "name": "Compradores VIP (últimos 90 días)",
  "description": null,
  "isActive": true,
  "isRoot": false,
  "ownerId": "0f0e0d0c-0b0a-4090-8070-605040302010",
  "updatedBy": "0f0e0d0c-0b0a-4090-8070-605040302010",
  "createdAt": "2026-07-15T14:32:07.481Z",
  "updatedAt": "2026-07-15T14:32:07.481Z",
  "queryBlocks": [
    {
      "id": "c3d4e5f6-7890-4abc-9def-34567890abcd",
      "order": 0,
      "setOperator": null,
      "from": {
        "table": "event_transactions",
        "joins": [
          {
            "type": "INNER",
            "table": "user_properties",
            "on": [
              {
                "left":  { "table": "event_transactions", "column": "user_id" },
                "right": { "table": "user_properties", "column": "user_id" }
              }
            ]
          }
        ],
        "unnests": []
      },
      "select": {
        "distinct": false,
        "items": [
          { "kind": "column", "column": { "table": "event_transactions", "column": "user_id" } }
        ]
      },
      "timeWindow": {
        "timeOperator": "IN_THE_LAST",
        "reference": { "table": "event_transactions", "column": "event_date" },
        "unit": "DAYS",
        "value": 90
      },
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "event_transactions", "column": "status" },
            "comparisonOperator": "EQUALS",
            "value": "completed"
          },
          {
            "kind": "predicate",
            "column": { "table": "user_properties", "column": "country" },
            "comparisonOperator": "IN",
            "value": ["CL", "MX"]
          }
        ]
      },
      "groupBy": [
        { "table": "event_transactions", "column": "user_id" }
      ],
      "having": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "aggregate": {
              "aggregationOperator": "SUM",
              "operand": { "kind": "column", "column": { "table": "event_transactions", "column": "pricing.final_amount" } }
            },
            "comparisonOperator": "GREATER_THAN",
            "value": 100000
          }
        ]
      }
    }
  ],
  "compositions": [
    {
      "id": "d4e5f6a7-8901-4abc-9def-4567890abcde",
      "operandCriteriaId": "b2c3d4e5-6789-4abc-9def-0123456789ab",
      "operandCriteriaName": "Usuarios activos",
      "setOperator": "INTERSECT_DISTINCT"
    }
  ]
}

Respuestas de error