Filtros de eventos

Visão geral

Um filtro de eventos (event criteria) é um conjunto de eventos selecionado com um query-builder —tabela → colunas → filtros → janela temporal → agregações— sem escrever SQL manualmente.

A definição é montada compondo:

A árvore completa —com as três folhas do where e todos os seus campos— é documentada uma única vez em Definição; as páginas de endpoint a referenciam em vez de repeti-la.

Sem coluna de identidade

Um filtro de eventos projeta eventos, não sujeitos: não existe uma coluna de identidade obrigatória e o SQL gerado retorna subjectColumn: null. Essa é a diferença estrutural com as audiências, que precisam, sim, expor sua identidade em pelo menos um bloco.

Endpoints

Base URL e ambientes

Todas as rotas ficam sob o prefixo global /api, dentro do recurso /event-criterias (por exemplo POST /api/event-criterias).

Autenticação

Todos os endpoints exigem um token JWT Bearer mais o header x-tenant-id que identifica o tenant em cujo schema a requisição opera, e o header x-project-id que identifica o projeto em que a requisição trabalha (veja Autenticação → Contexto de Projeto).

-H "Authorization: Bearer <access_token>"
-H "x-tenant-id: <tenant-id>"
-H "x-project-id: <project-id>"

Permissões

Cada rota exige uma permissão específica:

Códigos de status

Formato de erro

Os erros de validação, autorização e resolução seguem o formato de erro padrão da API:

{
  "statusCode": 400,
  "message": ["name should not be empty"],
  "error": "Bad Request"
}

Em erros de validação de DTO, message é um array de strings (uma entrada por regra violada). A validação é estrita: propriedades não declaradas são rejeitadas, então enviar um campo desconhecido produz um 400.

Paginação

A listagem envolve os resultados em PaginatedResponseDto<T>:

{
  "data": [],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 0,
    "total_pages": 0,
    "has_next": false,
    "has_previous": false
  }
}

O detalhe dos parâmetros de paginação está documentado em Listar.

Glossário de enums

Catálogo de referência rápida. O campo onde cada um aparece e sua forma exata estão em Definição.

SetOperatorEnum

Combinação de blocos de consulta dentro do mesmo filtro (setOperator de um bloco).

• UNION_DISTINCT · UNION_ALL · INTERSECT_DISTINCT

LogicalOperatorEnum

Encadeamento de predicados dentro de um grupo da árvore de filtros.

• AND · OR

ComparisonOperatorEnum

Operador de um predicado sobre uma coluna ou sobre um sub-campo.

• EQUALS · NOT_EQUALS · GREATER_THAN · LESS_THAN · GREATER_THAN_OR_EQUAL · LESS_THAN_OR_EQUAL · CONTAINS · NOT_CONTAINS · STARTS_WITH · ENDS_WITH · IS_NULL · IS_NOT_NULL · IN · NOT_IN · BETWEEN

AggregationOperatorEnum

Função de agregação sobre um operando (uma coluna, * ou uma expressão aritmética).

• COUNT · SUM · AVG · MIN · MAX

ArithmeticOperatorEnum

Operador de uma expressão aritmética dentro do operando de um agregado. SAFE_DIVIDE retorna NULL quando o denominador é zero.

• ADD · SUBTRACT · MULTIPLY · SAFE_DIVIDE

TimeOperatorEnum

Operador da janela temporal (timeWindow).

• ALL_TIME · IN_THE_LAST · IN_THE_FIRST · SINCE · BETWEEN

TimeUnitEnum

Unidade da janela temporal.

• DAYS · WEEKS · MONTHS · YEARS

JoinTypeEnum

Tipo de join entre tabelas do catálogo.

• INNER · LEFT · RIGHT · FULL

CatalogFieldTypeEnum

Tipo de dado de uma coluna escalar do catálogo de eventos. Determina quais operadores de comparação ela admite.

• STRING · TIMESTAMP · BOOLEAN · FLOAT64 · INT64 · NUMERIC · BIGNUMERIC

Diferenças em relação às audiências

Os dois recursos compartilham o query-builder, mas não são simétricos. Se você chega das audiências, estas são as suposições que não se transferem: