Definition

What this page is

The definition of an event filter is the tree that describes which events it selects. It is identical in every endpoint that receives it or returns it, so it is documented only once here:

The table and column names that appear in the examples come from the catalog, which is the source of what can be filtered.

queryBlocks[] — query block

Minimum 1 element. Each block (QueryBlockDto) is a complete SQL statement; blocks are combined with each other via setOperator.

ColumnRefDto — column reference

Used throughout the tree (select, column filters, group by, joins, aggregates, time window):

Every column is always qualified with its table to avoid ambiguity. The exception is in the relative sub-trees —the inside of a record filter or of a related table filter—, where the operand is a bare field with no table (see Relative sub-tree).

from — data source (FromDto)

Each JoinDto:

Each JoinPredicateDto is a pair of columns: { left: ColumnRefDto, right: ColumnRefDto }. Both sides must be scalar columns.

select — projection (SelectDto)

The items are discriminated by kind:

• Column — kind: "column":

  Field	Type	Required	Description
  kind	"column"	Yes	Discriminator.
  column	ColumnRefDto	Yes	Projected column. Must be scalar.
  alias	string	No	Must match ^[A-Za-z_][A-Za-z0-9_]*$.

• Aggregate — kind: "aggregate":

  Field	Type	Required	Description
  kind	"aggregate"	Yes	Discriminator.
  aggregate	AggregateDto	Yes	Aggregation expression.
  alias	string	Yes	Here the alias is required. Same identifier regex.

AggregateDto:

operand — what is aggregated — is discriminated by kind:

ArithmeticOperatorEnum: ADD | SUBTRACT | MULTIPLY | SAFE_DIVIDE (a division that yields NULL when the denominator is zero instead of failing the query). The columns of an arithmetic expression must be numeric (INT64, NUMERIC, BIGNUMERIC, FLOAT64), and expressions nest up to 3 levels of arithmetic, counting the outermost one.

where — filter tree (WhereDto)

The where is a recursive tree. The root node is always a group, and its leaves come in three types:

Group — kind: "group"

Column leaf — kind: "predicate"

Compares a scalar column qualified by its table.

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

Record leaf — kind: "recordPredicate"

Filters by a RECORD REPEATED column (an array of structs, such as attributes or items). It means there is at least one element of the array that satisfies the sub-filter.

{
  "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" }
    ]
  }
}

Related table leaf — kind: "semiJoinPredicate"

Filters events by the existence of a match in another table, following a semi-join that the catalog declares. The path between the two tables is resolved by the catalog: the request only names the owner table and the 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"]
      }
    ]
  }
}

Relative sub-tree

The subWhere of a record filter and that of a related table filter have the same shape: an AND/OR group whose leaves are resolved against the fields that the scope declares —the record's sub-fields, or the related table's fields.

There is a single difference with the top-level tree, and it is the most common source of error:

Leaves accepted inside a relative sub-tree:

• Scalar leaf — { "kind": "predicate", "field": string, "comparisonOperator": …, "value"?: … }. The field must be a scalar sub-field of the scope.
• Nested record — { "kind": "recordPredicate", "field": string, "subWhere": … }. A record inside another record (for example items[].attributes[]); it nests with no declared limit, as long as the catalog declares each level.
• Group — the same group shape, to combine the previous leaves with AND/OR.

Shape of value by comparisonOperator

ScalarValue = string | number | boolean. The rule holds equally for column leaves and for the scalar leaves of a relative sub-tree.

Operators accepted by column type

Each operator must also be compatible with the column type that the catalog declares. An operator outside this table responds 400 with Operator <op> is not allowed for <type> operands.

groupBy — grouping columns

Optional list of ColumnRefDto[]. When the block aggregates (declares groupBy or has an aggregate in the select), the groupBy must match exactly the non-aggregated columns of the select.

having — filter over aggregates (HavingDto)

Same recursive structure as the where —nested AND/OR groups and the same value rule per operator—, but the leaf operates over an aggregate, not over a column:

• Group — identical to the one in the where.
• Leaf — { "kind": "predicate", "aggregate": AggregateDto, "comparisonOperator": …, "value"?: … }.

timeWindow — time window (TimeWindowDto)

Discriminated union by timeOperator. Constrains the block to a time period over a TIMESTAMP column from the catalog (reference). It is a sibling field of the where, not a node of the filter tree.

TimeUnitEnum: DAYS | WEEKS | MONTHS | YEARS.

Semantics of each operator:

• ALL_TIME — no window; considers the entire history.
• IN_THE_LAST — rolling window relative to "now": the last value unit (e.g. last 30 DAYS). Recomputed on each run.
• SINCE — from the civil date from (inclusive) onward.
• BETWEEN — between from and to, both civil dates inclusive of their full day.

Validation Rules

The definition goes through two layers of validation, both returning 400 Bad Request:

1. DTO validation (structure, types, enums, required fields). message is an array of strings and unknown properties are rejected.
2. Business validation (the definition must generate valid SQL that is coherent against the catalog). message is a single string with the message of the violated rule, and it stops at the first violated invariant.

Business rules verified, with the exact message from the API:

Catalog and references

Projection and aggregation

Query blocks

Operators and values

Record and related table filters

Time window