Actualizar Audience Criteria

PATCH /api/audience-criterias/:id

Actualiza un Audience Criteria existente. Es una actualización parcial: solo se modifican los campos presentes en el cuerpo; los omitidos quedan intactos. La operación es transaccional — si se reemplaza la definición, los cambios se aplican juntos o no se aplica ninguno.

Auth: Requerida — permiso audience-criteria:update

Parámetros de ruta

Semántica de actualización (léase primero)

El comportamiento del PATCH no es un merge campo a campo del árbol. Se resume así:

• Solo se actualiza lo enviado. Un campo omitido no se toca.
  • name — si se envía, no puede ser vacío; actualiza el nombre.
  • description — enviar un string la cambia; enviar null la limpia (queda null); omitirla la deja igual.
  • type — enviar un enum válido lo cambia; omitirlo lo deja igual (ver el aviso de type: null).
• updatedBy se fija al usuario que edita; updatedAt se refresca automáticamente.

Cuerpo de la solicitud

Nivel raíz (UpdateAudienceCriteriaDto). Todos los campos son opcionales:

Cuando se envía queryBlocks y/o composedWith, usan exactamente los mismos DTOs que Crear (CreateQueryBlockDto / CreateCompositionDto). El sub-árbol se documenta completo a continuación.

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 (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:

Recuerda: composedWith solo se aplica cuando también se envía queryBlocks (ver Semántica de actualización).

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 del sub-árbol). En este caso message es un arreglo de strings y se rechazan propiedades desconocidas. Corre siempre.
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 y se detiene en el primer invariante violado. Solo corre si el cuerpo incluye queryBlocks, y usa el type efectivo (del cuerpo o, si se omite, el actual del criterio).

Las reglas de negocio de la definición son idénticas a las de Crear (catálogo de tablas/columnas, "*" solo con COUNT, cobertura de GROUP BY, contexto de HAVING, identidad del AUDIENCE, setOperator por posición del bloque, compatibilidad de operador por tipo, forma de value, reglas del timeWindow, etc.).

Reglas específicas de composedWith (también 400, verificadas al recrear las composiciones cuando se envía queryBlocks):

Ejemplos

Actualización parcial (solo metadatos)

Renombrar el criterio y limpiar su descripción, sin tocar la definición (queryBlocks / composedWith se omiten, así que bloques y composiciones quedan intactos):

curl -X PATCH https://api.reten.ai/api/audience-criterias/a1b2c3d4-5678-4abc-9def-1234567890ab \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compradores VIP (renombrado)",
    "description": null
  }'

import axios from 'axios';

const id = 'a1b2c3d4-5678-4abc-9def-1234567890ab';
const response = await axios.patch(
  `https://api.reten.ai/api/audience-criterias/${id}`,
  { name: 'Compradores VIP (renombrado)', description: null },
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>' } },
);
const updated = response.data;

Reemplazo de la definición

Al incluir queryBlocks se reemplaza toda la definición. Aquí también se re-envía composedWith para conservar la composición (si se omitiera, la composición se borraría):

curl -X PATCH https://api.reten.ai/api/audience-criterias/a1b2c3d4-5678-4abc-9def-1234567890ab \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Compradores VIP (últimos 60 días)",
    "queryBlocks": [
      {
        "order": 0,
        "from": { "table": "event_transactions", "joins": [] },
        "select": {
          "distinct": false,
          "items": [
            { "kind": "column", "column": { "table": "event_transactions", "column": "user_id" } },
            {
              "kind": "aggregate",
              "aggregate": {
                "aggregationOperator": "SUM",
                "column": { "table": "event_transactions", "column": "pricing.final_amount" }
              },
              "alias": "total_gastado"
            }
          ]
        },
        "timeWindow": {
          "timeOperator": "IN_THE_LAST",
          "reference": { "table": "event_transactions", "column": "event_date" },
          "unit": "DAYS",
          "value": 60
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "event_transactions", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "completed"
            }
          ]
        },
        "groupBy": [
          { "table": "event_transactions", "column": "user_id" }
        ],
        "having": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "aggregate": {
                "aggregationOperator": "SUM",
                "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 id = 'a1b2c3d4-5678-4abc-9def-1234567890ab';
const body = {
  name: 'Compradores VIP (últimos 60 días)',
  queryBlocks: [
    {
      order: 0,
      from: { table: 'event_transactions', joins: [] },
      select: {
        distinct: false,
        items: [
          { kind: 'column', column: { table: 'event_transactions', column: 'user_id' } },
          {
            kind: 'aggregate',
            aggregate: {
              aggregationOperator: 'SUM',
              column: { table: 'event_transactions', column: 'pricing.final_amount' },
            },
            alias: 'total_gastado',
          },
        ],
      },
      timeWindow: {
        timeOperator: 'IN_THE_LAST',
        reference: { table: 'event_transactions', column: 'event_date' },
        unit: 'DAYS',
        value: 60,
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'event_transactions', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'completed',
          },
        ],
      },
      groupBy: [{ table: 'event_transactions', column: 'user_id' }],
      having: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            aggregate: {
              aggregationOperator: 'SUM',
              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.patch(
  `https://api.reten.ai/api/audience-criterias/${id}`,
  body,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>' } },
);
const updated = response.data;

Respuesta 200 OK

Devuelve el criterio ya actualizado como IAudienceCriteriaDetail — la misma forma que GET /audience-criterias/:id y que Crear. Es el recurso base más el árbol completo: queryBlocks[] (con su id y order 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 quedó (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.
• compositions[] — cada composición: id (UUID), operandCriteriaId, operandCriteriaName (nombre del operando resuelto; "" si no resuelve) y setOperator.

{
  "id": "a1b2c3d4-5678-4abc-9def-1234567890ab",
  "name": "Compradores VIP (últimos 60 días)",
  "description": null,
  "type": "AUDIENCE",
  "isActive": true,
  "ownerId": "0f0e0d0c-0b0a-4090-8070-605040302010",
  "updatedBy": "1a2b3c4d-5e6f-4071-8092-a0b0c0d0e0f0",
  "createdAt": "2026-07-15T14:32:07.481Z",
  "updatedAt": "2026-07-15T16:05:44.902Z",
  "queryBlocks": [
    {
      "id": "e5f6a7b8-9012-4abc-9def-567890abcdef",
      "order": 0,
      "setOperator": null,
      "from": { "table": "event_transactions", "joins": [] },
      "select": {
        "distinct": false,
        "items": [
          { "kind": "column", "column": { "table": "event_transactions", "column": "user_id" } },
          {
            "kind": "aggregate",
            "aggregate": {
              "aggregationOperator": "SUM",
              "column": { "table": "event_transactions", "column": "pricing.final_amount" }
            },
            "alias": "total_gastado"
          }
        ]
      },
      "timeWindow": {
        "timeOperator": "IN_THE_LAST",
        "reference": { "table": "event_transactions", "column": "event_date" },
        "unit": "DAYS",
        "value": 60
      },
      "where": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "column": { "table": "event_transactions", "column": "status" },
            "comparisonOperator": "EQUALS",
            "value": "completed"
          }
        ]
      },
      "groupBy": [
        { "table": "event_transactions", "column": "user_id" }
      ],
      "having": {
        "kind": "group",
        "logicalOperator": "AND",
        "children": [
          {
            "kind": "predicate",
            "aggregate": {
              "aggregationOperator": "SUM",
              "column": { "table": "event_transactions", "column": "pricing.final_amount" }
            },
            "comparisonOperator": "GREATER_THAN",
            "value": 100000
          }
        ]
      }
    }
  ],
  "compositions": [
    {
      "id": "f6a7b8c9-0123-4abc-9def-67890abcdef0",
      "operandCriteriaId": "b2c3d4e5-6789-4abc-9def-0123456789ab",
      "operandCriteriaName": "Usuarios activos",
      "setOperator": "INTERSECT_DISTINCT"
    }
  ]
}

Respuestas de error