Catálogo de audiencias

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 y columnas RECORD REPEATED.

Sin el catálogo la definición no es construible: no hay otra forma de saber cuál es la columna de identidad de una tabla, qué columna TIMESTAMP sugiere como referencia temporal, ni que attributes es un registro repetido y no una columna comparable.

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

GET /api/audience-criterias/tables

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

Ejemplo

curl https://api.reten.ai/api/audience-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/audience-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 IAudienceTable:

[
  {
    "tableName": "user_properties",
    "identityColumn": "user_id",
    "defaultTimeReferenceColumn": "sign_up_date",
    "requiresInnerJoin": false
  },
  {
    "tableName": "event_transactions",
    "identityColumn": "user_id",
    "defaultTimeReferenceColumn": "event_date",
    "requiresInnerJoin": false
  },
  {
    "tableName": "user_segment_relation",
    "identityColumn": "user_id",
    "requiresInnerJoin": true
  },
  {
    "tableName": "user_seller_relation",
    "identityColumn": "user_id",
    "requiresInnerJoin": true
  }
]

GET /api/audience-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

Ejemplo

curl https://api.reten.ai/api/audience-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/audience-criterias/tables/event_transactions/columns',
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const columns = response.data;

Respuesta 200 OK

Un arreglo de IAudienceColumn: una unión discriminada por kind con 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.
  isIdentity	boolean	true si es la columna de identidad de la tabla. Como máximo una columna por tabla la tiene.
  isDefaultTimeReference	boolean	true si es la referencia temporal sugerida de la tabla. Es una sugerencia: se puede anclar la ventana en otra columna TIMESTAMP.

• 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	IAudienceColumn[]	Sub-campos filtrables, relativos al registro. Puede contener otros record.
  isIdentity	false	Siempre false: un registro repetido no puede ser la identidad de la tabla.
  isDefaultTimeReference	false	Siempre false: un registro repetido no puede anclar la ventana temporal.

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

Ejemplo de respuesta

GET /api/audience-criterias/tables/event_transactions/columns:

[
  {
    "columnName": "user_id",
    "kind": "scalar",
    "type": "STRING",
    "isIdentity": true,
    "isDefaultTimeReference": false
  },
  {
    "columnName": "event_date",
    "kind": "scalar",
    "type": "TIMESTAMP",
    "isIdentity": false,
    "isDefaultTimeReference": true
  },
  {
    "columnName": "event_id",
    "kind": "scalar",
    "type": "STRING",
    "isIdentity": false,
    "isDefaultTimeReference": false
  },
  {
    "columnName": "status",
    "kind": "scalar",
    "type": "STRING",
    "isIdentity": false,
    "isDefaultTimeReference": false
  },
  {
    "columnName": "coupon_code",
    "kind": "scalar",
    "type": "STRING",
    "isIdentity": false,
    "isDefaultTimeReference": false
  },
  {
    "columnName": "pricing.final_amount",
    "kind": "scalar",
    "type": "FLOAT64",
    "isIdentity": false,
    "isDefaultTimeReference": false
  },
  {
    "columnName": "attributes",
    "kind": "record",
    "fields": [
      {
        "columnName": "key",
        "kind": "scalar",
        "type": "STRING",
        "isIdentity": false,
        "isDefaultTimeReference": false
      },
      {
        "columnName": "value",
        "kind": "scalar",
        "type": "STRING",
        "isIdentity": false,
        "isDefaultTimeReference": false
      }
    ],
    "isIdentity": false,
    "isDefaultTimeReference": false
  }
]

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

Respuestas de error

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