Filtros de eventos

Descripción general

Un filtro de eventos (event criteria) es un conjunto de eventos seleccionado con un query-builder —tabla → columnas → filtros → ventana temporal → agregaciones— sin escribir SQL a mano.

La definición se arma componiendo:

El árbol completo —con las tres hojas del where y todos sus campos— se documenta una sola vez en Definición; las páginas de endpoint la referencian en vez de repetirla.

Sin columna de identidad

Un filtro de eventos proyecta eventos, no sujetos: no existe una columna de identidad obligatoria y el SQL generado devuelve subjectColumn: null. Es la diferencia estructural con las audiencias, que sí deben exponer su identidad en al menos un bloque.

Endpoints

Base URL y ambientes

Todas las rutas cuelgan del prefijo global /api bajo el recurso /event-criterias (por ejemplo POST /api/event-criterias).

Autenticación

Todos los endpoints requieren un token JWT Bearer más la cabecera x-tenant-id que identifica el tenant sobre cuyo esquema opera la solicitud, y la cabecera x-project-id que identifica el proyecto en el que trabaja la solicitud (ver Autenticación → Contexto de Proyecto).

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

Permisos

Cada ruta exige un permiso específico:

Códigos de estado

Formato de error

Los errores de validación, autorización y resolución siguen el formato de error estándar de la API:

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

En errores de validación de DTO, message es un arreglo de strings (una entrada por regla incumplida). La validación es estricta: se rechazan propiedades no declaradas, así que enviar un campo desconocido produce un 400.

Paginación

El listado envuelve los resultados en PaginatedResponseDto<T>:

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

El detalle de los parámetros de paginación se documenta en Listar.

Glosario de enums

Catálogo de referencia rápida. El campo donde aparece cada uno y su forma exacta están en Definición.

SetOperatorEnum

Combinación de bloques de consulta dentro del mismo filtro (setOperator de un bloque).

• UNION_DISTINCT · UNION_ALL · INTERSECT_DISTINCT

LogicalOperatorEnum

Encadenamiento de predicados dentro de un grupo del árbol de filtros.

• AND · OR

ComparisonOperatorEnum

Operador de un predicado sobre una columna o sobre un 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

Función de agregación sobre un operando (una columna, * o una expresión aritmética).

• COUNT · SUM · AVG · MIN · MAX

ArithmeticOperatorEnum

Operador de una expresión aritmética dentro del operando de un agregado. SAFE_DIVIDE da NULL cuando el denominador es cero.

• ADD · SUBTRACT · MULTIPLY · SAFE_DIVIDE

TimeOperatorEnum

Operador de la ventana temporal (timeWindow).

• ALL_TIME · IN_THE_LAST · IN_THE_FIRST · SINCE · BETWEEN

TimeUnitEnum

Unidad de la ventana temporal.

• DAYS · WEEKS · MONTHS · YEARS

JoinTypeEnum

Tipo de join entre tablas del catálogo.

• INNER · LEFT · RIGHT · FULL

CatalogFieldTypeEnum

Tipo de dato de una columna escalar del catálogo de eventos. Determina qué operadores de comparación admite.

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

Diferencias con audiencias

Los dos recursos comparten el query-builder, pero no son simétricos. Si llegas desde audiencias, estas son las suposiciones que no se trasladan: