List

Aerospike Lists 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 set_order() operation.

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.

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.

Element Ordering

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 is used.

Unordered Lists

• 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.

Ordered Lists

• 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.

List API

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.

• set_order()
• sort(), clear()
• append(), append_items()
• insert(), insert_items()
• set()
• increment()
• size()
• get_by_index(), get_by_index_range()
• get_by_rank(), get_by_rank_range()
• get_all_by_value(), get_all_by_value_list(), get_by_value_interval(), get_by_value_rel_rank_range()
• remove_by_index(), remove_by_index_range()
• remove_by_rank(), remove_by_rank_range()
• remove_all_by_value(), remove_all_by_value_list(), remove_by_value_interval(), remove_by_value_rel_rank_range()

note

Operations on nested list/map elements were added in Aerospike Database version 4.6. Relative rank operations were added in Aerospike version 4.3.

Superseded operations

These operations are superseded by the remove_by_*() and get_by_*(). The operations are deprecated and will be removed in a future release.

• get(), get_range(), get_range_from()
• pop(), pop_range()
• remove(), remove_range()
• trim()

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 append, insert, set or increment operations.
• 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.

Performance

For the operational complexity analysis of list operations 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 write-block-size configuration parameter.
• List operations are not supported by Lua UDFs.

Language Specific Client Operations

Language-specific list operation examples:

• Java
• C
• C#
• Go
• Python
• Node.js
• Rust
• Ruby