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.

There are two complementary ways to work with collection elements:

CDT operations (ListOperation, MapOperation) act in-place on the record within an operate() call. They read or modify a single element and accept an optional context to target nested elements.
CDT expressions (ListExp, MapExp) each evaluate to an Aerospike data type and can be composed with other expressions. They are used inside expressions for record filtering (where the outermost expression must evaluate to boolean true or false), computed reads/writes, and secondary index definitions.

Expressions also support operations on blobs and HyperLogLogs through read-expressions and write-expressions.

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.