Aerospike Go Client

CDT (Complex Data Type) Context allows you to navigate deep into nested Maps and Lists. Instead of retrieving a whole large object to modify a small part, you provide a slice of *as.CDTContext to target a specific path.

Context Navigation Types

• as.CtxMapKey(value): Navigate to a map value by its key. Note that keys must be wrapped in an as.Value type (e.g., as.StringValue("key")).
• as.CtxListIndex(index): Navigate to a list item by its integer index.
• as.CtxMapRank(rank): Navigate to a map value by its rank.
• as.CtxListRank(rank): Navigate to a list item by its rank.

By chaining these contexts, you can reach deeply nested fields like user.profile.address.city or a specific item in a 2D array.

// Example: Accessing a nested field 'zip' inside 'address' inside 'profile' inside 'user123'
ctx := []*as.CDTContext{
    as.CtxMapKey(as.StringValue("user123")),
    as.CtxMapKey(as.StringValue("profile")),
    as.CtxMapKey(as.StringValue("address")),
}

record, err := client.Operate(nil, key,
    as.MapGetByKeyOp("data", "zip", as.MapReturnType.VALUE, ctx...),
)

When using Operate(), the way results are returned in record.Bins depends on how many operations target the same bin:

1. Single operation on a bin: The result is returned directly as its underlying type (e.g., string, int, []any). It is not wrapped in OpResults.
2. Multiple operations on the same bin: The results are wrapped in an as.OpResults type, which is a slice ([]interface{}). The elements in the slice correspond to the operations in the order they were provided.
3. Operations on different bins: Each bin returns its value directly, regardless of how many total operations were performed in the call.

Note: If a single operation returns a slice (like MapGetByValueOp with KEY return type), it is stored directly as []any, not wrapped in OpResults.

// Example: Multiple Operations on the SAME bin (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 on a bin (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
count := record.Bins["orders"].(int)    // Direct value

In ordered maps, you can retrieve items based on their sorted position (rank) relative to their values.

Understanding Ranks:

• Rank 0: The smallest/lowest value.
• Rank 1: The second smallest value.
• Rank -1: The largest/highest value (most common for leaderboards).
• Rank -2: The second largest value.

Key Rank Operations

• MapGetByRankOp: Retrieves a single item at a specific rank.
• MapGetByRankRangeOp: Retrieves items within a rank range.
• MapGetByRankRangeCountOp: A more intuitive way to get the "Top N" items. You specify a starting rank and a count. For example, starting at rank -1 with a count of 10 retrieves the 10 highest values.

// Get item with highest value (rank -1)
record, err := client.Operate(nil, key,
    as.MapGetByRankOp("scores", -1, as.MapReturnType.KEY_VALUE),
)

// Get top 10 players using count (starting from highest rank -1)
record, err := client.Operate(nil, key,
    as.MapGetByRankRangeCountOp("leaderboard", -1, 10, as.MapReturnType.KEY_VALUE),
)
results := record.Bins["leaderboard"].(as.OpResults)
topPlayers := results[0].([]as.MapPair)

A Record is represented as a struct in the Go client. When you perform a Get operation, you receive a Record containing:

• Bins: A BinMap (map[string]any) containing the data.
• Key: The associated Key pointer.
• Node: The database node that provided the record.
• Expiration: Time-to-live in seconds.
• Generation: The number of times the record has been updated.

To update a record, you typically retrieve it using Get, modify the values within the Bins map, and then write it back using Put.

// define a client to connect to
client, err := NewClient("127.0.0.1", 3000)
panicOnError(err)

key, err := NewKey("test", "demo", "key")
panicOnError(err)

// define some bins
bins := BinMap{
  "bin1": 42,
  "bin2": "An elephant is a mouse with an operating system",
  "bin3": []any{"Go", 2009},
}

// write the bins
writePolicy := NewWritePolicy(0, 0)
err = client.Put(writePolicy, key, bins)
panicOnError(err)

// read it back!
readPolicy := NewPolicy()
rec, err := client.Get(readPolicy, key)
panicOnError(err)

// change data
v := rec.Bins["bin1"].(int)
v += 1
rec.Bins["bin1"] = v

// update
err = client.Put(nil, key, rec.Bins)