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 0let 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 elementclient.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
- Map operations: Change, read, and remove map entries on the server.
- Bin operations: Combine several operations in one
operate()call.