Map operations

What are CDT Operations?

CDT (Collection data type) operations are server-side operations that allow you to manipulate maps and lists stored in Aerospike bins without transferring entire data structures over the network. Instead of reading a map, modifying it in your application, and writing it back, you can perform operations directly on the server.

Benefits:

Reduced network traffic
Atomic operations
Better performance
Simplified code

Basic Concepts

Maps: Key-value pairs, similar to Go’s map[any]any

Keys can be strings, integers, or bytes
Values can be any supported type
Can be ordered or unordered

Lists: Ordered collections, similar to Go’s []any

Indexed by position (0-based)
Can be ordered or unordered
Support negative indexing (-1 = last item)

Nested Structures: Maps and lists can contain other maps and lists, creating complex nested data structures.

Using Operate() with CDT Operations

All CDT operations are performed using the Operate() method:

import as "github.com/aerospike/aerospike-client-go/v8"

// Perform CDT operations
record, err := client.Operate(policy, key,
    as.MapGetByKeyOp("binName", "key", as.MapReturnType.VALUE),
    // ... more operations
)

if err != nil {
    log.Fatal(err)
}

// Results are in OpResults (a slice)
results := record.Bins["binName"].(as.OpResults)
value := results[0]  // First operation result

Understanding OpResults

When are OpResults returned?

OpResults is a slice type ([]interface{}) that wraps results when you perform multiple operations on the same bin. The behavior depends on how many operations target the same bin:

Single operation on a bin: Returns the value directly (string, int, []any, etc.)
Multiple operations on the same bin: Returns OpResults, a slice containing each operation’s result in order

Example: multiple operations (returns OpResults)

record, err := client.Operate(nil, key,
    as.MapGetByKeyOp("profile", "name", as.MapReturnType.VALUE),
    as.MapGetByKeyOp("profile", "age", as.MapReturnType.VALUE),
)

results := record.Bins["profile"].(as.OpResults)  // Wrapped in OpResults
name := results[0].(string)  // First operation
age := results[1].(int)    // Second operation

Example: single operation (returns value directly)

record, err := client.Operate(nil, key,
    as.MapGetByKeyOp("profile", "name", as.MapReturnType.VALUE),
)

name := record.Bins["profile"].(string)  // Direct value, NOT OpResults

Example: operations on different bins (each returns directly)

record, err := client.Operate(nil, key,
    as.MapGetByKeyOp("profile", "name", as.MapReturnType.VALUE),
    as.MapGetByKeyOp("orders", "count", as.MapReturnType.VALUE),
)

name := record.Bins["profile"].(string)  // Direct value (different bin)
count := record.Bins["orders"].(int)    // Direct value (different bin)

Policies overview

MapPolicy: Controls how maps are created and written.

DefaultMapPolicy() - Unordered map, UPDATE mode
NewMapPolicy(order, writeMode) - Custom order and write mode
Order types: UNORDERED, KEY_ORDERED, KEY_VALUE_ORDERED
Write modes: UPDATE, CREATE_ONLY, UPDATE_ONLY

ListPolicy: Controls how lists are created and written.

DefaultListPolicy() - Unordered list
NewListPolicy(order, flags) - Custom order and flags
Order types: ListOrderUnordered, ListOrderOrdered

Conclusion

CDT operations provide powerful, efficient ways to work with maps and lists in Aerospike. By performing operations server-side, you reduce network traffic and improve performance.

Key takeaways:

Use MapGetByKeyOp for the most common map retrieval operations.
Leverage nested operations with CDT Context for complex data structures.
Choose appropriate return types to get exactly the data you need.
Batch operations in a single Operate() call for better performance.
Always handle errors and check for nil results.