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()
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
orincrement
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: