Working with Arrays

AMPS supports filters that operate on arrays in messages. There are two simple principles behind how AMPS treats arrays:

1. Binary operators that yield true or false (for example, =, <, LIKE) are array aware, as is the IN operator. These operators work on arrays as a whole, and evaluate every element in the array.

2. Arithmetic operators, functions, user-defined functions and other scalar operators, are not array aware, and use the first element in the array.

With these simple principles, you can predict how AMPS will evaluate an expression that uses an array. For any operator, an empty array evaluates to NULL.

Let's look at some examples. For the purposes of this section, we will consider the following JSON document:

{
    "data"  : [1, 2, 3, "zebra", 5],
    "other" : [14, 34, 23, 5]
}

While these arrays are presented using JSON format for simplicity, the same principles apply to arrays in other message formats.

Here are some examples of ways to use an array in an AMPS filter:

Determining if any element in an array meets a criteria

To determine this, you provide the identifier for the array, and use a comparison operator.

Filter	Evaluates as
/data = 1	TRUE, /data contains 1
/data = 'zebra'	TRUE, /data contains 'zebra'
/data != 'zebra'	TRUE, /data contains an element that is not 'zebra'
/data = 42	FALSE, /data does not contain 42
/data LIKE 'z'	TRUE, a member of /data matches 'z'
/other > 30	TRUE, a member of /other is > 30
/other > 50	FALSE, no member of /other is > 50

Determine whether a specific value is at a specific position

To determine this, use the subscript operator [] on the XPath identifier to specify the position, and use the equality operator to check the value at that position.

Filter	Evaluates as
/data[0] = 1	TRUE, first element of /data is 1
/data[3] = "zebra"	TRUE, fourth element of /data is 'zebra'
/data[1] != 1	TRUE, second element of /data is not 1
/other[1] LIKE '4'	TRUE, second element of /other matches '4'

Determine whether any value in one array is present in another array

Filter	Evaluates as
/data = /other	TRUE, a value in /data equals a value in /other
/data != /other	TRUE, a value in /data does not equal a value in /other

Determine whether an array contains one of a set of values

Filter	Evaluates as
3 IN (/data)	TRUE, 3 is a member of /data
/data IN (1, 2, 3)	TRUE, a member of /data is in (1, 2, 3)
/data IN ("zebra", "antelope", "lion")	TRUE, a member of /data is in ("zebra", "antelope", "lion")

These patterns and principles hold regardless of the original representation of the array in a document.

When creating an expression that uses a field in a compound value, keep in mind that AMPS represents compound values as described in the section on Compound Data Types in AMPS.