List

Overview

Aerospike Lists have two subtypes that differ in how elements are ordered and what internal indexes they maintain. Both subtypes share the same API and support index, value, and rank based operations. They can be converted between each other with the set_order() operation.

Unordered: elements maintain insertion order (when appended). No internal indexes.
Ordered: elements are stored in value order. Has an offset index that maps each element position to a byte offset within the packed list. Because elements are in value order, index and rank are equivalent.

By default, the offset index is rebuilt temporarily for each operation. Setting persistIndex in the list policy stores the offset index on disk inside the list particle, so subsequent operations load it directly instead of rebuilding it.

A list can store scalar data types or contain nested list or Map elements. List operations manipulate lists directly on the Aerospike server.

List terminology

For the following list,

[ 1, 4, 7, 3, 9, 26, 11 ]

The index is the (0 origin) position of an element in the list.
The value at index 2 is 7. The value at index -2 is 26.
The rank is the value order of the elements in the list. The lowest value element has rank 0.
The value of the element with rank 2 is 4. The value of the element with rank -2 is 11.

	1	4	7	3	9	26	11
index	0 or -7	1 or -6	2 or -5	3 or -4	4 or -3	5 or -2	6 or -1
value	1	4	7	3	9	26	11
rank	0 or -7	2 or -5	3 or -4	1 or -6	4 or -3	6 or -1	5 or -2

Element ordering

Specify element access through index, rank (value ordering) or element value:

[ 1, 4, 7, 3, 9, 26, 11 ] # Unordered
[ 1, 3, 4, 7, 9, 11, 26 ] # Ordered

Once created, a list’s order doesn’t change, unless the set_order() API call is used.

Unordered lists

An Unordered List maintains insertion order, as long as new elements are appended.
In an Unordered List, rank-based operations compute the value order on each access.

Ordered lists

An Ordered List maintains value order, and sorts itself every time new elements are added.
Because elements are in value order, index and rank are equivalent in an ordered list.
In an Ordered List, elements of mixed data types are first ordered by type, then by value.
By default a new list is Unordered, unless a create policy instructs otherwise.

List API

Using the Aerospike client API, an application can retrieve the full list, or operate on individual elements. Atomic list commands work on top level elements, and on nested elements with an additional collection data type nested context. For a tutorial on working with lists in nested structures, see Working with nested collection data types.

Access the following commands to review detailed descriptions.

See List operations for write flags, return types, and context.

Development guidelines and tips

Multiple commands on List, Map and scalar data types can be combined into a single-record command.
A list bin is created when a list value is written to a bin, or by using list append, insert, set or increment commands.
Insertion at either end of the list requires no element walk and is generally fast.
If insertions and deletions are mostly at the end of the list, commands are, on average, fast.
For ordered lists with a persisted index, an offset index is stored in the list particle for O(1) random-access reads. Without a persisted index, the offset index is rebuilt on each access.
If the namespace saves to disk storage, disk writes may create a bottleneck. For example, if there are not enough nodes or devices or if key use is not evenly distributed. This is especially true for list bins nearing maximum record size.

Performance

For the operational complexity analysis of list commands see List performance.

Known limitations

Lists are bound by the maximum record size. For data on SSD, the maximum record size is limited by the max-record-size configuration parameter.
List commands are not supported by Lua UDFs.

Language-specific client commands

Language-specific list operation examples: