Skip to content

List operations

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

A list bin stores an ordered collection of values. The server’s list collection data type (CDT) operations add, read, and remove individual list elements in a single round trip, without the client reading the whole bin first.

This matters because Client::put always replaces the full bin value. Calling put() a second time with a new Vec<Value> does not append to the existing list. It overwrites it. To add items to a list bin that may already exist, without a read-modify-write round trip, use the aerospike::operations::lists builders with Client::operate().

Setup

use aerospike::operations::lists;
use aerospike::{as_key, Client, ClientPolicy, ListPolicy, ListReturnType, Value, WritePolicy};
let client = Client::new(&ClientPolicy::default(), &"127.0.0.1:3000").await?;
let key = as_key!("test", "carts", "cart:1");
let policy = ListPolicy::default();

📖 API reference: Client::new | operations::lists | ListPolicy

Write a list bin

To write a list as the whole value of a bin, build it with as_list! (or Value::List(Vec<Value>)) and pass it to put(). Integers in the macro are stored as integers. as_list! expands to as_val!, so import as_val too:

use aerospike::{as_bin, as_list, as_val};
let key = as_key!("test", "feeds", "feed:1");
let bin = as_bin!("events", as_list!(1, 2, 3, 4, 5, 6, 7, 8));
client.put(&WritePolicy::default(), &key, &[bin]).await?;

📖 API reference: as_list! | Value::List

Append to a list bin

lists::append appends a single value to a list bin and creates the bin (and an empty list) if it doesn’t exist yet. No read is required first. Call it again later and it appends again, rather than overwriting:

let ops = vec![lists::append(&policy, "items", Value::from("apple"))];
client.operate(&WritePolicy::default(), &key, &ops).await?;
// Later, in a separate call. This appends "banana", it does not replace "apple".
let ops = vec![lists::append(&policy, "items", Value::from("banana"))];
client.operate(&WritePolicy::default(), &key, &ops).await?;
// items is now ["apple", "banana"]

📖 API reference: operations::lists::append | Client::operate

To append more than one value in a single call, use append_items:

let ops = vec![lists::append_items(
&policy,
"items",
vec![Value::from("cherry"), Value::from("date")],
)];
client.operate(&WritePolicy::default(), &key, &ops).await?;

📖 API reference: operations::lists::append_items

Read the list size

lists::size returns the number of elements in a list bin. Combine it with an append in the same operate() call to append and confirm the new length in one round trip:

let ops = vec![
lists::append(&policy, "items", Value::from("apple")),
lists::size("items"),
];
let record = client.operate(&WritePolicy::default(), &key, &ops).await?;
// record.results holds one answer per operation, in order; the size is the second.
let results = record.results.unwrap();
println!("list size: {:?}", results[1]);

📖 API reference: operations::lists::size | Record::results

Read elements back

lists::get reads the element at an index. lists::get_range(bin, index, count) reads count elements that start at index, without removing them. lists::get_range_from(bin, index) reads from index to the end of the list. The server selects the elements, so the whole list never travels to your program:

let ops = vec![lists::get_range("items", 0, 2)]; // two elements, starting at index 0
let record = client.operate(&WritePolicy::default(), &key, &ops).await?;
println!("{:?}", record.operation_result(0));

📖 API reference: operations::lists::get | operations::lists::get_range | operations::lists::get_range_from

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. These two calls return the same elements:

let ops = vec![lists::get_range("items", -3, 3)];
// or: let ops = vec![lists::get_range_from("items", -3)];
let record = client.operate(&WritePolicy::default(), &key, &ops).await?;

A list read returns a Value::List. To read its elements, match on it. record.operation_result(0) returns the result of the first operation in the call:

if let Some(Value::List(elements)) = record.operation_result(0) {
for element in elements {
println!("{element}");
}
}

📖 API reference: Record::operation_result | Value::List

Remove elements

lists::pop removes and returns the element at an index. lists::remove_by_value removes every occurrence of a value and takes a ListReturnType that selects what the server reports about the removed items:

let ops = vec![lists::pop("items", 0)]; // remove and return the first element
client.operate(&WritePolicy::default(), &key, &ops).await?;
// Remove every "banana"; COUNT asks the server to return how many were removed.
let ops = vec![lists::remove_by_value("items", Value::from("banana"), ListReturnType::COUNT)];
client.operate(&WritePolicy::default(), &key, &ops).await?;

📖 API reference: operations::lists::pop | operations::lists::remove_by_value | ListReturnType

Keep only the last elements of a list

lists::trim(bin, 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:

let key = as_key!("test", "feeds", "feed:1");
let ops = vec![
lists::append(&policy, "events", Value::from(9)),
lists::trim("events", -5, 5), // keep the last five elements
];
client.operate(&WritePolicy::default(), &key, &ops).await?;

📖 API reference: operations::lists::trim

To remove a range instead of keeping one, use lists::remove_range(bin, index, count), or lists::remove_range_from(bin, index) to remove from index to the end of the list. Both return the number of elements removed.

For nested-path navigation with CdtContext, see the operations::maps API reference.

Next steps