Segmentation Expressions

Segmentation Expressions are used in Query API and Raw Data Export API to allow for more specificity when querying your data.

The power of segmentation comes from the ability to define custom expressions based on property names in the where and on parameters. An expression consists of a property, combined with one or more operators that can perform mathematical operations, logical operations, or typecasts. Expression are then applied in the where and on parameters of the segmentation API. The full grammar for expressions is given here:

<expression> ::= 'properties["' <property> '"]'
                | <expression> <binary op> <expression>
                | <unary op> <expression>
                | <math op> '(' <expression> ')'
                | <typecast op> '(' <expression> ')'
                | '(' <expression> ')'
                | <boolean literal>
                | <numeric literal>
                | <string literal>
  <binary op> ::= '+' | '-' | '*' | '/' | '%' | '==' | '!=' |
                  '>' | '>=' | '<' | '<=' | 'in' | 'and' | 'or'
   <unary op> ::= '-' | 'not'
    <math op> ::= 'floor' | 'round' | 'ceil'
<typecast op> ::= 'boolean' | 'number' | 'string'
   <property> ::= 'properties["' <property name> '"]'

Examples

Expression	Description
`properties["account_id"] in [1,2,3,4]`	Returns `true` if `account_id` event property is 1, 2, 3, or 4, otherwise `false`.
`user["$email"] == "[email protected]"`	Returns `true` if `$email` user property is "[email protected]" otherwise `false`.
`defined(properties["My Prop"])`	Returns `true` if `My Prop` event property has any value, otherwise `false`. This is the same as "is set" in the UI.
`not defined(properties["city"])`	Returns `false` if `city` event property has any value, otherwise `true`. This is the same as "is not set" in the UI.

Typecast Operations

Internally, all properties of events have a type. This type is determined when we parse the event sent to us into a JSON object. Currently, there are three types, string, number, and boolean, which may be specified directly. A property may also have the values null and undefined, which are only handled internally. The default type is string. If you wish to treat an expression as another type, you may use the typecast operators to cast a property to a different type. For example, if properties["signed up"] has values of "true" and "false" as strings, and you wish to encode them as booleans, you may cast them by using the boolean() typecast function: boolean(properties["signed up"]).

The typecasting rules are described below.

Casting to String


Type	Result
String	Same String
Number	String containing the decimal representation of the number.
Boolean	"true" or "false"
null	null
Undefined	undefined

Casting to Number


Type	Result
String	Attempts to interpret the string as a decimal. If this fails, the value becomes undefined.
Number	Same number
Boolean	1.0 if true, 0.0 if false
null	undefined
undefined	undefined

Binary Operations

The arithmetic operators "-", "*", "/", "%" perform the subtraction, multiplication, division, and remainder operations, respectively. The division operator will return undefined if the divisor is 0. The sign of the value of the remainder will be equivalent to the dividend. All four of these operators expect both operands to be of the type number, or else the result is undefined.

The "+" operator behaves as addition if its two operands are of type number. However, if its two operands are of type string, it will concatenate the two strings. In other cases, the result is undefined.

The equals operator "==" will always return a boolean. When its two types are equal, it performs the standard equality comparison based on the values. If the types of its operands are not equal, false is returned. The not equals operator "!=" returns false when the equals operator would return true and vice-versa.

The comparison operators ">", ">=", "<", and "<=" returns a boolean value based on evaluating the comparison when its operands are both of type number. When its types are not equal, undefined is returned.

The "in" operator returns true if both operands are of type string and the first string is a substring of the second. When both operands are of differing types, undefined is returned.

The logical operators "and" and "or" accept boolean and undefined operands. An operand with type undefined evaluates as false. Any other types will result in an error.

Unary and Math Operations

The "-" operator will negate an operand of type number, and return undefined otherwise.

The "not" operator will perform the logical not on an operand of type boolean. It will also evaluate an operand of type undefined as true. All other operands will be evaluated to undefined.

The "floor", "round", and "ceil" functions perform their mathematical operations on an operand of type number. On all other types, it will return undefined.