# Configuring Jexl operators

You can write a Jexl script as part of the configuration of many lenses. Jexl is a friendly language offering a number of operators which can be applied to transform data (typically the `payload` fields ) or do comparison.

The following is a selection, for more information refer to the Jexl GitHub page.

Operators

Use these operators to perform mathematical operations on values:

Operation Symbol Example

Negate

`!`

`!true``false`

`+`

`3 + 4``7`

Subtract

`-`

`4 - 3``1`

Multiply

`*`

`3 * 8``24`

Divide

`/`

`15 / 4``3.75`

Divide and Floor

`//`

`15 // 4``3`

Modulus

`%`

`23 % 2``1`

Power of

`^`

`2^3``8`

Logical AND

`&&`

`true && true``true`

Logical OR

`+

Comparisons

Use these expressions to compare two values and get a Boolean result. For example, the results can be used for filtering.

Operation Symbol Example

Equal

`==`

`1 == 2``false`

Not Equal

`!=`

`1 != 2``true`

Greater Than

`>`

`2 > 3``false`

Greater Than or Equal

`>=`

`3 >= 3``true`

Less Than

`<`

`2 < 3``true`

Less Than or Equal

`<=`

`2 ⇐ 4``true`

Element in array or string

`in`

`"cat" in ["cat", "dog", "mouse"]``true`

Conditional operators

Conditional operators return the second or third expression based on the result of the first expression. If the first expression (`"Bob" in ["Bob", "Mary"]` below) return `true`, "Yes" is returned. If it returns false, "No" is returned.

Example Result

"Bob" `in` ["Bob", "Mary"] ? "Yes" : "No"

"Yes"

Identifiers

Access variables in the payload with dot notation or by using brackets For example:

```{
name: {
first: 'John'
last: 'Smith'
},
age: 55,
colleagues: [
'Mary',
'Bob',
'Ted'
],
teammate: 2
}```
Example Result

name.first

"John"

colleagues[teammate]

"Ted"

name['la' + 'st']

"Smith"

Collection filtering

Arrays of objects (Collections) can be filtered by including a filter expression in brackets. Properties of each collection can be referenced by prefixing them with a leading dot. The result is an array of objects for which the filter returns a truthy value.

```{
users: [
{ first: 'John', last: 'Smith', age: 20},
{ first: 'Mary', last: 'Jones', age: 46},
{ first: 'Ted', last: 'Cotter', age: 16},
{ first: 'Bob', last: 'White', age: 66}
],
}```
Example Result

users[.last == 'Jones']

[\{ first: 'Mary', last: 'Jones', age: 46}]

[\{ first: 'John', last: 'Smith', age: 20}, first: 'Ted', last: 'Cotter', age: 16}]

users[first == 'John'].last

"Smith"

Lens expression functions

In addition to the general Jexl parsing functionality, Siren Investigate also exposes a number of JavaScript-like functions for use in lens expressions. Payload values, or the results from earlier parsing, are piped into the function using the `|` character. These values become the `val` parameter for the functions below meaning that the `val` does not need to be added in the `()` after the function name. In some cases, this value is all that’s needed by the function and some functions require extra parameters.

Some functions require string inputs and some require integer or floating-point inputs

Table 1. String lens expressions
Function Example Explanation

`payload.IP | split('.', 3)`

Splits an IP address by the '.' and returns the first 3 entries as an array.

`payload.name | endsWith('smith', 10)`

Returns true if `val` ends with `substring`, if `length` is added, that number of characters from the beginning of `val` is checked.

`payload.name | startsWith('smith', 10)`

Returns true if `val` begins with `substring`, if `position` is added, the substring from that position to the end of `val` is checked.

`payload.name | indexOf('smith', 10)`

Returns the position of the first character of `substring` if `val` contains `substring`, if `length` is added, `val` is checked from that position.

upper(val)

`payload.name | upper`

Returns `val` in upper case.

lower(val)

`payload.name | lower`

Returns `val` in lower case.

substring(val, start, end)

`payload.name | substring(5, 10)`

Returns the string within `val` found between `start` and `end`.

replace(val, substring, newSubString)

`payload.name | replace('smith', 'jones')`

Replaces `substring` with `newSubString` in `val`.

Table 2. Number lens expressions
Function Example Explanation

round(val)

`payload.range | round`

Returns `val` rounded to the nearest integer.

trunc(val)

`payload.range | trunc`

Returns the integer part of `val`.

sqrt(val)

`payload.range | sqrt`

Returns `√val`.

sign(val)

`payload.range | sign`

Returns 1 if `val` is positive, -1 if `val` is negative or 0 if `val` equals 0.

ceil(val)

`payload.price | ceil`

Returns the nearest integer greater than `val`

floor(val)

`payload.price | floor`

Returns the nearest integer less than `val`

abs(val)

`payload.temperature_change | abs`

Returns the absolute value for a Number or 0 if the number is `null`

exp(val)

`payload.difference | exp`

Returns `ℯval`

log(val)

`payload.difference | log`

Returns the natural logarithm of `val`, for example `ln(val)`

random(val)

`payload.range | random`

Returns `val` multiplied by a floating-point, pseudo-random number between 0 (inclusive) and 1 (exclusive).