Order and compare collection elements

Type order (ascending)

• Unordered maps do not have a guaranteed element order. Only ordered maps (K-ordered or KV-ordered) can be reliably compared for equality in expressions and *_by_value / *_by_value_list operations.
• If an application relies on the informal ordering of an unordered map, it could fail if that ordering changes.
• Ordered maps have performance advantages. See Map Performance.

Elements with different types are ordered based on their type.

1. NIL
2. BOOLEAN
3. INTEGER
4. STRING
5. LIST
6. MAP
7. BYTES
8. DOUBLE
9. GEOJSON
10. INF

NIL

The lowest valued type. NIL is a singleton. NIL is used as a lower bound in list and map interval and range operations.

NIL can be stored as a list element or a map value, and reads back successfully. Setting a top-level bin to NIL deletes the bin (and if it is the last bin on the record, the record is removed). NIL cannot be used as a map key.

BOOLEAN

False < True

INTEGER

Ordered by integer value.

STRING

Order by each byte in the string.

"aa" < "b"

Strings are assumed to have UTF-8 encoding.

LIST

Order by:

1. Each element starting from index 0 [1, 2] < [1, 3]
2. Element count [1, 2] < [1, 2, 1]

MAP

Order by:

1. Element count
2. Each key in order stored
3. Map values if the corresponding map keys are equal

BYTES

Order by each byte in the string.

DOUBLE

Ordered by float value.

INF

The highest valued type. INF is a singleton. INF is used as an upper bound in list and map interval and range operations. Not a storage type. Storing INF in a list or map has undefined behavior.

Comparison

Wildcard

The singleton WILDCARD(*) type can be used as a value parameter in list and map *_by_value and *_by_value_list operations. When used as an element in a list, it matches any remaining elements from that position onward. Not a storage type. Storing WILDCARD in a list or map has undefined behavior.

Bin: [ [1, 1], [1, 2], [1, 3], [2, 1], [2, 2], [2, 3] ]

list_get_all_by_value([1, *]) -> [ [1, 1], [1, 2], [1, 3] ]

Intervals

Intervals are inclusive-exclusive by default: start <= elements < end

Bin: [ [1, 1], [1, 2], [2, 1], [2, 2], [3, 1] ]

list_get_by_value_interval(start=[1, NIL], end=[2, NIL]) -> [ [1, 1], [1, 2] ]

Using INF, we can get an inclusive-inclusive interval when using 2nd level lists.

list_get_by_value_interval(start=[1, NIL], end=[2, INF]) -> [ [1, 1], [1, 2], [2, 1], [2, 2] ]