Definición

Qué es esta página

La definición de un filtro de eventos es el árbol que describe qué eventos selecciona. Es idéntica en todos los endpoints que la reciben o la devuelven, así que se documenta una sola vez acá:

Los nombres de tablas y columnas que aparecen en los ejemplos salen del catálogo, que es la fuente de qué se puede filtrar.

queryBlocks[] — bloque de consulta

Mínimo 1 elemento. Cada bloque (QueryBlockDto) es un statement SQL completo; los bloques se combinan entre sí con setOperator.

ColumnRefDto — referencia a columna

Se usa en todo el árbol (select, filtros de columna, group by, joins, agregados, ventana temporal):

Toda columna se cualifica siempre con su table para evitar ambigüedad. La excepción son los sub-árboles relativos —el interior de un filtro de registro o de tabla relacionada—, donde el operando es un field suelto sin tabla (ver Sub-árbol relativo).

from — fuente de datos (FromDto)

Cada JoinDto:

Cada JoinPredicateDto es un par de columnas: { left: ColumnRefDto, right: ColumnRefDto }. Ambos lados deben ser columnas escalares.

select — proyección (SelectDto)

Los items se discriminan por kind:

• Columna — kind: "column":

  Campo	Tipo	Requerido	Descripción
  kind	"column"	Sí	Discriminador.
  column	ColumnRefDto	Sí	Columna proyectada. Debe ser escalar.
  alias	string	No	Debe matchear ^[A-Za-z_][A-Za-z0-9_]*$.

• Agregado — kind: "aggregate":

  Campo	Tipo	Requerido	Descripción
  kind	"aggregate"	Sí	Discriminador.
  aggregate	AggregateDto	Sí	Expresión de agregación.
  alias	string	Sí	Aquí el alias es obligatorio. Mismo regex de identificador.

AggregateDto:

operand —lo que se agrega— se discrimina por kind:

ArithmeticOperatorEnum: ADD | SUBTRACT | MULTIPLY | SAFE_DIVIDE (una división que da NULL cuando el denominador es cero, en vez de hacer fallar la consulta). Las columnas de una expresión aritmética tienen que ser numéricas (INT64, NUMERIC, BIGNUMERIC, FLOAT64), y las expresiones se anidan hasta 3 niveles de arithmetic, contando el exterior.

where — árbol de filtros (WhereDto)

El where es un árbol recursivo. El nodo raíz es siempre un grupo, y sus hojas son de tres tipos:

Grupo — kind: "group"

Hoja de columna — kind: "predicate"

Compara una columna escalar cualificada por su tabla.

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

Hoja de registro — kind: "recordPredicate"

Filtra por una columna RECORD REPEATED (un array de structs, como attributes o items). Significa existe al menos un elemento del array que cumple el 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" }
    ]
  }
}

Hoja de tabla relacionada — kind: "semiJoinPredicate"

Filtra los eventos por la existencia de un match en otra tabla, siguiendo un semi-join que el catálogo declara. El camino entre las dos tablas lo resuelve el catálogo: la solicitud solo nombra la tabla dueña y el 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-árbol relativo

El subWhere de un filtro de registro y el de uno de tabla relacionada tienen la misma forma: un grupo AND/OR cuyas hojas se resuelven contra los campos que declara el scope —los sub-campos del record, o los campos de la tabla relacionada.

La diferencia con el árbol de primer nivel es una sola, y es la fuente de error más común:

Hojas admitidas dentro de un sub-árbol relativo:

• Hoja escalar — { "kind": "predicate", "field": string, "comparisonOperator": …, "value"?: … }. El field debe ser un sub-campo escalar del scope.
• Registro anidado — { "kind": "recordPredicate", "field": string, "subWhere": … }. Un record dentro de otro record (por ejemplo items[].attributes[]); se anida sin límite declarado, siempre que el catálogo declare cada nivel.
• Grupo — la misma forma de grupo, para combinar las hojas anteriores con AND/OR.

Forma de value según comparisonOperator

ScalarValue = string | number | boolean. La regla vale igual para las hojas de columna y para las hojas escalares de un sub-árbol relativo.

Operadores admitidos por tipo de columna

Cada operador debe además ser compatible con el tipo de la columna que declara el catálogo. Un operador fuera de esta tabla responde 400 con Operator <op> is not allowed for <tipo> operands.

groupBy — columnas de agrupación

Lista opcional de ColumnRefDto[]. Cuando el bloque agrega (declara groupBy o tiene un agregado en el select), el groupBy debe coincidir exactamente con las columnas no agregadas del select.

having — filtro sobre agregados (HavingDto)

Misma estructura recursiva que el where —grupos AND/OR anidados y la misma regla de value por operador—, pero la hoja opera sobre un agregado, no sobre una columna:

• Grupo — idéntico al del where.
• Hoja — { "kind": "predicate", "aggregate": AggregateDto, "comparisonOperator": …, "value"?: … }.

timeWindow — ventana temporal (TimeWindowDto)

Unión discriminada por timeOperator. Acota el bloque a un período de tiempo sobre una columna TIMESTAMP del catálogo (reference). Es un campo hermano del where, no un nodo del árbol de filtros.

TimeUnitEnum: DAYS | WEEKS | MONTHS | YEARS.

Semántica de cada operador:

• ALL_TIME — sin ventana; considera todo el histórico.
• IN_THE_LAST — ventana rodante relativa a "ahora": los últimos value unit (p. ej. últimos 30 DAYS). Se recomputa en cada corrida.
• SINCE — desde la fecha civil from (inclusiva) en adelante.
• BETWEEN — entre from y to, ambas fechas civiles inclusivas de su día completo.

Reglas de validación

La definición pasa por dos capas de validación, ambas devuelven 400 Bad Request:

1. Validación del DTO (estructura, tipos, enums, campos requeridos). message es un arreglo de strings y se rechazan propiedades desconocidas.
2. Validación de negocio (la definición debe generar SQL válido y coherente contra el catálogo). message es un string único con el mensaje de la regla incumplida, y se detiene en el primer invariante violado.

Reglas de negocio verificadas, con el mensaje exacto del API:

Catálogo y referencias

Proyección y agregación

Bloques de consulta

Operadores y valores

Filtros de registro y de tabla relacionada

Ventana temporal