Validar

Validar

Valida una definición de audience criteria y, si pasa todas las validaciones, ejecuta un dry-run contra BigQuery. Un mismo motor sirve dos entradas:

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

Ambos devuelven la misma forma de respuesta: IValidateAudienceCriteriaResult, con la validez y el costo estimado del query. La validación no devuelve filas ni el SQL generado: solo si la definición es ejecutable y cuántos bytes procesaría.

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

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

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

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

Cuerpo de la solicitud

Nivel raíz (CriteriaDefinitionDto): la definición del criterio, sin envoltorio.

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

Definición de una audiencia de usuarios con al menos una orden pagada en Chile o México.

curl -X POST https://api.reten.ai/api/audience-criterias/validate-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"
            }
          ]
        },
        "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"]
            }
          ]
        }
      }
    ]
  }'

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',
          },
        ],
      },
      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'],
          },
        ],
      },
    },
  ],
};

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

La respuesta se documenta en IValidateAudienceCriteriaResult, con un ejemplo válido y uno inválido.

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

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

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

Parámetros de ruta

Este endpoint no recibe cuerpo ni query params.

Ejemplo

curl -X POST https://api.reten.ai/api/audience-criterias/f47ac10b-58cc-4372-a567-0e02b2c3d479/validate \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>"

import axios from 'axios';

const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await axios.post(
  `https://api.reten.ai/api/audience-criterias/${id}/validate`,
  undefined, // sin cuerpo
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>' } },
);
const result = response.data; // IValidateAudienceCriteriaResult

Respuesta — IValidateAudienceCriteriaResult

Status 201 Created en ambos endpoints. El cuerpo reporta el resultado del dry-run de BigQuery:

Ejemplo — válida (valid: true)

Respuesta 201 a una definición que compila y pasa el dry-run:

{
  "valid": true,
  "bytesProcessed": 10485760
}

Cuando valid es true, errors se omite y bytesProcessed trae la estimación de BigQuery (en este ejemplo, ~10 MB).

Ejemplo — inválida (valid: false)

La definición pasó la validación estructural y de negocio y se compiló a SQL, pero el dry-run de BigQuery la rechazó (p. ej. una columna del catálogo que aún no existe en la tabla real del dataset, o un query cuyo costo estimado supera el límite de bytes facturables). Aun así el status es 201:

{
  "valid": false,
  "errors": [
    "Unrecognized name: legacy_column at [3:8]"
  ],
  "bytesProcessed": 0
}

Con valid: false, errors trae el mensaje de BigQuery y bytesProcessed es 0.

Validación estructural vs. dry-run

Este es el punto clave del recurso: no todos los fallos llegan a errors[]. Una solicitud atraviesa etapas y cada una falla de forma distinta.

En otras palabras:

• Todo lo que ocurre antes del dry-run (etapas 1–3) que falla, responde un error HTTP y no produce un cuerpo IValidateAudienceCriteriaResult. Por ejemplo: una tabla fuera del catálogo, un AUDIENCE que no proyecta su columna de identidad, un timeWindow mal formado, un id inexistente o un operandCriteriaId que no existe.
• valid: false es exclusivo del dry-run: la definición ya era estructuralmente válida y se compiló a SQL, pero BigQuery la rechazó al estimarla. El status sigue siendo 201.

Reglas de validación

Antes del dry-run, 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). message es un arreglo de strings y se rechazan propiedades desconocidas (incluidos name/description/format).
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, y se detiene en el primer invariante violado.

Respuestas de error

Estos son los errores HTTP (distintos de valid: false, que viaja con status 201):