Criar Audience Criteria

POST /api/audience-criterias

Cria um Audience Criteria a partir de sua definição completa. É o endpoint central do recurso: recebe toda a árvore da definição —blocos de consulta, projeção, filtros, janela temporal, cruzamentos, agregações e composições com outras audiências— e a persiste. A operação é transacional: o critério, seus query blocks e suas composições são criados juntos, ou nada é criado.

Auth: Obrigatória — permissão audience-criteria:create

Corpo da requisição

Nível raiz (CreateAudienceCriteriaDto):

queryBlocks[] — bloco de consulta

Cada elemento de queryBlocks (QueryBlockDto) é um statement SQL completo:

ColumnRefDto — referência a coluna

Usado em toda a árvore (select, filtros, group by, joins, agregados, janela temporal):

Toda coluna é sempre qualificada com sua table para evitar ambiguidade.

from — fonte de dados (FromDto)

Cada JoinDto:

Cada JoinPredicateDto é um par de colunas: { left: ColumnRefDto, right: ColumnRefDto }.

select — projeção (SelectDto)

Os items são discriminados por kind:

• Coluna — kind: "column":

  Campo	Tipo	Obrigatório	Descrição
  kind	"column"	Sim	Discriminador.
  column	ColumnRefDto	Sim	Coluna projetada.
  alias	string	Não	Deve corresponder a ^[A-Za-z_][A-Za-z0-9_]*$.

• Agregado — kind: "aggregate":

  Campo	Tipo	Obrigatório	Descrição
  kind	"aggregate"	Sim	Discriminador.
  aggregate	AggregateDto	Sim	Expressão de agregação.
  alias	string	Sim	Aqui o alias é obrigatório. Mesmo regex de identificador.

AggregateDto:

operand —o que é agregado— é discriminado por kind:

ArithmeticOperatorEnum: ADD | SUBTRACT | MULTIPLY | SAFE_DIVIDE (uma divisão que retorna NULL quando o denominador é zero, em vez de fazer a consulta falhar). As colunas de uma expressão aritmética precisam ser numéricas (INT64, NUMERIC, BIGNUMERIC, FLOAT64), e as expressões se aninham até 3 níveis de arithmetic, contando o externo.

where — árvore de predicados (WhereDto)

O where é uma árvore recursiva. O nó raiz é sempre um grupo, e suas folhas são de dois tipos:

Grupo — kind: "group"

Folha de coluna — kind: "predicate"

Compara uma coluna escalar qualificada por sua tabela.

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

Folha de registro — kind: "recordPredicate"

Filtra por uma coluna RECORD REPEATED (um array de structs, como attributes). Significa que pelo menos um elemento do array satisfaz o 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" }
    ]
  }
}

Quais colunas aceitam um filtro de registro é informado pelo catálogo: as que vêm com kind: "record".

Sub-árvore relativa

O subWhere é um grupo AND/OR cujas folhas são resolvidas contra os sub-campos que o registro declara.

Há uma única diferença em relação à árvore de nível superior, e ela é a origem mais comum de erros:

Folhas permitidas dentro de uma sub-árvore relativa:

• Folha escalar — { "kind": "predicate", "field": string, "comparisonOperator": …, "value"?: … }. O field deve ser um sub-campo escalar do registro.
• Registro aninhado — { "kind": "recordPredicate", "field": string, "subWhere": … }. Um registro dentro de outro registro; aninha sem limite declarado, desde que o catálogo declare cada nível.
• Grupo — o mesmo formato de grupo, para combinar as folhas anteriores com AND/OR.

Formato de value conforme comparisonOperator

ScalarValue = string | number | boolean. Além disso, cada operador deve ser compatível com o tipo da coluna (ver regras de validação).

groupBy — colunas de agrupamento

Lista opcional de ColumnRefDto[]. Quando o bloco agrega (declara groupBy ou tem um agregado no select), o groupBy deve corresponder exatamente às colunas não agregadas do select (ver regras de validação).

having — filtro sobre agregados (HavingDto)

Mesma estrutura recursiva que where (grupos AND/OR aninhados e mesma regra de value por operador), mas a folha opera sobre um agregado, não sobre uma coluna:

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

timeWindow — janela temporal (TimeWindowDto)

União discriminada por timeOperator. Restringe o bloco a um período de tempo sobre uma coluna TIMESTAMP do catálogo (reference). É um campo irmão do where, não um nó da árvore de filtros.

TimeUnitEnum: DAYS | WEEKS | MONTHS | YEARS.

Semântica de negócio de cada operador:

• ALL_TIME — sem janela; considera todo o histórico.
• IN_THE_LAST — janela rolante relativa a "agora": os últimos value unit (ex.: últimos 30 DAYS). Recalculada a cada execução.
• IN_THE_FIRST — janela relativa à origem do ciclo de vida do usuário (atualmente, sua data de cadastro): os primeiros value unit de vida de cada usuário. É ancorada por usuário, não a uma data fixa.
• SINCE — a partir da data civil from (inclusive).
• BETWEEN — entre from e to, ambas as datas civis inclusivas de seu dia completo.

composedWith[] — composição com outras audiências

Cada elemento (CreateCompositionDto) combina este critério com outra audiência via uma operação de conjunto:

Regras de validação

A requisição passa por duas camadas de validação, ambas retornando 400 Bad Request:

1. Validação do DTO (estrutura, tipos, enums, campos obrigatórios). Nesse caso message é um array de strings e propriedades desconhecidas são rejeitadas.
2. Validação de negócio (o critério deve gerar SQL válido e coerente com o catálogo). Nesse caso message é uma string única com a mensagem da regra violada. A validação de negócio para no primeiro invariante violado.

Regras de negócio verificadas (todas retornam 400, com a mensagem exata da API):

Regras específicas de composedWith (também 400):

Exemplo

Audiência de usuários que nos últimos 90 dias completaram transações de valor superior a 100000, cruzando event_transactions com user_properties para filtrar por país, e intersectada com outra audiência existente que também projeta apenas 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;

Resposta 201 Created

Retorna o critério criado como IAudienceCriteriaDetail — a mesma forma que GET /audience-criterias/:id. É o recurso base mais a árvore completa: queryBlocks[] (com seu id e order já resolvidos, ordenados por order ascendente) e compositions[] (com id e operandCriteriaName).

Campos base (IAudienceCriteria) — todos camelCase; os instantes são serializados em ISO 8601:

Relações aninhadas:

• queryBlocks[] — cada bloco adiciona seu id (UUID) e retorna a árvore exatamente como foi enviada (from, select, timeWindow, where, groupBy, having). Campos opcionais ausentes são retornados como null (setOperator, timeWindow, groupBy, having) e from.joins como [] se não havia joins; from.unnests vem sempre como [].
• compositions[] — cada composição: id (UUID), operandCriteriaId, operandCriteriaName (nome do operando resolvido; "" se não resolver) e 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"
    }
  ]
}

Respostas de erro