Audience catalog

Catalog

The catalog answers what can be filtered. There are two routes: one lists the available tables and the other, for a table, everything it offers —scalar columns and RECORD REPEATED columns.

Without the catalog the definition is not buildable: there is no other way to know which is the identity column of a table, which TIMESTAMP column it suggests as the time reference, or that attributes is a repeated record and not a comparable column.

Auth: Required — audience-criteria:view permission on both routes

GET /api/audience-criterias/tables

Lists the catalog tables on which an audience can be built. The catalog is identical across tenants: this route does not query the tenant's dataset.

Example

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;

Response 200 OK

An array of 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

Returns everything the catalog offers about a table. Unlike /tables, this route reconciles the catalog against the real schema of the tenant's dataset before responding.

Path Parameters

Example

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;

Response 200 OK

An array of IAudienceColumn: a discriminated union by kind with two variants.

• kind: "scalar" — a column that can be filtered directly:

  Field	Type	Description
  columnName	string	Column name. For leaves of a non-repeated STRUCT it is the dotted path (pricing.final_amount).
  kind	"scalar"	Discriminator.
  type	CatalogFieldTypeEnum	Catalog type; it determines which comparison operators it admits.
  isIdentity	boolean	true if it is the identity column of the table. At most one column per table has it.
  isDefaultTimeReference	boolean	true if it is the table's suggested time reference. It is a suggestion: the window can be anchored on another TIMESTAMP column.

• kind: "record" — a RECORD REPEATED column, filterable only with a record filter:

  Field	Type	Description
  columnName	string	Name of the repeated column.
  kind	"record"	Discriminator.
  fields	IAudienceColumn[]	Filterable sub-fields, relative to the record. It may contain other record.
  isIdentity	false	Always false: a repeated record cannot be the identity of the table.
  isDefaultTimeReference	false	Always false: a repeated record cannot anchor the time window.

The fields of a record use the same scalar | record union, so the rule of narrowing by kind applies at every level.

Example response

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

How each variant is used in the definition

Error Responses

GET /api/audience-criterias/tables does not query the tenant's dataset, so it only returns 200, 401 or 403.