Bin operations

You can use the Rust client API to perform separate operations on multiple bins in a record in a single command. This feature allows the application to modify and read bins of a record in a single transaction (that is, perform an atomic modification that returns the result).

Some record operations include:

Operation	Description	Conditions
write	Write a value to a bin.
get	Read the value of a bin.
get_header	Read only the metadata (generation and time-to-live) of the record.
add	Add an integer to the existing value of the bin.	The existing value must be integer.
append	Append a string to the existing value of the bin.	The existing value must be string.
prepend	Prepend a string to the existing value of the bin.	The existing value must be string.
touch	Rewrite the same record.	Generation and time-to-live are updated.

Note

Operations are performed in user-defined order.

Both Client::put and Client::operate take a WritePolicy reference. There is no separate OperatePolicy type. Use WritePolicy::default() (or a configured WritePolicy) for atomic bin operations.

Operation specification

To specify operations on different bins in the same transaction, create the bins with the values to apply:

let policy = WritePolicy::default();
let key = as_key!("test", "demoset", "opkey");
let bin1 = as_bin!("optintbin", 7);
let bin2 = as_bin!("optstringbin", "string value");
match client.put(&policy, &key, &[bin1, bin2]).await {
    Ok(()) => println!("Record written"),
    Err(err) => println!("Error writing record: {}", err),
};

let bin3 = as_bin!(bin1.name, 4);
let bin4 = as_bin!(bin2.name, "new string");

📖 API reference: Client::put

Create the appropriate operations using the bins and supply them to the operate() function:

let ops = vec![
    operations::add(&bin3),
    operations::put(&bin4),
    operations::get(),
];
match client.operate(&policy, &key, &ops).await {
    Ok(record) => {
        if let Some(val) = record.bins.get(bin1.name.as_str()) {
            println!("optintbin: {}", val);
        } else {
            println!("bin {} not returned", bin1.name);
        }
    }
    Err(err) => println!("Error operating on record: {}", err),
}

📖 API reference: Client::operate | operations::add | operations::put | operations::get

Note

record.bins is a HashMap of bin names to values. Use HashMap::get (returns Option) when reading individual bins after an operate call. To print every bin returned by operations::get(), iterate directly: for (name, value) in &record.bins { ... }.

String append

To atomically append text to a string bin without reading the record first, pass operations::append to operate with a WritePolicy:

let key = as_key!("test", "posts", "post:1");
let ops = vec![operations::append(&as_bin!("body", " (edited)"))];
match client.operate(&WritePolicy::default(), &key, &ops).await {
    Ok(_record) => println!("Appended to body bin"),
    Err(err) => println!("Error operating on record: {}", err),
}

📖 API reference: operations::append | Client::operate | WritePolicy::default