Skip to content

Basic operations

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

In this tutorial, you use basic create, read, update, and delete operations on Aerospike records. You also run several operations on one record in a single command. Choose your client in any tab group. The page remembers your choice.

The Java SDK and Python SDK tabs use the Aerospike Developer SDKs. The Java and Python tabs use the legacy clients.

Prerequisites

  • An Aerospike Database running on your computer and listening on port 3000, with a namespace named test. The Java SDK and Python SDK tabs require Aerospike Database 8.2.0 or later. For the other clients, see the Client Compatibility Matrix. To set up a database, see the Quickstart.
  • Your client installed. To install it, follow the Install the client step of the Hello, World! tutorial.

Records

Data in Aerospike is stored in records. A record belongs to a namespace, which is similar to a database, and optionally to a set, which is similar to a table. A record has bins, which are named, typed containers for values. A bin can hold a scalar value (String, Integer, or Blob) or a collection (List or Map).

For more information, see the Data model.

A key identifies a record. The key has a namespace, a set, and a user key. The client sends the database a 20-byte digest, a hash of the set and the user key. The database uses that digest to find the record. By default, the database doesn’t store the user key.

Import the client modules

import java.util.List;
import java.util.Map;
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.RecordResult;
import com.aerospike.client.sdk.RecordStream;
import com.aerospike.client.sdk.Session;
import com.aerospike.client.sdk.policy.Behavior;

Connect to the database

Connect to the database on port 3000 of your computer. This is the default port. If your database runs on another host or port, change the address.

The client connects to the seed node you specify, which is the first node it contacts, and then discovers the other nodes in the cluster.

Cluster cluster = new ClusterDefinition("127.0.0.1", 3000).connect();
Session session = cluster.createSession(Behavior.DEFAULT);

The session applies a Behavior, which sets the timeouts and retries for each command. Behavior.DEFAULT is a reasonable starting point.

Write a record

The put command writes a record. In the SDKs, the same command is an upsert, which creates the record if it doesn’t exist and updates it if it does.

The key identifies the record: a namespace, a set, and a user key. Write a record in the set basicops with the user key bender and six bins. The bins hold a String, an Integer, a Map, a List, a Blob, and another Integer. A put writes all the bins in one command, and it leaves any other bins in the record as they are.

The last step deletes the records that remain, so you can run the tutorial again.

DataSet dataSet = DataSet.of("test", "basicops");
Key key = dataSet.id("bender");
session.upsert(key)
.bin("name").setTo("Bender")
.bin("serialnum").setTo(2716057)
.bin("lastsentence").setTo(Map.of("BBS", "Well, we're boned", "TBwaBB", "I love you, meatbags!"))
.bin("composition").setTo(List.of("40% zinc", "40% titanium", "30% iron", "40% dolomite"))
.bin("apartment").setTo(new byte[] {0x24})
.bin("quote_cnt").setTo(47)
.execute();

Read a record

The get command reads a record by its key and returns its bins and its metadata. A read returns two metadata values:

  • The generation is the number of times the record has been written. A new record has generation 1.
  • The time to live (TTL) is the number of seconds until the record expires. When a client writes a record with a TTL of 0, the server applies the default-ttl of the namespace. For details, see Configuring namespace data retention.

Read the record you wrote and print three bins and the generation.

Record record = session.query(key).execute().getFirstRecord();
System.out.println("name: " + record.getString("name"));
System.out.println("serialnum: " + record.getLong("serialnum"));
System.out.println("quote_cnt: " + record.getLong("quote_cnt"));
System.out.println("Generation: " + record.generation);
name: Bender
serialnum: 2716057
quote_cnt: 47
Generation: 1
Output

Prepend, append, and increment bins

Update the record with three commands, each with one operation. Prepend Dr. to the String. Append Bending Rodriguez to the String. Add 3 to the Integer. Each command that writes the record increments its generation, so the generation goes from 1 to 4.

session.upsert(key).bin("name").prepend("Dr. ").execute();
session.upsert(key).bin("name").append(" Bending Rodriguez").execute();
session.upsert(key).bin("quote_cnt").add(3).execute();
record = session.query(key).execute().getFirstRecord();
System.out.println("name: " + record.getString("name"));
System.out.println("quote_cnt: " + record.getLong("quote_cnt"));
System.out.println("Generation: " + record.generation);
name: Dr. Bender Bending Rodriguez
quote_cnt: 50
Generation: 4
Output

Read specific bins

A read can return only the bins you name. This reduces the data that the database sends over the network.

Read the serialnum and quote_cnt bins, and print how many bins the result has.

record = session.query(key).bin("serialnum").get().bin("quote_cnt").get().execute().getFirstRecord();
System.out.println("Bins returned: " + record.bins.size());
System.out.println("serialnum: " + record.getLong("serialnum"));
System.out.println("quote_cnt: " + record.getLong("quote_cnt"));
Bins returned: 2
serialnum: 2716057
quote_cnt: 50
Output

Check whether a record exists

An exists command returns whether a record is in the database, without returning its bins. Check the record you wrote and a key that you never wrote.

Key missing = dataSet.id("nokey");
System.out.println("bender exists: " + session.exists(key).execute().getFirstBoolean().orElse(false));
System.out.println("nokey exists: " + session.exists(missing).execute().getFirstBoolean().orElse(false));
bender exists: true
nokey exists: false
Output

Read several records in one batch

A batch read gets several records in one call, which saves network round trips compared with reading them one at a time. Write two records, key1 and key2, each with a batch bin. Then read three keys in one batch. The third key, key3, doesn’t exist.

A batch returns a result for each key, in the order of the keys. The result for a missing key has no record. The Java SDK and Python SDK omit missing keys from the results unless you call includeMissingKeys() or include_missing_keys(), as the examples do.

Key key1 = dataSet.id("key1");
Key key2 = dataSet.id("key2");
Key key3 = dataSet.id("key3");
session.upsert(key1).bin("batch").setTo(1).execute();
session.upsert(key2).bin("batch").setTo(2).execute();
RecordStream stream = session.query(key1, key2, key3).includeMissingKeys().execute();
while (stream.hasNext()) {
RecordResult result = stream.next();
if (result.isOk()) {
System.out.println(result.getKey().userKey + ": " + result.getRecord().getLong("batch"));
} else {
System.out.println(result.getKey().userKey + ": not found");
}
}
key1: 1
key2: 2
key3: not found
Output

Delete a record

The delete command removes a record. Delete key1, and then check that it no longer exists.

session.delete(key1).execute();
System.out.println("key1 exists: " + session.exists(key1).execute().getFirstBoolean().orElse(false));
key1 exists: false
Output

Run several operations in one command

An operate command runs several operations on one record as a single command. The database runs the operations in the order you specify. The whole command is atomic, so no other command sees the record with only some operations applied. The command increments the generation once, however many operations it has.

Write a record for fry with an age bin and a career bin. Then run one command that adds 1000 to the age, builds the name bin in three steps (write J., prepend Phillip , and append Fry), and reads the career bin. Finally, read the record to see the result of the writes.

The command returns only the bin that the read operation names and a value for each operation that reads. If several operations in one command use the same bin, some clients return a list of results for that bin. To keep the results simple, this example reads a bin that no other operation in the command uses.

Key fry = dataSet.id("fry");
session.upsert(fry).bin("age").setTo(25).bin("career").setTo("delivery boy").execute();
Record result = session.upsert(fry)
.bin("age").add(1000)
.bin("name").setTo("J.")
.bin("name").prepend("Phillip ")
.bin("name").append(" Fry")
.bin("career").get()
.execute().getFirstRecord();
System.out.println("career: " + result.getString("career"));
record = session.query(fry).execute().getFirstRecord();
System.out.println("name: " + record.getString("name"));
System.out.println("age: " + record.getLong("age"));
System.out.println("Generation: " + record.generation);
career: delivery boy
name: Phillip J. Fry
age: 1025
Generation: 2
Output

Read and delete a record in one command

An operate command can read a record and delete it in the same command. The read comes first, so it returns the bins before the delete removes the record.

Read the name bin of fry and delete the record, and then check that the record no longer exists.

Record last = session.upsert(fry).bin("name").get().deleteRecord().execute().getFirstRecord();
System.out.println("name: " + last.getString("name"));
System.out.println("fry exists: " + session.exists(fry).execute().getFirstBoolean().orElse(false));
name: Phillip J. Fry
fry exists: false
Output

Delete the remaining records and close the connection

Delete the two records that are still in the database, and then close the client.

session.delete(key).execute();
session.delete(key2).execute();
cluster.close();

Complete program

This program combines the steps. It writes a record, reads it, updates it with one multi-operation command, and deletes it.

import java.util.List;
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;
public class BasicOperations {
public static void main(String[] args) {
try (Cluster cluster = new ClusterDefinition("127.0.0.1", 3000).connect()) {
Session session = cluster.createSession(Behavior.DEFAULT);
Key key = DataSet.of("test", "basicops").id("bender");
session.upsert(key)
.bin("name").setTo("Bender")
.bin("composition").setTo(List.of("40% zinc", "40% titanium", "30% iron", "40% dolomite"))
.bin("quote_cnt").setTo(47)
.execute();
Record record = session.query(key).execute().getFirstRecord();
System.out.println("name: " + record.getString("name"));
System.out.println("quote_cnt: " + record.getLong("quote_cnt"));
session.upsert(key)
.bin("name").prepend("Dr. ")
.bin("name").append(" Bending Rodriguez")
.bin("quote_cnt").add(3)
.execute();
record = session.query(key).execute().getFirstRecord();
System.out.println("name: " + record.getString("name"));
System.out.println("quote_cnt: " + record.getLong("quote_cnt"));
System.out.println("Generation: " + record.generation);
session.delete(key).execute();
System.out.println("bender exists: " + session.exists(key).execute().getFirstBoolean().orElse(false));
}
}
}
name: Bender
quote_cnt: 47
name: Dr. Bender Bending Rodriguez
quote_cnt: 50
Generation: 2
bender exists: false
Output

What you learned

You wrote, read, updated, and deleted records, read specific bins and batches, and checked existence. You also ran several operations on one record in one atomic command, including a read and a delete in the same command.

Next steps