Basic Syntax
The expression language includes support for field references and string and numeric literals, as well as basic predicate and arithmetic operators.
Field References
Input fields can be referenced within an expression, and the value of that field will be used when the expression is evaluated.
If a field name contains only alphanumeric characters and starts with a letter, you can reference it simply by its name; for example, the expression:
Field1
returns the value in Field1 when the expression is evaluated.
If a field name contains other types of characters, or does not start with a letter, it can be surrounded by back ticks, such as in the expression:
`Field Number 1`
which returns the value of the field named Field Number 1.
Even when using the back tick notation, the following characters within a field name should be escaped:
Any other Unicode character can be included directly, escaped as \uXXXX, where XXXX is the four-digit hexadecimal code point of the character.
Literals
In addition to input fields, you can also use literal values within an expression. These values remain constant, regardless of the record against which the expression is being evaluated.
Numeric Literals
Numeric literals can be entered directly into an expression. These include integers (12 or 4321) and floating point numbers (3.14159). Any type of numeric literal can be made negative by preceding it with a negative sign (-123 or -3.5).
String Literals
To enter a string literal into an expression, surround it with double quotes. For example, the expression:
"Hello, world!"
always evaluates to the string Hello, world!.
The following characters within a string literal should be escaped:
Any other Unicode character can be included directly, or escaped as \uXXXX, where XXXX is the four-digit hexadecimal code point of the character.
Null Values
A null value can be added to an expression by using the null keyword. The type of this null value will be automatically determined based on the surrounding expression.
The keyword null cannot form an entire expression, as fields in a record cannot be of the null type.
Predicate Operators
The expression language contains many commonly used predicates. These functions can be used in conjunction with each other by stringing predicates together with the logical functions (and, or). All of these operators return a Boolean token value: one of true, false, or null.
If an argument to a predicate operator is null, the result will always be null. The exceptions to this rule are the isX/notX operators; these will never return null, only true or false.
Based on the predicate function, an expression given to a function to evaluate may be:
• The name of an input field (evaluates to the current value of the field)
• A constant value
• An arithmetic function (see the following section)
• A scalar function (in which case the return value of the function is evaluated)
For a list of available predicate functions, see
Available Functions.
Arithmetic Operators
The expression language provides the common arithmetic functions. All of these operators return numeric values. Arithmetic functions are listed in
Available Functions.
Conditional Operators
The expression language supports the common if-then-else conditional expression. The expression will evaluate the provided predicate and return the appropriate sub-expression based on the result.
The expression language also supports switch- or case-style expressions, using the case, when, then, else, and end operators. The value associated with the first matching case will be returned. If no matching case is found, the default value specified using else will be returned; otherwise, if no default value is specified, null will be returned. The following examples show how these operators can be used.
With a base expression
case `Department Code`
when "01" then "Management"
when "02" then "Sales"
when "03" then "Engineering"
end
In the above example, the field Department Code is compared against each case string. If the value of Department Code were "01", then the expression would return "Management"; otherwise, if the value were "02", then the expression would return "Sales", and so on. If the value of Department Code did not match any of the cases, null would be returned.
The following example would exhibit the same behavior as that above, except if no match were found, the expression would return "Invalid Department" rather than null.
With a base expression and a default value
case `Department Code`
when "01" then "Management"
when "02" then "Sales"
when "03" then "Engineering"
else "Invalid Department"
end
The conditional operators can also be used without a base expression, in which each case must be a Boolean predicate, and the first one to evaluate to true is considered a match.
Without a base expression
case
when Hour < 12 then "Morning"
when Hour < 18 then "Afternoon"
when Hour < 22 then "Evening"
else "Night"
end
In the above example, the expression returns "Morning" if the value of Hour is less than 12; otherwise, it returns "Afternoon" if the value of Hour is less than 18, and so on. If none of the predicates is true, the expression returns "Night". Similarly to when a base expression is used, if no true predicate is found and no default value is specified, the expression will return null.
Available conditionals are listed in
Available Functions.
Parentheses
Multiple expressions can be used together by separating the expressions with the logical functions: and, or. By default, the and logical function takes precedence, but this can be overridden by using parentheses. For example:
In the expression:
a or b and c or d
the and expression will be processed first, followed by the or expressions; however, in the expression:
(a or b) and (c or d)
the or expressions will be processed first, followed by the and expression. Likewise, in the expression:
a + b * c + d
the multiplication operation will be performed first, followed by the addition operations, whereas in the expression:
(a + b) * (c + d)
the addition operations will be performed first, followed by the multiplication operation.