Preview

Preview

Runs an audience criteria against BigQuery (bounded by limit) and returns a sample of the real rows it matches plus the total of the universe. A single engine serves two entry points:

• POST /api/audience-criterias/preview-from-body — runs a definition sent in the body (not yet persisted).
• POST /api/audience-criterias/:id/preview — runs an already saved criteria, referenced by its id.

Both return the same response shape: IPreviewAudienceCriteriaResult.

Unlike Generate SQL, preview does not return SQL; and unlike Validate (which only does a dry-run), preview does bring data: it runs the query and shows you rows.

Within a project, every audience other than the root audience runs intersected with the project's root audience — see Intersection with the root audience.

Auth: Required — audience-criteria:view-sql permission (both endpoints).

POST /api/audience-criterias/preview-from-body

Runs a definition sent in the body, without persisting it.

Auth: Required — audience-criteria:view-sql permission

Request Body

Root level (PreviewFromBodyDto): the criteria definition (CriteriaDefinitionDto) plus the limit field.

Criteria Definition

It is the same tree that Create receives, without the name/description fields. It is documented here in a self-contained way.

queryBlocks[] — query block

Each element of queryBlocks (QueryBlockDto) is a complete SQL statement:

ColumnRefDto — column reference

Used across the entire tree (select, filters, group by, joins, aggregates, time window):

Every column is always qualified with its table to avoid ambiguity.

from — data source (FromDto)

Each JoinDto:

Each JoinPredicateDto is a pair of columns: { left: ColumnRefDto, right: ColumnRefDto }.

select — projection (SelectDto)

The items are discriminated by kind:

• Column — kind: "column":

  Field	Type	Required	Description
  kind	"column"	Yes	Discriminator.
  column	ColumnRefDto	Yes	Projected column.
  alias	string	No	Must match ^[A-Za-z_][A-Za-z0-9_]*$.

• Aggregate — kind: "aggregate":

  Field	Type	Required	Description
  kind	"aggregate"	Yes	Discriminator.
  aggregate	AggregateDto	Yes	Aggregation expression.
  alias	string	Yes	Here the alias is required. Same identifier regex.

AggregateDto:

operand — what is aggregated — is discriminated by kind:

ArithmeticOperatorEnum: ADD | SUBTRACT | MULTIPLY | SAFE_DIVIDE (a division that yields NULL when the denominator is zero instead of failing the query). The columns of an arithmetic expression must be numeric (INT64, NUMERIC, BIGNUMERIC, FLOAT64), and expressions nest up to 3 levels of arithmetic, counting the outermost one.

where — predicate tree (WhereDto)

The where is a recursive tree. The root node is always a group, and its leaves come in two kinds:

Group — kind: "group"

Column leaf — kind: "predicate"

Compares a scalar column qualified by its table.

{
  "kind": "predicate",
  "column": { "table": "user_properties", "column": "country" },
  "comparisonOperator": "IN",
  "value": ["CL", "MX"]
}

Record leaf — kind: "recordPredicate"

Filters by a RECORD REPEATED column (an array of structs, such as attributes). It means at least one element of the array satisfies the sub-filter.

{
  "kind": "recordPredicate",
  "column": { "table": "event_transactions", "column": "attributes" },
  "subWhere": {
    "kind": "group",
    "logicalOperator": "AND",
    "children": [
      { "kind": "predicate", "field": "key", "comparisonOperator": "EQUALS", "value": "canal" },
      { "kind": "predicate", "field": "value", "comparisonOperator": "EQUALS", "value": "web" }
    ]
  }
}

Which columns accept a record filter is stated by the catalog: the ones that come with kind: "record".

Relative sub-tree

The subWhere is an AND/OR group whose leaves are resolved against the sub-fields the record declares.

There is a single difference with the top-level tree, and it is the most common source of errors:

Leaves allowed inside a relative sub-tree:

• Scalar leaf — { "kind": "predicate", "field": string, "comparisonOperator": …, "value"?: … }. The field must be a scalar sub-field of the record.
• Nested record — { "kind": "recordPredicate", "field": string, "subWhere": … }. A record inside another record; it nests with no declared limit, as long as the catalog declares each level.
• Group — the same group shape, to combine the previous leaves with AND/OR.

value shape by comparisonOperator

ScalarValue = string | number | boolean. In addition, each operator must be compatible with the column type (see validation rules).

groupBy — grouping columns

Optional list of ColumnRefDto[]. When the block aggregates (it declares groupBy or has an aggregate in the select), the groupBy must match exactly the non-aggregated columns of the select (see validation rules).

having — filter over aggregates (HavingDto)

Same recursive structure as where (nested AND/OR groups and the same value rule per operator), but the leaf operates over an aggregate, not over a column:

• Predicate (leaf) — { kind: "predicate", aggregate: AggregateDto, comparisonOperator: ComparisonOperatorEnum, value?: PredicateValue }.
• Group — identical to the one in where.

timeWindow — time window (TimeWindowDto)

Discriminated union by timeOperator. Bounds the block to a time period over a TIMESTAMP column of the catalog (reference). It is a sibling field of where, not a node of the filter tree.

TimeUnitEnum: DAYS | WEEKS | MONTHS | YEARS.

Business semantics of each operator:

• ALL_TIME — no window; considers the entire history.
• IN_THE_LAST — rolling window relative to "now": the last value unit (e.g. last 30 DAYS). Recomputed on every run.
• IN_THE_FIRST — window relative to the origin of the user's lifecycle (their signup date): the first value unit of each user's life. It is anchored per user, not to a fixed date.
• SINCE — from the civil date from (inclusive) onward.
• BETWEEN — between from and to, both civil dates inclusive of their full day.

composedWith[] — composition with other audiences

Each element (CreateCompositionDto) combines this definition with another audience via a set operation:

Example

Audience of users with 3 or more COMPLETED transactions in the last 90 days. It projects only user_id, like the root audience's default definition (see Intersection with the root audience). A sample of 50 rows is requested (limit).

curl -X POST https://api.reten.ai/api/audience-criterias/preview-from-body \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{
    "queryBlocks": [
      {
        "order": 0,
        "from": { "table": "event_transactions" },
        "select": {
          "distinct": false,
          "items": [
            {
              "kind": "column",
              "column": { "table": "event_transactions", "column": "user_id" }
            }
          ]
        },
        "timeWindow": {
          "timeOperator": "IN_THE_LAST",
          "reference": { "table": "event_transactions", "column": "event_date" },
          "unit": "DAYS",
          "value": 90
        },
        "where": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "column": { "table": "event_transactions", "column": "status" },
              "comparisonOperator": "EQUALS",
              "value": "COMPLETED"
            }
          ]
        },
        "groupBy": [{ "table": "event_transactions", "column": "user_id" }],
        "having": {
          "kind": "group",
          "logicalOperator": "AND",
          "children": [
            {
              "kind": "predicate",
              "aggregate": {
                "aggregationOperator": "COUNT",
                "operand": { "kind": "star" }
              },
              "comparisonOperator": "GREATER_THAN_OR_EQUAL",
              "value": 3
            }
          ]
        }
      }
    ],
    "limit": 50
  }'

import axios from 'axios';

const body = {
  queryBlocks: [
    {
      order: 0,
      from: { table: 'event_transactions' },
      select: {
        distinct: false,
        items: [
          {
            kind: 'column',
            column: { table: 'event_transactions', column: 'user_id' },
          },
        ],
      },
      timeWindow: {
        timeOperator: 'IN_THE_LAST',
        reference: { table: 'event_transactions', column: 'event_date' },
        unit: 'DAYS',
        value: 90,
      },
      where: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            column: { table: 'event_transactions', column: 'status' },
            comparisonOperator: 'EQUALS',
            value: 'COMPLETED',
          },
        ],
      },
      groupBy: [{ table: 'event_transactions', column: 'user_id' }],
      having: {
        kind: 'group',
        logicalOperator: 'AND',
        children: [
          {
            kind: 'predicate',
            aggregate: {
              aggregationOperator: 'COUNT',
              operand: { kind: 'star' },
            },
            comparisonOperator: 'GREATER_THAN_OR_EQUAL',
            value: 3,
          },
        ],
      },
    },
  ],
  limit: 50, // optional; defaults to 100
};

const response = await axios.post(
  'https://api.reten.ai/api/audience-criterias/preview-from-body',
  body,
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const preview = response.data; // IPreviewAudienceCriteriaResult

The response is documented in IPreviewAudienceCriteriaResult, with a non-empty rows example.

POST /api/audience-criterias/:id/preview

Runs an already saved criteria, referenced by its id. The definition does not travel in the body: it is taken from the criteria persisted in the active project. The body only carries limit.

Auth: Required — audience-criteria:view-sql permission

Path Parameters

Request Body

PreviewQueryDto — a single, optional field:

An empty body ({}) is valid: it uses the default limit (100).

Example

curl -X POST https://api.reten.ai/api/audience-criterias/f47ac10b-58cc-4372-a567-0e02b2c3d479/preview \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>" \
  -H "Content-Type: application/json" \
  -d '{ "limit": 50 }'

import axios from 'axios';

const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await axios.post(
  `https://api.reten.ai/api/audience-criterias/${id}/preview`,
  { limit: 50 }, // optional; defaults to 100
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const preview = response.data; // IPreviewAudienceCriteriaResult

limit — sample size

limit bounds only how many rows the response brings in rows (the sample you see), not the universe that the audience matches.

• Range: integer 1..500 (less than 1 or greater than 500 ⇒ 400).
• Default: 100 (PREVIEW_ROW_LIMIT_DEFAULT) when omitted.

Response — IPreviewAudienceCriteriaResult

Example

201 response to the example above (limit: 50). The audience matches 4821 users; rows shows the first 50 (trimmed to 3 here for brevity), each with the only projected column (user_id):

{
  "rows": [
    { "user_id": "u_9f3a1c" },
    { "user_id": "u_2b7e04" },
    { "user_id": "u_c081ff" }
  ],
  "totalCount": 4821,
  "bytesProcessed": 5242880
}

The keys of each object in rows (user_id) come from the audience's select. totalCount (4821) is the complete universe, greater than the 50 rows of the sample.

Intersection with the root audience

Every project has a root audience, and every other audience of the project is evaluated within it. Preview runs the same SQL that Generate SQL returns: for any audience that is not the root audience, intersected with the project's root audience. So rows and totalCount are the audience's matches inside the root audience, and bytesProcessed includes the root audience's part of the query.

There is no intersection when the audience run is the root audience itself — :id/preview with the root audience's id, or a preview-from-body draft whose criteriaId is the root audience.

Validation Rules

Before executing, the definition goes through the same two layers of validation as Create, and both return 400 Bad Request:

1. DTO validation (structure, types, enums, required fields, limit within range). message is an array of strings and unknown properties are rejected (including name/description).
2. Business validation (the definition must generate valid SQL coherent against the catalog). message is a single string with the violated rule.

Error Responses