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.

Dentro de un proyecto, toda audiencia que no sea la audiencia raíz se valida intersectada con la audiencia raíz del proyecto — ver Intersección con la audiencia raíz.

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 (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 (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 3 o más transacciones COMPLETED en los últimos 90 días.

curl -X POST https://api.reten.ai/api/audience-criterias/validate-from-body \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "queryBlocks": [
      {
        "order": 0,
        "from": { "table": "event_transactions" },
        "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"
            }
          ]
        },
        "groupBy": [{ "table": "event_transactions", "column": "user_id" }],
        "having": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "aggregate": {
                "aggregationOperator": "COUNT",
                "operand": { "kind": "star" }
              },
              "comparisonOperator": "GREATER_THAN_OR_EQUAL",
              "value": 3
            }
          ]
        }
      }
    ]
  }'

import axios from 'axios';

const body = {
  queryBlocks: [
    {
      order: 0,
      from: { table: 'event_transactions' },
      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',
          },
        ],
      },
      groupBy: [{ table: 'event_transactions', column: 'user_id' }],
      having: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            aggregate: {
              aggregationOperator: 'COUNT',
              operand: { kind: 'star' },
            },
            comparisonOperator: 'GREATER_THAN_OR_EQUAL',
            value: 3,
          },
        ],
      },
    },
  ],
};

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>', 'x-project-id': '<project-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 proyecto activo.

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>" \
  -H "x-project-id: <project-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>', 'x-project-id': '<project-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.

Intersección con la audiencia raíz

Todo proyecto tiene una audiencia raíz, y toda otra audiencia del proyecto se evalúa dentro de ella. El dry-run corre sobre el mismo SQL que devuelve Generar SQL: para cualquier audiencia que no sea la audiencia raíz, intersectado con la audiencia raíz del proyecto. Por eso valid y bytesProcessed se refieren a esa consulta intersectada, y la estimación incluye la parte de la audiencia raíz.

No hay intersección cuando la audiencia validada es la propia audiencia raíz — :id/validate con el id de la audiencia raíz, o un borrador de validate-from-body cuyo criteriaId es la audiencia raíz.

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 criterio que no proyecta su columna de identidad, un timeWindow mal formado, un id o un criteriaId 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):