Pré-visualizar

Pré-visualizar

Executa um audience criteria contra o BigQuery (limitado por limit) e retorna uma amostra das linhas reais correspondentes mais o total do universo. Um único motor atende dois pontos de entrada:

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

Ambos retornam a mesma forma de resposta: IPreviewAudienceCriteriaResult.

Diferente de Gerar SQL, preview não retorna SQL; e diferente de Validar (que só faz um dry-run), preview traz dados de verdade: executa a consulta e mostra linhas.

Dentro de um projeto, toda audiência que não seja a audiência raiz é executada 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 os endpoints).

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

Executa 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 (PreviewFromBodyDto): a definição do critério (CriteriaDefinitionDto) mais o campo limit.

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 de 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.

Forma de value segundo comparisonOperator

ScalarValue = string | number | boolean. Além disso, cada operador deve ser compatível com o tipo da coluna (veja 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 (veja regras de validação).

having — filtro sobre agregados (HavingDto)

Mesma estrutura recursiva que where (grupos AND/OR aninhados e a 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. Limita 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 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 (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 inclusive 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

Audiência de usuários com 3 ou mais transações COMPLETED nos últimos 90 dias. Projeta apenas user_id, como a definição padrão da audiência raiz (veja Interseção com a audiência raiz). É solicitada uma amostra de 50 linhas (limit).

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

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,
          },
        ],
      },
    },
  ],
  limit: 50, // opcional; padrão 100
};

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

A resposta está documentada em IPreviewAudienceCriteriaResult, com um exemplo de rows não vazio.

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

Executa 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. O corpo só carrega limit.

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

Parâmetros de rota

Corpo da requisição

PreviewQueryDto — um único campo, opcional:

Um corpo vazio ({}) é válido: usa o limit padrão (100).

Exemplo

curl -X POST https://api.reten.ai/api/audience-criterias/f47ac10b-58cc-4372-a567-0e02b2c3d479/preview \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 50 }'

import axios from 'axios';

const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await axios.post(
  `https://api.reten.ai/api/audience-criterias/${id}/preview`,
  { limit: 50 }, // opcional; padrão 100
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const preview = response.data; // IPreviewAudienceCriteriaResult

limit — tamanho da amostra

limit limita apenas quantas linhas a resposta traz em rows (a amostra que você vê), não o universo correspondente à audiência.

• Intervalo: inteiro 1..500 (menor que 1 ou maior que 500 ⇒ 400).
• Padrão: 100 (PREVIEW_ROW_LIMIT_DEFAULT) quando omitido.

Resposta — IPreviewAudienceCriteriaResult

Exemplo

Resposta 201 ao exemplo acima (limit: 50). A audiência corresponde a 4821 usuários; rows mostra os primeiros 50 (aqui reduzidos a 3 por brevidade), cada um com a única coluna projetada (user_id):

{
  "rows": [
    { "user_id": "u_9f3a1c" },
    { "user_id": "u_2b7e04" },
    { "user_id": "u_c081ff" }
  ],
  "totalCount": 4821,
  "bytesProcessed": 5242880
}

As chaves de cada objeto em rows (user_id) vêm do select da audiência. totalCount (4821) é o universo completo, maior que as 50 linhas da amostra.

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 preview executa 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 rows e totalCount são as linhas correspondentes à audiência dentro da audiência raiz, e bytesProcessed inclui a parte da consulta que corresponde à audiência raiz.

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

Regras de validação

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

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

Respostas de erro