Amba

Segment Operators

All 13 operators supported by the Amba segment rule evaluator, the built-in device fields, and examples of the fields each one works on.

This page lists every operator the segment rule evaluator supports, the fields each one is valid against, and the exact SQL that gets emitted. All identifiers are whitelisted — admin-authored rules cannot inject arbitrary SQL.

Operator reference

OperatorValid onExample
eqanyentitlements.is_active eq true
neqanyentitlements.product_id neq "premium_monthly"
gtnumeric / timestampcreated_at gt "2026-01-01"
gtenumeric / timestampentitlements.expiration_date gte "2026-12-01"
ltnumeric / timestamplast_seen_at lt "2026-06-01"
ltenumeric / timestampfirst_seen_at lte "2026-03-31"
containsstring / text-castable fieldemail contains "@example.com"
not_containsstring / text-castable fieldemail not_contains "spam"
existsanyemail exists
not_existsanyemail not_exists
withindate column onlylast_seen_at within "7d"
not_withindate column onlylast_seen_at not_within "30d"
inany (array of up to 100)country in ["US", "CA"]

An operator outside this list answers 400 INVALID_SEGMENT_RULES when you create or update the segment.

Field domains

The evaluator resolves field into one of five target surfaces. Anything outside the whitelists silently falls back to FALSE (the condition never matches) rather than raising — an admin typo in a rule won't take the workflow down.

Direct user fields

Whitelisted: id, external_id, anonymous_id, email, phone, display_name, first_seen_at, last_seen_at, created_at.

{ "field": "email", "op": "exists" }
{ "field": "last_seen_at", "op": "within", "value": "14d" }

Built-in device fields

The SDKs report four fields about the device on every request from a signed-in user, and Amba stores them on the user. A request that does not carry a value leaves the stored one as it is, and Amba writes only when a value changed.

FieldValuesOperators
platformThe SDK in use: swift, kotlin, react-native, expo, dart, csharp, webeq, neq, in, exists, not_exists
osThe device operating system: ios, android, web, macos, windows, linux, othereq, neq, in, exists, not_exists
app_versionYour app's version string, such as 2.4.1 or 3.0.0-beta.2eq, neq, gt, gte, lt, lte, exists, not_exists
countryThe ISO 3166-1 alpha-2 region of the device locale, such as US or FReq, neq, in, exists, not_exists

platform and os compare in lowercase and country in uppercase, so "iOS" and "us" match. os accepts only the seven values above.

app_version compares in semantic-version order: 2.10.0 is above 2.9.3, a missing minor or patch counts as 0 (2.4 equals 2.4.0), a pre-release sorts below its release (3.0.0-beta.2 < 3.0.0), and build metadata (+77) is ignored. A leading v is allowed. gt / gte / lt / lte need a version as the value, and never match a user whose stored version is not one. For a version string that is not a semantic version (nightly-7), eq / neq compare the text as written. neq matches every user with a stored version other than the value, whatever its form; a user with no stored version matches neither eq nor neq.

{ "field": "os", "op": "eq", "value": "ios" }
{ "field": "app_version", "op": "lt", "value": "2.4" }
{ "field": "country", "op": "in", "value": ["US", "CA", "GB"] }

The fields change as users update the app or travel, and memberships follow on the next evaluation.

Custom properties (properties.*)

Any path matching [a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)*. Nested keys are safe to address with dot notation:

{ "field": "properties.plan", "op": "contains", "value": "premium" }
{ "field": "properties.user.onboarded", "op": "eq", "value": true }

A properties.* comparison follows the type of the rule's value: a string compares with the property's text ({ field: "properties.plan", op: "eq", value: "pro" } matches plan: "pro"), a number compares numerically and counts a JSON number or a numeric string (gt 9 matches 10), and a boolean matches true / false or the strings "true" / "false". An object or array value supports eq / neq against the whole JSON value. A user without the property matches none of these operators.

within / not_within are not supported on property fields — promote the value to a typed column if you need time-based filtering.

Entitlements (entitlements.*)

Whitelisted columns: entitlement_id, product_id, is_active, store, period_type, purchase_date, expiration_date.

{ "field": "entitlements.is_active", "op": "eq", "value": true }
{ "field": "entitlements.product_id", "op": "eq", "value": "premium_monthly" }

A user matches the clause if they hold any entitlement satisfying it.

Unknown fields

Treated as never-matching. No error is raised — the condition simply evaluates to false. This keeps a misconfigured rule from taking the whole segment evaluation down.

Duration literals (within / not_within)

Values are parsed as <number><unit>:

UnitMeaning
mminutes
hhours
ddays
wweeks

Examples: "15m", "24h", "7d", "2w". Invalid literals (bad unit, non-numeric) fall back to FALSE.

{ "field": "last_seen_at", "op": "within", "value": "7d" }
{ "field": "created_at", "op": "not_within", "value": "30d" }

within matches values from the last N <unit>; not_within matches values older than that.

contains / not_contains

Case-insensitive substring match. The value must be a string — a numeric value on a contains clause never matches.

{ "field": "properties.tags", "op": "contains", "value": "fitness" }
{ "field": "email", "op": "not_contains", "value": "@example.com" }

On entitlement fields the same substring check runs against each of the user's entitlements; a user matches if any one of them does.

in

Matches when the field equals any value in the array (1 to 100 strings, numbers or booleans). On a property, a number or boolean matches its JSON spelling (3, true). On entitlements, a user matches if any one of their entitlements does.

{ "field": "properties.plan", "op": "in", "value": ["pro", "team"] }
{ "field": "platform", "op": "in", "value": ["swift", "kotlin"] }

exists / not_exists

On direct user fields: matches when the field is set (exists) or unset (not_exists).

On property paths: works the same way over nested property keys.

On entitlements: matches when the user has any entitlement with that field populated.

Composing rules

A rule is a tree of boolean groups. Each group has an operator (AND / OR) and a conditions array; entries in conditions are either leaf conditions or further nested groups. The evaluator wraps each group in parens, so operator precedence is explicit — you don't have to memorise that AND binds tighter than OR.

Flat (single group) rules are still the common case:

{
  "operator": "AND",
  "conditions": [
    { "field": "last_seen_at", "op": "within", "value": "7d" },
    { "field": "entitlements.is_active", "op": "eq", "value": true }
  ]
}

Nested boolean groups

Mix groups to express things like "active users AND (Pro OR Enterprise product)":

{
  "operator": "AND",
  "conditions": [
    { "field": "last_seen_at", "op": "within", "value": "7d" },
    {
      "operator": "OR",
      "conditions": [
        { "field": "entitlements.product_id", "op": "eq", "value": "pro_monthly" },
        { "field": "entitlements.product_id", "op": "eq", "value": "enterprise_monthly" }
      ]
    }
  ]
}

Depth is capped at 5 (the top-level group counts as depth 1). Rules deeper than the cap are rejected with SEGMENT_RULES_TOO_DEEP. An empty inner AND group evaluates to TRUE; an empty inner OR group evaluates to FALSE — algebraic identity, so adding an empty branch never changes the truth value of an enclosing group of the same operator.

Evaluation cadence

Amba recomputes segment_memberships for every segment on a 15-minute cycle, for apps with something to re-evaluate:

  • Your users' data changed (SDK or admin traffic, subscription webhooks): re-evaluated on the next cycle, so within 15 minutes.
  • A rule uses within / not_within: membership changes as time passes even when nothing is written. Amba re-evaluates when the next user crosses a window boundary: within 15 minutes for windows shorter than a day, within the hour for windows of a day or longer (so a user crosses a not_within "7d" boundary within the hour).
  • Neither: membership cannot change, and the cycle skips the app. A full recompute still runs once a day.

Background evaluation covers apps with SDK or admin traffic in the last 7 days. An app with none is picked up again on its next request. A segment's last_evaluated_at moves only when a re-evaluation runs, so on an idle app it can be up to a day old while its memberships are current.

Manual POST /v1/admin/projects/:projectId/segments/:id/evaluate triggers a one-off immediate run against that segment only.

Next