Validar

Valida uma definição de filtro de eventos com um dry-run do BigQuery e retorna o custo estimado, sem executar o query.

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

Valida uma definição de filtro de eventos: compila-a para SQL e a submete a um dry-run do BigQuery, que verifica o query contra o schema real e estima seu custo sem executá-lo.

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

Não existe POST /event-criterias/:id/validate. As audiências têm a variante por id; este recurso somente valida a partir do corpo. Para validar um filtro salvo, obtenha sua definição com GET /:id e envie seus queryBlocks para esta rota.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`queryBlocks`	`QueryBlockDto[]`	Sim	Pelo menos 1 elemento. A definição a validar.

A estrutura de cada bloco está em Definição.

Este endpoint recebe somente a definição: name, description e format não fazem parte do corpo e enviá-los produz um 400 por propriedade desconhecida.

Exemplo

curl -X POST https://api.reten.ai/api/event-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", "joins": [] },
        "select": {
          "distinct": true,
          "items": [
            { "kind": "column", "column": { "table": "event_transactions", "column": "event_id" } }
          ]
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "event_transactions", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "Facturada"
            }
          ]
        }
      }
    ]
  }'

import axios from 'axios';

const body = {
  queryBlocks: [
    {
      order: 0,
      from: { table: 'event_transactions', joins: [] },
      select: {
        distinct: true,
        items: [
          { kind: 'column', column: { table: 'event_transactions', column: 'event_id' } },
        ],
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'event_transactions', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'Facturada',
          },
        ],
      },
    },
  ],
};

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

Resposta

Status 201 Created. O corpo relata o resultado do dry-run:

Campo	Tipo	Obrigatório	Descrição
`valid`	boolean	Sim	`true` se o dry-run teve sucesso; `false` se o BigQuery rejeitou o query.
`errors`	`string[]`	Não	Presente somente quando `valid: false`. Contém a(s) mensagem(ns) de erro do BigQuery.
`bytesProcessed`	number	Sim	Bytes que o BigQuery estima processar. Em caso de sucesso, a estimativa do dry-run; em caso de falha, `0`.

O dry-run não executa o query nem retorna linhas: apenas o valida contra o BigQuery e estima seu custo. Para obter uma amostra de linhas reais use Pré-visualizar; para ver o SQL gerado, Gerar SQL.

errors é um array por contrato, mas na prática o dry-run retorna uma única mensagem (a que o BigQuery reporta). Sempre discrimine por valid antes de ler errors.

Exemplo — válida (`valid: true`)

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

Com 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. Ainda assim o status é 201:

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

Validação estrutural vs. dry-run

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

Etapa	Como falha	Onde aparece
1. Validação do DTO (estrutura, tipos, enums)	Erro HTTP `400`	`message` (array de strings); interrompe a requisição.
2. Validação de negócio (catálogo, agregação, tempo)	Erro HTTP `400`	`message` (string); interrompe a requisição.
3. Dry-run do BigQuery	`valid: false` (status `201`)	Campo `errors` do corpo de resposta.

Não assuma que uma "definição inválida" sempre chega como valid: false. A maioria dos erros de forma e de negócio são erros HTTP 400 e nunca alcançam o dry-run. valid: false significa especificamente que o BigQuery rejeitou um query que já havia passado por toda a validação local.

Regras de validação

Antes do dry-run, a definição passa pelas duas camadas de validação. O catálogo completo de regras e suas mensagens exatas está em Definição → Regras de validação.

Respostas de erro

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

Status	Descrição
`400`	DTO inválido (campo faltando, tipo incorreto, enum fora do intervalo, propriedade desconhecida) ou uma regra de negócio violada.
`401`	Falta ou é inválido o `Authorization: Bearer`.
`403`	O usuário não tem a permissão `event-criteria:view-sql`, ou o `x-tenant-id` não está autorizado.
`404`	O tenant não tem dataset configurado (`Dataset not configured for tenant <id>`).