Definição

O que é esta página

A definição de um filtro de eventos é a árvore que descreve quais eventos ele seleciona. É idêntica em todos os endpoints que a recebem ou a retornam, então está documentada uma única vez aqui:

Os nomes de tabelas e colunas que aparecem nos exemplos vêm do catálogo, que é a fonte do que pode ser filtrado.

queryBlocks[] — bloco de consulta

Mínimo 1 elemento. Cada bloco (QueryBlockDto) é um statement SQL completo; os blocos se combinam entre si via setOperator.

ColumnRefDto — referência a coluna

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

Toda coluna é sempre qualificada com sua table para evitar ambiguidade. A exceção são as sub-árvores relativas —o interior de um filtro de registro ou de um filtro de tabela relacionada—, onde o operando é um field solto sem tabela (ver Sub-árvore relativa).

from — fonte de dados (FromDto)

Cada JoinDto:

Cada JoinPredicateDto é um par de colunas: { left: ColumnRefDto, right: ColumnRefDto }. Ambos os lados devem ser colunas escalares.

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. Deve ser escalar.
  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 filtros (WhereDto)

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

Grupo — kind: "group"

Folha de coluna — kind: "predicate"

Compara uma coluna escalar qualificada por sua tabela.

{
  "kind": "predicate",
  "column": { "table": "event_transactions", "column": "status" },
  "comparisonOperator": "EQUALS",
  "value": "Facturada"
}

Folha de registro — kind: "recordPredicate"

Filtra por uma coluna RECORD REPEATED (um array de structs, como attributes ou items). Significa existe ao menos um elemento do array que cumpre o sub-filtro.

{
  "kind": "recordPredicate",
  "column": { "table": "event_transactions", "column": "attributes" },
  "subWhere": {
    "kind": "group",
    "logicalOperator": "AND",
    "children": [
      { "kind": "predicate", "field": "key", "comparisonOperator": "EQUALS", "value": "documento_tipo" },
      { "kind": "predicate", "field": "value", "comparisonOperator": "EQUALS", "value": "factura" }
    ]
  }
}

Folha de tabela relacionada — kind: "semiJoinPredicate"

Filtra os eventos pela existência de uma correspondência em outra tabela, seguindo um semi-join que o catálogo declara. O caminho entre as duas tabelas é resolvido pelo catálogo: a requisição só nomeia a tabela dona e o semi-join.

{
  "kind": "semiJoinPredicate",
  "table": "event_transactions",
  "semiJoin": "products",
  "subWhere": {
    "kind": "group",
    "logicalOperator": "AND",
    "children": [
      {
        "kind": "predicate",
        "field": "categorization.category_name",
        "comparisonOperator": "IN",
        "value": ["Food Service", "HORECA"]
      }
    ]
  }
}

Sub-árvore relativa

O subWhere de um filtro de registro e o de um filtro de tabela relacionada têm o mesmo formato: um grupo AND/OR cujas folhas são resolvidas contra os campos que o escopo declara —os sub-campos do registro, ou os campos da tabela relacionada.

A diferença com a árvore de primeiro nível é uma só, e é a fonte de erro mais comum:

Folhas aceitas dentro de uma sub-árvore relativa:

• Folha escalar — { "kind": "predicate", "field": string, "comparisonOperator": …, "value"?: … }. O field deve ser um sub-campo escalar do escopo.
• Registro aninhado — { "kind": "recordPredicate", "field": string, "subWhere": … }. Um registro dentro de outro registro (por exemplo items[].attributes[]); aninha-se 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. A regra vale igualmente para as folhas de coluna e para as folhas escalares de uma sub-árvore relativa.

Operadores aceitos por tipo de coluna

Cada operador deve, além disso, ser compatível com o tipo da coluna que o catálogo declara. Um operador fora desta tabela responde 400 com Operator <op> is not allowed for <type> operands.

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.

having — filtro sobre agregados (HavingDto)

Mesma estrutura recursiva que o 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:

• Grupo — idêntico ao do where.
• Folha — { "kind": "predicate", "aggregate": AggregateDto, "comparisonOperator": …, "value"?: … }.

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 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.
• SINCE — a partir da data civil from (inclusive) em diante.
• BETWEEN — entre from e to, ambas as datas civis inclusivas de seu dia completo.

Regras de validação

A definição passa por duas camadas de validação, ambas retornando 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.
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 mensagem da regra violada, e para no primeiro invariante violado.

Regras de negócio verificadas, com a mensagem exata da API:

Catálogo e referências

Projeção e agregação

Blocos de consulta

Operadores e valores

Filtros de registro e de tabela relacionada

Janela temporal