List operations

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Aerospike’s list collection data type (CDT) operations let the server add, read, and remove individual list elements in a single round trip, while the client reads only the operation results. A list bin stores an ordered collection of values.

AerospikeClient.Put always replaces the full bin value. To change a list bin that already exists, use the ListOperation builders with AerospikeClient.Operate(). Each builder returns an Operation, and the server runs the operations in the order you pass them.

Setup

using Aerospike.Client;
using System.Collections;
using System.Collections.Generic;

// Define host configuration
Host config = new Host("127.0.0.1", 3000);
// Establishes a connection to the server
AerospikeClient client = new AerospikeClient(null, config);

// Creates a key with the namespace "sandbox", set "feeds", and user key "feed:1"
Key key = new Key("sandbox", "feeds", "feed:1");

📖 API reference: ListOperation | ListReturnType

Write a list bin

To write a list as the whole value of a bin, pass a List<object> to a Bin:

List<object> events = new List<object> { 1, 2, 3, 4, 5, 6, 7, 8 };
client.Put(null, key, new Bin("events", events));

Append to a list bin

ListOperation.Append(binName, value) appends one value to the end of a list bin. It creates the bin and an empty list if the bin doesn’t exist yet. ListOperation.AppendItems(binName, list) appends every element of a list as a separate element. Both return the new size of the list.

// Append one value
client.Operate(null, key, ListOperation.Append("events", Value.Get(9)));

// Append three values as three separate elements, not one nested list
client.Operate(null, key,
    ListOperation.AppendItems("events", new List<object> { "login", "view", "logout" })
);

Read the list size

ListOperation.Size(binName) returns the number of elements. Combine it with an append in one Operate() call to append and get the new length in a round trip.

When one call runs several operations on the same bin, the Record holds one bin whose value is a list of results, one result for each operation, in order. Read it with record.GetList(binName):

Record record = client.Operate(null, key,
    ListOperation.Append("events", Value.Get(10)),
    ListOperation.Size("events")
);

// The results are in the order of the operations: [new size from Append, size from Size]
IList results = record.GetList("events");
Console.WriteLine("size: {0}", results[1]);

Read elements back

ListOperation.Get(binName, index) reads one element. ListOperation.GetRange(binName, index, count) reads count elements that start at index. ListOperation.GetRange(binName, index) reads from index to the end of the list. The server selects the elements, so the whole list doesn’t travel to your program.

An index can be negative. -1 is the last element, -2 the one before it, and so on. To read the last three elements, start at index -3:

Record record = client.Operate(null, key, ListOperation.GetRange("events", -3, 3));

// A list read returns the elements as an IList
foreach (object element in record.GetList("events"))
{
    Console.WriteLine(element);
}

ListOperation.GetByIndexRange(binName, index, count, returnType) selects the same elements and also takes a ListReturnType. It returns the elements as values with ListReturnType.VALUE, and returns the number of elements selected with ListReturnType.COUNT. Use it when you need something other than the values.

Remove elements

ListOperation.Pop(binName, index) removes the element at an index and returns it. ListOperation.Remove(binName, index) removes it and returns the number of elements removed. ListOperation.RemoveRange(binName, index, count) removes count elements that start at index, and returns the number of elements removed.

// Remove and return the first element
Record record = client.Operate(null, key, ListOperation.Pop("events", 0));
Console.WriteLine("popped: {0}", record.GetValue("events"));

// Remove the next two elements
client.Operate(null, key, ListOperation.RemoveRange("events", 0, 2));

Keep only the last elements of a list

ListOperation.Trim(binName, index, count) keeps the count elements that start at index and removes all the others. With a negative index, it counts from the end of the list, so -5, 5 keeps the last five elements. Trim returns the number of elements it removed.

To cap a list at its five most recent entries, append the new element and trim in the same Operate() call. The server runs the operations in order, so no read comes first:

client.Operate(null, key,
    ListOperation.Append("events", Value.Get(9)),
    ListOperation.Trim("events", -5, 5) // keep the last five elements
);

Read a list from a record

Get() returns a list bin as an IList of object elements. Integers come back as long. Read the list with record.GetList(binName):

Record record = client.Get(null, key);

foreach (object element in record.GetList("events"))
{
    Console.WriteLine(element);
}

For nested-list navigation with a nested CDT context (CTX), see the ListOperation API reference and Context for operations on nested elements.