Validar

Validar

Valida uma definição de audience criteria e, se passar em todas as validações, executa um dry-run contra o BigQuery. Um mesmo motor atende duas entradas:

• POST /api/audience-criterias/validate-from-body — valida uma definição enviada no corpo (ainda não persistida).
• POST /api/audience-criterias/:id/validate — valida um critério já salvo, referenciado por seu id.

Ambos retornam a mesma forma de resposta: IValidateAudienceCriteriaResult, com a validade e o custo estimado do query. A validação não retorna linhas nem o SQL gerado: apenas se a definição é executável e quantos bytes ela processaria.

Dentro de um projeto, toda audiência que não seja a audiência raiz é validada intersectada com a audiência raiz do projeto — veja Interseção com a audiência raiz.

Auth: Obrigatória — permissão audience-criteria:view-sql (ambos endpoints).

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

Valida uma definição enviada no corpo, sem persisti-la.

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

Corpo da requisição

Nível raiz (CriteriaDefinitionDto): a definição do critério, sem wrapper.

Definição do critério

É a mesma árvore que Criar recebe, sem os campos name/description. Está documentada aqui de forma autocontida.

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 casar com ^[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.

Forma de value por 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 coincidir exatamente com as 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 de 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 móvel 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 (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 datas civis inclusivas do dia completo.

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

Cada elemento (CreateCompositionDto) combina esta definição com outra audiência via uma operação de conjunto:

Exemplo

Definição de uma audiência de usuários com 3 ou mais transações COMPLETED nos últimos 90 dias.

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

A resposta é documentada em IValidateAudienceCriteriaResult, com um exemplo válido e um inválido.

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

Valida um critério já salvo, referenciado por seu id. A definição não viaja no corpo: é obtida do critério persistido no projeto ativo.

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

Parâmetros de rota

Este endpoint não recebe corpo nem parâmetros de consulta.

Exemplo

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, // sem corpo
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const result = response.data; // IValidateAudienceCriteriaResult

Resposta — IValidateAudienceCriteriaResult

Status 201 Created em ambos os endpoints. O corpo relata o resultado do dry-run do BigQuery:

Exemplo — válida (valid: true)

Uma resposta 201 para uma definição que compila e passa no dry-run:

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

Quando valid é true, errors é omitido e bytesProcessed traz a estimativa do BigQuery (neste exemplo, ~10 MB).

Exemplo — inválida (valid: false)

A definição passou na validação estrutural e de negócio e compilou para SQL, mas o dry-run do BigQuery a rejeitou (ex.: uma coluna do catálogo que ainda não existe na tabela real do dataset, ou um query cujo custo estimado excede o limite de bytes faturáveis). Ainda assim o status é 201:

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

Com valid: false, errors traz a mensagem do BigQuery e bytesProcessed é 0.

Interseção com a audiência raiz

Todo projeto tem uma audiência raiz, e toda outra audiência do projeto é avaliada dentro dela. O dry-run roda sobre o mesmo SQL que Gerar SQL retorna: para qualquer audiência que não seja a audiência raiz, intersectado com a audiência raiz do projeto. Por isso valid e bytesProcessed se referem a essa consulta intersectada, e a estimativa inclui a parte da audiência raiz.

Não há interseção quando a audiência validada é a própria audiência raiz — :id/validate com o id da audiência raiz, ou um rascunho de validate-from-body cujo criteriaId é a audiência raiz.

Validação estrutural vs. dry-run

Este é o ponto-chave do recurso: nem todas as falhas chegam a errors[]. Uma requisição passa por etapas e cada uma falha de forma diferente.

Em outras palavras:

• Tudo o que acontece antes do dry-run (etapas 1–3) que falha responde com um erro HTTP e não produz um corpo IValidateAudienceCriteriaResult. Por exemplo: uma tabela fora do catálogo, um critério que não projeta sua coluna de identidade, um timeWindow malformado, um id ou um criteriaId inexistente, ou um operandCriteriaId que não existe.
• valid: false é exclusivo do dry-run: a definição já era estruturalmente válida e compilou para SQL, mas o BigQuery a rejeitou ao estimá-la. O status continua sendo 201.

Regras de validação

Antes do dry-run, a definição passa pelas mesmas duas camadas de validação que Criar, e ambas retornam 400 Bad Request:

1. Validação do DTO (estrutura, tipos, enums, campos obrigatórios). message é um array de strings e propriedades desconhecidas são rejeitadas (incluindo name/description/format).
2. Validação de negócio (a definição deve gerar SQL válido e coerente com o catálogo). message é um string único com a regra violada, e para no primeiro invariante violado.

Respostas de erro

Estes são os erros HTTP (diferentes de valid: false, que viaja com status 201):