Collection data types

Overview

Aerospike collection data types contain an arbitrary number of scalar data type elements, as well as nesting other CDT (List, Map) elements.

Collection data types

Aerospike records have one or more bins. Each bin holds a distinct scalar data type, such as integer or string, a collection data type (CDT), such as List or Map, an Aerospike probabilistic data type such as HyperLogLog, or a geospatial GeoJSON data type.

Collection data types (CDTs) are flexible, schema-free containers, which can hold scalar data or nest other collections within them. The elements in a CDT can be of mixed types.

CDTs are a superset of JSON, supporting more data types as elements of the collection, such as integers for Map keys, and binary data as List values.

{ 'scores': { 'ACE': [ 34500,
                       { 'awards': {'🏆': 1},
                         'dt': '1979-04-01 09:46:28',
                         'ts': 291807988156}],
              'CFO': [ 17400,
                       { 'awards': {'🦄': 1},
                         'dt': '2017-11-19 15:22:38',
                         'ts': 1511104958197}],
              'CPU': [9800, {'dt': '2017-12-05 01:01:11', 'ts': 1512435671573}],
              'EIR': [ 18400,
                       {'dt': '2018-03-18 18:44:12', 'ts': 1521398652483}],
              'ETC': [9200, {'dt': '2018-05-01 13:47:26', 'ts': 1525182446891}],
              'SOS': [ 24700,
                       {'dt': '2018-01-05 01:01:11', 'ts': 1515114071923}]},
  'valid': {1: 'a', 2: 'b', 3: 'c', 26: 'z'}}

Collections come with extensive APIs for performing multiple operations in a single operate() command. The command executes under a record lock with atomicity and isolation - either all operations succeed or the command fails and none of the changes are persisted. The NO_FAIL write flag on an individual operation treats that operation’s failure as success, allowing the command to continue.

Collection elements can be reached through either of the two surfaces described in Operations and expressions: an operation acts in place on a bin, while an expression evaluates to a value you can filter on, return from a projection, or store.

Two things about that split are particular to collections:

• Both surfaces take an optional context path, so either one can target an element nested inside another List or Map rather than the top level of the bin.
• Each has its own builders. Operations use ListOperation and MapOperation; expressions use ListExp and MapExp, documented in List expressions and Map expressions.

Nesting depth limit

Starting with Aerospike Database 8.2.0, CDT nesting depth is limited to 64 levels. The top-level List or Map value stored in a bin counts as depth 1, and each List or Map nested one level deeper adds 1 to the depth. A List or Map value deeper than 64 levels is rejected when it is sent to the server, whether as a whole-bin write, a CDT operation value, or an expression literal. Keep the whole bin within 64 levels, counting from its top level, including values you place inside an existing List or Map.

selectByPath and modifyByPath refuse a context deeper than 64 levels. Keep other CDT context paths within the limit too, including ones that create missing levels with MAP_KEY_CREATE or LIST_INDEX_CREATE.

Path expressions

Starting with Aerospike Database 8.1.1, path expressions add two CDT operations for multi-element selection and modification within nested collections:

• selectByPath reads elements from a nested Map or List structure, applying filter expressions at each level to return only matching elements.
• modifyByPath updates or removes elements in place using the same traversal and filtering model.

Both operations accept a chain of context entries that describe how to traverse the nested structure. Path expression contexts include allChildren() and allChildrenWithFilter(exp) for matching and filtering, as well as the traditional mapKey(), listIndex(), and other selectors.

Aerospike Database 8.1.2 adds mapKeysIn(keys...) for native IN-list key selection and andFilter(exp) for combining filters at the same context level, improving both API clarity and performance for common query patterns.

For a tutorial on working with nested collections using CDT operations, expression composition, and path expressions together, see Working with nested collection data types.