Blog
Log In

Query expressions

A Segment's Query defines a boolean expression that determines if a user/instance belongs to that given Segment.

A basic query has the following format:

{
  "$<group-operator>": [
    { "<field1>": { "$<operator>": "<value1>" } },
    { "<field2>": { "$<operator>": "<value2>" } },
    ...
  ]
}

Where is the root expression, containing two nested expressions ( and ).

{ 
  "$all": [
    { "lang" : { "$eq" : "en" } },
    { "os" : { "$ne" : "Android" } }
  ]
}

Will match all devices that have an English language setting AND their Operative System is NOT Android.

Additionally, group expressions can be nested:

{ 
  "$all": [
    { "os" : { "$ne" : "Android" } },
    { "$any": [
      { "lang" : { "$eq" : "en" } },
      { "lang" : { "$eq" : "es" } }
    ] }
  ]
}

This expression will match non-Android devices with either English or Spanish language.

Operators

Valid root operators are:

  • $all : All child expressions are required to accept the segment
  • $any : Only one child is required to accept the segment

Valid expression operators are:

  • $eq : The field's value is equal to the specified value
  • $ne : The field's value is not equal to the specified value
  • $lt : The field's value is less than the specified value.
  • $gt : The field's value is greater than the specified value.
  • $lte : The field's value is not greater than the specified value.
  • $gte : The field's value is not less than the specified value.
  • $in : The field's value is in a list of specified values.
  • $nin : The field's value is not in a list of specified values.
  • $like : SQL like expression, used to match values. e.g. "%campaign%"
  • $matches : Regex expression, used to match values. e.g. "User\s\d+"
  • $startsWith : The field's value starts with the specified value.
  • $endsWith : The field's value ends with the specified value.
  • $contains : The field's value contains the specified value.

Additionally, you may skip the operator for $eq expressions:

  • { "field" : { "$eq": "value" } } -> { "field" : "value" }

All operators work on a best effort basis: They will try to match data for every possible value type, and will work even if the field's value and the specified value are of different format.

📘

Evaluation exception handling

In the case that the evaluation is not possible, the expression is evaluated to false.

All the following expressions are accepted:

  • [1,2,3] $contains 2
  • "Hello" $contains "lo"
  • "34" $gt 10 (The string can be parsed as a number)
  • 1 $eq true (1 is a Truthy value)

Fields

Field expressions are JSON-like variables that can also be nested if the field is an object.

Example:
Given "address" : { "country": "Spain", "city": "Barcelona" }
"address.country" -> "Spain"

Some of the available fields are the following:

  • lang : device language as configured by user
  • country : device country as configured by user
  • os : operating system name
  • os_version : os version
  • app_name : application name
  • app_version : app version extracted from app bundle
  • device_type : type of device (E.g. iPad)
  • device_model : manufacturer model of the device (E.g. iPhone 5)
  • geo_hash : latest known user geo-location (if enabled) expressed as a geo-hash code.
  • st : last updated at timestamp UTC
  • session _number : number of times the user has opened the app
  • tags : array of tag names the user has been tagged with
  • tags.XXX : current value of the tag XXX (numerical)
  • user.XXX : custom field added through MOCA SDK

You can get a complete list by accessing Get all fields