Skip to content
Optima docs
Reference

Expressions

The expression language used in eligibility rules, score formulas, signal transforms, cohort filters, data-contract rules and webhook success conditions.

An expression is a short formula that Optima evaluates for one profile, one value or one response. It returns true or false, a number, or a piece of text. The same language is used in several places in the console; what differs is the data the expression can read and what the result must be.

Most screens offer a point-and-click builder for the common cases. Use an expression when the builder cannot say what you need. Expressions are compiled when you save, so a mistake in the syntax is rejected on the spot with a message that points at the position.

Where expressions are used

Where in the consoleLabelReadsMust returnIf it fails
OffersEligibility expression (under Advanced: expression)attributes.*, signals.*, context.*, profile_idtrue or falseThe offer is excluded for that profile (reason Eligibility expression error).
Offers and offer cataloguesScore formula / Scoring formulaattributes.*, signals.*, context.*A numberThe offer scores 0. A scoring error never excludes the offer; running over the time limit does.
SignalsTransform expressionvalue, the signal's raw resultA value of the signal's typeThe raw value is stored unchanged.
CohortsFilter expressionThe signal values of the entity, by signal nametrue or falseA signal name that does not exist matches nobody.
Data contractsValidation expressionvalue, attrstrueThe value is rejected.
Data contractsTransform expressionvalueThe replacement valueThe value is kept unchanged.
Journey Webhook nodeSuccess whenstatus, body and the keys you mapped from the responsetrue or falseDecides the success or error branch.
Journey Condition and goal (older ones)Legacy expressionattributes.*, signals.*true or falseStill evaluates. New conditions use a segment and the condition builder.

Details of each:

  • Eligibility and score. attributes.* are the profile's attributes, signals.* its signals, and context.* the situational values supplied with the request, such as channel or page. A name that does not exist is not a save-time error: it evaluates to nothing (nil). Using nothing in a comparison or in arithmetic is a run-time error for that profile, so write expressions that cope with sparse profiles (see ?? below). Example eligibility: signals.churn_risk > 0.7 && attributes.country == "SK". Example score: signals.engagement * 10 + (attributes.tier == "gold" ? 5 : 0).
  • Signal transform. Runs once per profile on every recompute. value is a number for numeric signals and text for text signals, and the expression is checked against that type when you save: arithmetic on a text signal, or upper() on a numeric one, is refused. The result is converted to the signal's type afterwards; an integer signal drops the decimals (0.42 becomes 0), so scale before you round. Examples: min(value, 1000), round(value * 100) / 100, upper(value). A transform applies on the next recompute and is not retroactive.
  • Cohort filter. Reads only the signals of that entity; profile attributes are not in scope. Example: churn_risk_score > 0.7 && rfm_score >= 4.
  • Data contracts. value is the incoming value of the attribute and, for validation only, attrs holds every attribute in the payload. Validation must return true; anything else rejects the value. Example: len(value) > 3 and attrs.country == "SK". Transform example: phone_e164(trim(value)). Four extra helpers exist only here, listed below.
  • Webhook success. "2xx" (the default) and "any" are shorthand; anything else is an expression such as status == 200 && outcome == "accepted".

Writing expressions

Values

KindExamples
Numbers42, 0.7
Text"gold" or 'gold'
True and falsetrue, false
Nothingnil
Lists["a", "b"]
Number ranges1..5 (a list of 1 to 5)

Read a value by name. Reach inside with a dot or brackets: attributes.country, attributes["country"], attrs.tags[0]. Put ?. before a name to read it safely when something earlier may be missing: attributes?.address?.city.

Operators

OperatorsMeaning
== != < <= > >=Compare
+ - * / % **Arithmetic. ** (also written ^) is the power. + also joins text.
and or notCombine conditions
in, not inMembership: value in ["a", "b"]
contains, startsWith, endsWithText tests: value contains "@"
matchesRegular-expression test: value matches "^SK-[0-9]+$"
a ? b : cChoose: attributes.age >= 18 ? "adult" : "minor"
a ?? bA fallback for a missing value: attributes.nick ?? "friend"

&&, || and ! are accepted as other spellings of and, or and not.

+ adds numbers or joins two pieces of text. Mixing them ("x" + 1) is refused when you save with invalid operation: string + int; convert first, for example "x" + string(1).

Functions

GroupFunctions
Textlen, upper, lower, trim, trimPrefix, trimSuffix, split, replace, indexOf, hasPrefix, hasSuffix, join
Numbersabs, ceil, floor, round, min, max, sum, mean, median
Conversionint, float, string, toJSON, fromJSON
Listslen, first, last, take, reverse, sort, uniq, concat, flatten, keys, values
Lists with a conditionall, any, none, one, filter, map, count, find, findIndex, sortBy, groupBy, reduce
Timenow(), date("2026-01-02"), duration("2h")

The condition in a list function refers to the current entry as #:

all(attrs.tags, # != "blocked")
filter(attrs.tags, # startsWith "vip")
map(attrs.tags, upper(#))
count(attrs.tags, # contains "a")

Examples of results, for value = " SK-123 ":

ExpressionResult
trim(value)"SK-123"
upper(trim(value))"SK-123"
replace(trim(value), "-", "")"SK123"
trim(value) matches "^SK-[0-9]+$"true
len(split("a,b,c", ","))3
round(3.14159 * 100) / 1003.14

Helpers for data contracts

These four exist only in data-contract validation and transform expressions.

HelperWhat it doesExample
trim_lower(text)Trims spaces and lowercases.trim_lower(" SK-123 ") is "sk-123"
phone_e164(text)Keeps the digits and a leading +, and adds a + if there is none. It does not know country codes, so supply the full international number.phone_e164("(421) 905 123 456") is "+421905123456"
parse_iso_date(text)Reads an ISO 8601 date (2026-10-15, 2026-10-15T09:30:00, or with a zone) and returns it as UTC in RFC 3339 form. Anything it cannot read comes back unchanged.parse_iso_date("2026-10-15") is "2026-10-15T00:00:00Z"
truncate(text, n)Cuts the text to at most n characters.truncate("abcdefghij", 5) is "abcde"

Limits

Expressions are bounded so that one cannot slow everything down. These limits are checked when you save, and a refused expression says which one it hit.

LimitValue
Length of an expression8,192 bytes
Size (number of parts the formula is made of)About 2,000
Nesting of list functions (all, any, map, filter and similar inside each other)2 levels. all(a, any(b, all(c, true))) is refused.
A written range such as 1..5000At most 1,000 numbers
A text result (or the total text in a list)32 KB
Running timeCut off if an expression runs too long: 50 ms for a data-contract rule, 200 ms for a signal transform, 500 ms for a cohort filter or an offer expression

repeat is not available. An expression that runs over its time limit counts as a failure: an offer whose eligibility expression or score formula overruns is excluded for that profile.

Common problems

SymptomCauseWhat to do
invalid operation: string + int on save+ between text and a number.Convert one side with string() or int().
expression nests predicate functions … 3 deep; the limit is 2List functions inside list functions inside list functions.Split the work: compute a signal or a computed attribute first, and use that.
A transform seems to do nothingThe expression failed at run time, so the raw value was kept.Test it on sample values; check the type (text or number).
An offer never showsThe eligibility expression errors for profiles missing a value.Add ?? default for fields that can be absent.
A score formula returns 0 for everyoneThe formula errors or returns text.Return a number. signals.x ?? 0 covers a missing signal.
A cohort filter matches nobodyA signal name is misspelt or does not exist for that entity.Check the name on the Signals screen.

On this page