Validate

Validate

Validate an audience criteria definition and, if it passes all validations, run a dry-run against BigQuery. A single engine serves two entry points:

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

Both return the same response shape: IValidateAudienceCriteriaResult, with the validity and the estimated cost of the query. Validation does not return rows or the generated SQL: only whether the definition is executable and how many bytes it would process.

Within a project, every audience other than the root audience is validated 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/validate-from-body

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

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

Request Body

Root level (CriteriaDefinitionDto): the criteria definition, without a wrapper.

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 throughout the 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.

Shape of value 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 (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 that of where.

timeWindow — time window (TimeWindowDto)

Union discriminated by timeOperator. Restricts the block to a time period over a TIMESTAMP catalog column (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. 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

Definition of an audience of users with 3 or more COMPLETED transactions in the last 90 days.

curl -X POST https://api.reten.ai/api/audience-criterias/validate-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
            }
          ]
        }
      }
    ]
  }'

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

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

The response is documented in IValidateAudienceCriteriaResult, with a valid example and an invalid one.

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

Validates 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.

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

Path Parameters

This endpoint receives no body and no query params.

Example

curl -X POST https://api.reten.ai/api/audience-criterias/f47ac10b-58cc-4372-a567-0e02b2c3d479/validate \
  -H "Authorization: Bearer <token>" \
  -H "x-tenant-id: <tenant-id>" \
  -H "x-project-id: <project-id>"

import axios from 'axios';

const id = 'f47ac10b-58cc-4372-a567-0e02b2c3d479';
const response = await axios.post(
  `https://api.reten.ai/api/audience-criterias/${id}/validate`,
  undefined, // no body
  { headers: { Authorization: 'Bearer <token>', 'x-tenant-id': '<tenant-id>', 'x-project-id': '<project-id>' } },
);
const result = response.data; // IValidateAudienceCriteriaResult

Response — IValidateAudienceCriteriaResult

Status 201 Created on both endpoints. The body reports the result of the BigQuery dry-run:

Example — valid (valid: true)

A 201 response to a definition that compiles and passes the dry-run:

{
  "valid": true,
  "bytesProcessed": 10485760
}

When valid is true, errors is omitted and bytesProcessed carries the BigQuery estimate (in this example, ~10 MB).

Example — invalid (valid: false)

The definition passed structural and business validation and compiled to SQL, but the BigQuery dry-run rejected it (e.g. a catalog column that does not yet exist in the real table of the dataset, or a query whose estimated cost exceeds the billable bytes limit). Even so, the status is 201:

{
  "valid": false,
  "errors": [
    "Unrecognized name: legacy_column at [3:8]"
  ],
  "bytesProcessed": 0
}

With valid: false, errors carries the BigQuery message and bytesProcessed is 0.

Intersection with the root audience

Every project has a root audience, and every other audience of the project is evaluated within it. The dry-run runs on the same SQL that Generate SQL returns: for any audience that is not the root audience, intersected with the project's root audience. So valid and bytesProcessed refer to that intersected query, and the estimate includes the root audience's part.

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

Structural validation vs. dry-run

This is the key point of the resource: not all failures reach errors[]. A request goes through stages and each one fails differently.

In other words:

• Everything that happens before the dry-run (stages 1–3) that fails responds with an HTTP error and does not produce an IValidateAudienceCriteriaResult body. For example: a table outside the catalog, a criteria that does not project its identity column, a malformed timeWindow, a nonexistent id or criteriaId, or an operandCriteriaId that does not exist.
• valid: false is exclusive to the dry-run: the definition was already structurally valid and compiled to SQL, but BigQuery rejected it when estimating it. The status is still 201.

Validation Rules

Before the dry-run, 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). message is an array of strings and unknown properties are rejected (including name/description/format).
2. Business validation (the definition must generate valid SQL that is coherent against the catalog). message is a single string with the broken rule, and it stops at the first violated invariant.

Error Responses

These are the HTTP errors (distinct from valid: false, which travels with status 201):