Catálogo de eventos

Tablas, columnas, registros repetidos y semi-joins disponibles para construir un filtro de eventos.

Catálogo

El catálogo responde qué se puede filtrar. Son dos rutas: una lista las tablas disponibles y la otra, para una tabla, todo lo que ofrece —columnas escalares, columnas RECORD REPEATED y semi-joins contra tablas relacionadas.

Sin el catálogo la definición no es construible: no hay otra forma de saber que attributes es un registro repetido, que items[] tiene sub-campos, o que products alcanza la tabla product_properties.

Auth: Requerida — permiso event-criteria:view en ambas rutas

GET /api/event-criterias/tables

Lista las tablas del catálogo sobre las que se puede construir un filtro de eventos. El catálogo es idéntico entre tenants: esta ruta no consulta el dataset del tenant.

Ejemplo

curl https://api.reten.ai/api/event-criterias/tables \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>"

import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/event-criterias/tables',
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const tables = response.data;

Respuesta `200 OK`

Un arreglo de IEventTable:

Campo	Tipo	Descripción
`tableName`	string	Nombre de la tabla; es el valor que va en `from.table` y en `ColumnRefDto.table`.
`defaultTimeReferenceColumn`	string	Opcional. Columna `TIMESTAMP` sugerida como `reference` de la ventana temporal. Se puede elegir otra columna `TIMESTAMP`.
`requiresInnerJoin`	boolean	`true` si la tabla solo admite participar como tabla principal del `from` o como destino de un `INNER JOIN`.

[
  {
    "tableName": "event_transactions",
    "defaultTimeReferenceColumn": "event_date",
    "requiresInnerJoin": false
  }
]

Las tablas de este catálogo no declaran identityColumn: un filtro de eventos proyecta eventos, no sujetos. El campo existe en la forma de la respuesta por paridad con el catálogo de audiencias, pero acá viene siempre ausente.

GET /api/event-criterias/tables/:tableName/columns

Devuelve todo lo que el catálogo ofrece sobre una tabla. A diferencia de /tables, esta ruta reconcilia el catálogo contra el schema real del dataset del tenant antes de responder.

Parámetros de ruta

Parámetro	Tipo	Descripción
`tableName`	string	Nombre de la tabla, tal como lo devuelve `GET /tables`.

Ejemplo

curl https://api.reten.ai/api/event-criterias/tables/event_transactions/columns \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>"

import axios from 'axios';

const response = await axios.get(
  'https://api.reten.ai/api/event-criterias/tables/event_transactions/columns',
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const entries = response.data;

Respuesta `200 OK`

Un arreglo de IEventCatalogEntry: una unión discriminada por kind con tres variantes.

Estrecha por kind antes de leer type o fields. Solo la variante scalar trae type; solo record y semiJoin traen fields. Leer entry.type sin discriminar devuelve undefined para las otras dos variantes.

kind: "scalar" — una columna filtrable directamente:

Campo	Tipo	Descripción
`columnName`	string	Nombre de la columna. Para hojas de un STRUCT no repetido es el path con punto (`pricing.final_amount`).
`kind`	`"scalar"`	Discriminador.
`type`	`CatalogFieldTypeEnum`	Tipo del catálogo; determina qué operadores de comparación admite.

kind: "record" — una columna RECORD REPEATED, filtrable solo con un filtro de registro:

Campo Tipo Descripción
columnName string Nombre de la columna repetida.
kind "record" Discriminador.
fields IEventColumn[] Sub-campos filtrables, relativos al registro. Puede contener otros record.

Campo	Tipo	Descripción
`columnName`	string	Nombre de la columna repetida.
`kind`	`"record"`	Discriminador.
`fields`	`IEventColumn[]`	Sub-campos filtrables, relativos al registro. Puede contener otros `record`.

kind: "semiJoin" — una tabla relacionada alcanzable con un filtro de tabla relacionada:

Campo	Tipo	Descripción
`kind`	`"semiJoin"`	Discriminador.
`semiJoinName`	string	Nombre del semi-join; es el valor que va en `semiJoinPredicate.semiJoin`.
`targetTable`	string	Tabla relacionada contra la que se resuelve el filtro.
`fields`	`IEventColumn[]`	Campos filtrables de la tabla relacionada.

Los fields de un record y de un semiJoin usan la misma unión scalar | record, así que la regla de estrechar por kind aplica en cada nivel.

Ejemplo de respuesta

GET /api/event-criterias/tables/event_transactions/columns (recortado en las columnas escalares por brevedad; los registros y el semi-join van completos):

[
  { "columnName": "event_id", "kind": "scalar", "type": "STRING" },
  { "columnName": "event_date", "kind": "scalar", "type": "TIMESTAMP" },
  { "columnName": "user_id", "kind": "scalar", "type": "STRING" },
  { "columnName": "status", "kind": "scalar", "type": "STRING" },
  { "columnName": "coupon_code", "kind": "scalar", "type": "STRING" },
  { "columnName": "pricing.net_amount", "kind": "scalar", "type": "FLOAT64" },
  { "columnName": "pricing.final_amount", "kind": "scalar", "type": "FLOAT64" },
  { "columnName": "payment_details.method", "kind": "scalar", "type": "STRING" },
  { "columnName": "payment_details.date", "kind": "scalar", "type": "TIMESTAMP" },
  { "columnName": "shipping_address.region", "kind": "scalar", "type": "STRING" },
  {
    "columnName": "attributes",
    "kind": "record",
    "fields": [
      { "columnName": "key", "kind": "scalar", "type": "STRING" },
      { "columnName": "value", "kind": "scalar", "type": "STRING" }
    ]
  },
  {
    "columnName": "items",
    "kind": "record",
    "fields": [
      { "columnName": "item_id", "kind": "scalar", "type": "STRING" },
      { "columnName": "name", "kind": "scalar", "type": "STRING" },
      { "columnName": "price", "kind": "scalar", "type": "FLOAT64" },
      { "columnName": "quantity", "kind": "scalar", "type": "FLOAT64" },
      { "columnName": "category", "kind": "scalar", "type": "STRING" }
    ]
  },
  {
    "kind": "semiJoin",
    "semiJoinName": "products",
    "targetTable": "product_properties",
    "fields": [
      { "columnName": "sku", "kind": "scalar", "type": "STRING" },
      { "columnName": "name", "kind": "scalar", "type": "STRING" },
      { "columnName": "categorization.family_name", "kind": "scalar", "type": "STRING" },
      { "columnName": "categorization.subfamily_name", "kind": "scalar", "type": "STRING" },
      { "columnName": "categorization.category_name", "kind": "scalar", "type": "STRING" },
      { "columnName": "categorization.brand_name", "kind": "scalar", "type": "STRING" },
      { "columnName": "categorization.collection_name", "kind": "scalar", "type": "STRING" },
      { "columnName": "commercial.base_price", "kind": "scalar", "type": "FLOAT64" },
      { "columnName": "composition.is_pack", "kind": "scalar", "type": "BOOLEAN" },
      { "columnName": "composition.is_combo", "kind": "scalar", "type": "BOOLEAN" }
    ]
  }
]

Cómo se usa cada variante en la definición

Variante	Dónde va
`scalar`	`ColumnRefDto.column` de una hoja `predicate`, del `select`, del `groupBy`, de un agregado o de la `reference` de la ventana temporal.
`record`	`column` de una hoja `recordPredicate`; sus `fields` van en el `field` de las hojas del `subWhere`.
`semiJoin`	`semiJoin` de una hoja `semiJoinPredicate`; sus `fields` van en el `field` de las hojas del `subWhere`.

El targetTable de un semi-join no es una tabla del catálogo: no aparece en GET /tables, no puede ir en el from ni ser destino de un join. Solo se alcanza con una hoja semiJoinPredicate.

Un semi-join se omite de la respuesta si el dataset del tenant no tiene su tabla relacionada: no es un error, es que ese tenant no tiene esa fuente de datos. La ausencia del semiJoin en el catálogo es la señal de que el filtro no está disponible.

Respuestas de error

Estado	Descripción
`401`	Falta o es inválido el `Authorization: Bearer`.
`403`	El usuario no tiene el permiso `event-criteria:view`, o el `x-tenant-id` no está autorizado.
`404`	Solo en `/tables/:tableName/columns`: la tabla no está en el catálogo (`La tabla no existe o no está en el catálogo de eventos.`), o el tenant no tiene dataset configurado (`Dataset not configured for tenant <id>`).
`500`	Solo en `/tables/:tableName/columns`: el schema real del dataset no satisface el catálogo (`El schema de datos no satisface el catálogo de eventos.`).

GET /api/event-criterias/tables no consulta el dataset del tenant, así que solo devuelve 200, 401 o 403.