Map

Overview

Aerospike Maps are an abstract data type with three concrete subtypes - Key Ordered Map (K-ordered), Key-Value Ordered Map (KV-ordered), and Unordered Map. All types of Map share the same API and can cast between each other with the set_type() operation.

A Map can store scalar data types or contain nested List or Map elements. Map operations are optimal for manipulating maps directly on the Aerospike database.

Elements in a Map are stored based on the ordering type. Unordered maps do not have a guaranteed order, while K-ordered maps are always stored in key order. When a K-ordered Map is in an in-memory namespace, it will also have a key offset index for faster access.

KV-ordered maps are also stored in key order. When a KV-ordered Map is in an in-memory namespace, it will also have a full index - a key offset index, and a rank offset index.

caution

Starting in Database 7.1, map keys are restricted to the following scalar data types -- integer, string, and blob.

Map terminology

• The key is the identifier of the element in the map.
• The value is the value of the element identified by a specific map key.
• The index is the key order of the element in the map.
• The rank is the value order of the element in the map. If there are multiple elements with the same value, their rank is based on their index order.

{a:1, b:2, c:30, y:30, z:26}

The elements of the map have

	a:1	b:2	c:30	y:30	z:26
key	a	b	c	y	z
value	1	2	30	30	26
index	0 or -5	1 or -4	2 or -3	3 or -2	4 or -1
rank	0 or -5	1 or -4	4 or -2	5 or -1	2 or -3

Element ordering

In an ordered Map, elements of mixed data types are first ordered by type, then by value. Irrespective of the order type of the map, key, rank, index and value based operations are supported, with a variation in their runtime performance.

Map API

Using the Aerospike client API, an application can retrieve the full map, or operate on individual elements. Atomic map operations work on top level elements, and on nested elements with an additional collection data type (CDT) nested context.

You can click on each of the following operations to see a detailed description of it.

• set_type()
• put(), put_items()
• increment(), decrement()
• clear()
• size()
• get_by_key(), get_by_index(), get_by_rank()
• get_by_key_interval(), get_by_index_range()
• get_by_value_interval(), get_by_rank_range(), get_all_by_value()
• get_by_key_rel_index_range(), get_by_value_rel_rank_range()
• get_all_by_key_list(), get_all_by_value_list()
• remove_by_key(), remove_by_index(), remove_by_rank()
• remove_by_key_interval(), remove_by_index_range()
• remove_by_value_interval(), remove_by_rank_range(), remove_all_by_value()
• remove_by_key_rel_index_range(), remove_by_value_rel_rank_range()
• remove_all_by_key_list(), remove_all_by_value_list()

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.

Map operation flag

get_* or remove_* operations have an opFlags parameter to control what they return back and to modify their search criteria.

OpFlag	Description
INVERTED	Inverts the search criteria provided in the op parameters.

• Remove the 10 map elements with the largest key values: remove_by_index_range(-10, 10, NONE)
• Remove all but the 10 map elements with the largest key values: remove_by_index_range(-10, 10, INVERTED)

note

Since Aerospike version 3.16.0

Map return types

get_* and remove_* operations have a returnType parameter to control what they return back.

Return Type	Description
None	No results, useful for faster remove operations due to not constructing a reply.
Index	Key order: 0 = smallest key, (N-1) = largest key, where N is the number of key entries in map.
RevIndex	Reverse key order: 0 = largest key.
Rank	Value order: 0 = smallest value, (N-1) = largest value.
RevRank	Reverse value order: 0 = largest value.
Count	Return number of items matching criteria.
Key	Key for single item operations and list of keys for multi-ops.
Value	Value for single item operations, list of values for multi-ops.
KeyValue	Key Value pairs. The exact format is client dependent.

• Keep only the top 10 key elements, return count: remove_by_index_range(-10, 10, INVERTED | COUNT)

note

Since Aerospike version 3.16.0, returnType folded into opFlags.

Development guidelines and tips

• Multiple operations on List, Map and scalar data types can be combined into a single-record transaction.
• A map bin is created when a map value is written to a bin, or by using map put, put_items, or increment operations.
• Use set_type() to convert an unordered map into a K-ordered or KV-ordered map. Alternatively, use a map policy with put or put_items and the map_type in the policy will be used to create the map bin if it did not exist.
• All map operations work for any map_type. The only difference is performance as detailed in the performance table below.
• In general, when namespace is data-on-SSD, K-ordered gives the best performance for all map operations at the cost of 4 extra bytes on disk.

Performance

For the operational complexity analysis of map operations, refer to the Map Performance documentation.

Known limitations

• Maps are bound by the maximum record size. For data-on-SSD, the maximum record size is limited by the max-record-size configuration parameter.
• Map 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