Catálogo de audiências

Catálogo

O catálogo responde o que pode ser filtrado. São duas rotas: uma lista as tabelas disponíveis e a outra, para uma tabela, tudo o que ela oferece —colunas escalares e colunas RECORD REPEATED.

Sem o catálogo a definição não é construível: não há outra forma de saber qual é a coluna de identidade de uma tabela, que coluna TIMESTAMP ela sugere como referência temporal, nem que attributes é um registro repetido e não uma coluna comparável.

Auth: Obrigatória — permissão audience-criteria:view em ambas as rotas

GET /api/audience-criterias/tables

Lista as tabelas do catálogo sobre as quais uma audiência pode ser construída. O catálogo é idêntico entre tenants: esta rota não consulta o dataset do tenant.

Exemplo

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;

Resposta 200 OK

Um array 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

Retorna tudo o que o catálogo oferece sobre uma tabela. Diferente de /tables, esta rota reconcilia o catálogo contra o schema real do dataset do tenant antes de responder.

Parâmetros de rota

Exemplo

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;

Resposta 200 OK

Um array de IAudienceColumn: uma união discriminada por kind com duas variantes.

• kind: "scalar" — uma coluna que pode ser filtrada diretamente:

  Campo	Tipo	Descrição
  columnName	string	Nome da coluna. Para folhas de um STRUCT não repetido é o path com ponto (pricing.final_amount).
  kind	"scalar"	Discriminador.
  type	CatalogFieldTypeEnum	Tipo do catálogo; determina quais operadores de comparação ela admite.
  isIdentity	boolean	true se é a coluna de identidade da tabela. No máximo uma coluna por tabela a tem.
  isDefaultTimeReference	boolean	true se é a referência temporal sugerida da tabela. É uma sugestão: a janela pode ser ancorada em outra coluna TIMESTAMP.

• kind: "record" — uma coluna RECORD REPEATED, filtrável apenas com um filtro de registro:

  Campo	Tipo	Descrição
  columnName	string	Nome da coluna repetida.
  kind	"record"	Discriminador.
  fields	IAudienceColumn[]	Sub-campos filtráveis, relativos ao registro. Pode conter outros record.
  isIdentity	false	Sempre false: um registro repetido não pode ser a identidade da tabela.
  isDefaultTimeReference	false	Sempre false: um registro repetido não pode ancorar a janela temporal.

Os fields de um record usam a mesma união scalar | record, então a regra de estreitar por kind se aplica em cada nível.

Exemplo de resposta

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

Como cada variante é usada na definição

Respostas de erro

GET /api/audience-criterias/tables não consulta o dataset do tenant, então só retorna 200, 401 ou 403.