Skip to content

Single-record commands

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Aerospike provides simple interfaces for reading data from and writing data to an Aerospike cluster. They cover the standard CRUD (create, read, update, delete) use cases.

Every Aerospike client can perform the following single-record commands, no matter which language it’s written in:

CommandDescription
putWrite a record. Performs the equivalent of create, update or replace, depending on the write policy given to the write command.
getRead the record. Specific bins can be selected.
operateExecutes multiple bin operations atomically and in isolation as a single record command.
touchIncrement the generation counter and reset its time-to-live (TTL)
deleteRemove a record from the database. Generates a tombstone when using the durable-delete policy.

Filtering operations

A command can be conditionally applied, based on the result of a record filter expression. If the filter expression evaluates to true, the operation executes.

Code examples of record operations

Every record is identified by a key consisting of a namespace, an optional set, and a user key. In the following examples, the key is ("test", "demo", "user1"), placing the record in the demo set of the test namespace.

A record can also be created without a set by passing null (or None) as the set component. Such records belong to the null set. Records in the null set are fully accessible through single-record commands (put, get, operate, touch, delete) and batch commands, but cannot be targeted by a secondary index query unless the index covers the entire namespace. You can prevent null-set records from being created by setting disallow-null-setname to true.

The following examples demonstrate put (create and merge-style update), get, operate (atomic multi-bin updates in one round trip), touch, and delete on a single record. They use a record with a string bin, an integer bin, and a map bin:

BinTypeValue
namestring"Alice"
visitsinteger1
prefsmap{"theme": "dark", "lang": "en"}

Each section below shows an excerpt. See the Code block at the bottom of the page for the full, continuous program in each language.

Create a record

Use put to write a new record. By default, put creates the record if it does not exist, or merges bins into the existing record if it does. This behavior is controlled by the write policy’s recordExistsAction, which defaults to UPDATE (upsert). Other options include CREATE_ONLY, UPDATE_ONLY, and REPLACE. In the Developer SDKs, the write verb sets the behavior: upsert, insert, update, or replace.

Map<String, Object> prefs = new HashMap<>();
prefs.put("theme", "dark");
prefs.put("lang", "en");


// upsert creates the record or merges bins into it;
// insert, update and replace are the other write verbs.
session.upsert(key)
    .bin("name").setTo("Alice")
    .bin("visits").setTo(1)
    .bin("prefs").setTo(prefs)
    .execute();

Read a record

Use get to read the full record (metadata and all bins), or select specific bins.

Record record = session.query(key).execute().getFirstRecord();
System.out.format("Record: %s%n", record.bins);

Merge-update bins with put

Use put again to change one or more bins. With default write policies, the server merges new bins into the existing record and leaves other bins unchanged (this is not a full replace of every bin unless you use a replace-style policy).

session.upsert(key).bin("name").setTo("Alice K.").execute();

Atomic updates with operate

Use operate to execute multiple bin operations atomically in a single command. The following example increments the visits counter, updates a value inside the prefs map, and reads both bins — all in one round trip.

record = session.upsert(key)
    .bin("visits").add(1)
    .bin("prefs").onMapKey("lang").setTo("fr")
    .bin("visits").get()
    .bin("prefs").get()
    .execute()
    .getFirstRecord();


// Each bin holds a result per operation: the write's, then the read's
System.out.format("visits: %s, prefs: %s%n",
    record.getList("visits").get(1), record.getList("prefs").get(1));

Touch a record

Use touch to increment the record’s generation counter and optionally reset its time-to-live (TTL).

session.touch(key).expireRecordAfterSeconds(300).execute(); // TTL in seconds

Delete a record

Use delete (or remove) to delete a record. Enable durableDelete in the write policy to write a tombstone that prevents the record from resurrecting on a cold restart. See Durable Deletes for details.

// Durable delete:
// session.delete(key).withDurableDelete().execute();


session.delete(key).execute();

Usage note for all examples

All full record read and write commands accept policy parameters: Max Retries and Total Timeout.

Write operations take an optional time-to-live (TTL) parameter that sets when the record expires. Set the TTL to -1 so the record never expires.

Code block

Expand for the full single-record operations example 
import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import com.aerospike.client.sdk.DataSet;
import com.aerospike.client.sdk.Key;
import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.Session;
import com.aerospike.client.sdk.policy.Behavior;
import java.util.HashMap;
import java.util.Map;


public class SingleExample {
    public static void main(String[] args) {
        // Connect
        try (Cluster cluster = new ClusterDefinition("127.0.0.1", 3000).connect()) {
            Session session = cluster.createSession(Behavior.DEFAULT);


            Key key = DataSet.of("test", "demo").id("user1");


            // Upsert
            Map<String, Object> prefs = new HashMap<>();
            prefs.put("theme", "dark");
            prefs.put("lang", "en");


            // upsert creates the record or merges bins into it;
            // insert, update and replace are the other write verbs.
            session.upsert(key)
                .bin("name").setTo("Alice")
                .bin("visits").setTo(1)
                .bin("prefs").setTo(prefs)
                .execute();


            // Read
            Record record = session.query(key).execute().getFirstRecord();
            System.out.format("Record: %s%n", record.bins);


            // Merge-update (put)
            session.upsert(key).bin("name").setTo("Alice K.").execute();


            // Update (operate)
            record = session.upsert(key)
                .bin("visits").add(1)
                .bin("prefs").onMapKey("lang").setTo("fr")
                .bin("visits").get()
                .bin("prefs").get()
                .execute()
                .getFirstRecord();


            // Each bin holds a result per operation: the write's, then the read's
            System.out.format("visits: %s, prefs: %s%n",
                record.getList("visits").get(1), record.getList("prefs").get(1));


            // Touch
            session.touch(key).expireRecordAfterSeconds(300).execute(); // TTL in seconds


            // Delete
            // Durable delete:
            // session.delete(key).withDurableDelete().execute();


            session.delete(key).execute();
        }
    }
}

References

See these topics for language-specific examples: