Map

Overview

A Map is a collection of key-value pairs, where each key is unique within the map. Aerospike Maps have three subtypes that differ in how elements are ordered and what internal indexes they maintain. All subtypes share the same API and support key, index, value, and rank based operations. They can be converted between each other with the set_type() operation.

• Unordered: elements have no guaranteed order. No internal indexes.
• K-ordered: elements are stored in key order. Has a key offset index that maps each key position to a byte offset within the packed map.
• KV-ordered: elements are stored in key order (same as K-ordered). Has both a key offset index and a value order index that maps rank to element.

By default, internal indexes are rebuilt temporarily for each operation. Setting PERSIST_INDEX in the map policy stores the indexes on disk inside the map particle, so subsequent operations load them directly instead of rebuilding them.

Caution

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

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

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	3 or -2	4 or -1	2 or -3

Element ordering

In an ordered map, elements of mixed data types are first ordered by type, then by value. All three subtypes support key, index, value, and rank based operations. The difference is what ordering and indexes each subtype maintains internally.

Unordered

Elements have no guaranteed order. The map has no internal indexes, so all lookups require scanning the elements. This subtype has the lowest storage overhead.

K-ordered

Elements are stored sorted by key. The key offset index provides direct access to elements by key or by index position. Rank and value operations are supported but require the value order to be computed on each access.

KV-ordered

Elements are stored in key order (same as K-ordered). A separate value order index maps rank to element, so rank-based and value-based operations can use this index directly. Together the two indexes support key, index, rank, and value operations.

Note

Only ordered maps (K-ordered or KV-ordered) can be reliably compared for equality. Unordered maps have no canonical byte ordering, so two unordered maps with the same logical content can have different wire representations. Comparisons involving unordered maps, whether through an expression eq operator or through *_by_value and *_by_value_list operations, may return false even when the maps contain the same elements.

Map API

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

You can click on each of the following commands 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()

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

Development guidelines and tips

• Multiple operations on List, Map and scalar data types can be combined into a single-record command.
• 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 subtype. The subtypes differ in which internal indexes they maintain, which affects the performance of different operations. See Map performance for details.
• For maps that are accessed frequently, consider using PERSIST_INDEX to store the internal indexes on disk rather than rebuilding them on each access.

Performance

The choice of map subtype and whether indexes are persisted are the main factors in operation performance. For the operational complexity analysis of each combination, refer to the Map performance documentation.

Known limitations

• Maps are bound by the maximum record size. The maximum record size is limited by the max-record-size configuration parameter.
• Map commands are not supported by Lua UDFs.

Language-specific client commands

Language-specific map operation examples:

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