are an abstract data type with two concrete subtypes - Unordered List
and Ordered List. Both types of List share the same API and can be cast between
each other with the
A List can store scalar data types or contain nested List or Map elements. List operations are optimal for manipulating lists directly on the Aerospike database.
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.
Element access can be specified 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
- An Unordered List maintains insertion order, as long as new elements are appended.
- In an Unordered List, getting elements by rank will obey the same (just-in-time) ordering.
- An Ordered List maintains rank order, and sorts itself every time new elements are added.
- 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.
Using the Aerospike client API, an application can retrieve the full list, or operate on individual elements. Atomic list operations work on top level elements, and on nested elements with an additional collection data type (CDT) nested context.
Access the following operations to review detailed descriptions.
Operations on nested list/map elements were added in Aerospike Database version 4.6. Relative rank operations were added in Aerospike version 4.3.
These operations are superseded by the
get_by_*(). The operations are deprecated and will be removed in a future release.
Development Guidelines and Tips
- Multiple operations on List, Map and scalar data types can be combined into a single-record transaction.
- A list bin is created when a list value is written to a bin, or by using list
- 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, operations are, on–average, fast.
- For data-in-memory, internal structures are optimized for random-access reads with an offset index.
- 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.
For the operational complexity analysis of list operations see List performance.
- Lists are bound by the maximum record size. For data on SSD, the maximum record size is limited by the
- List operations are not supported by Lua UDFs.
Language Specific Client Operations
Language-specific list operation examples: