Skip to content

Hello, World!

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

In this tutorial, you write a short program that connects to an Aerospike Database, writes a record, reads the record back, and closes the connection. 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, or Install on macOS and Windows with Docker to run one in a container.
  • A development environment for your language. The install links give the language versions each client supports.

Install the client

The Java SDK requires JDK 21 or later. Add the aerospike-client-sdk dependency to your pom.xml file.

<dependency>
<groupId>com.aerospike</groupId>
<artifactId>aerospike-client-sdk</artifactId>
<version>1.0.0</version>
</dependency>

For other build tools, see the Installation page.

Import the client modules

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;

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.

Define a record key

A record key has three parts: a namespace, an optional set, and a user key. Together they identify a record so you can read or write the record with its key.

By default, the database doesn’t store the user key. It stores a 20-byte digest, a hash of the set and the user key. For details, see the Data model.

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

Write a record

Aerospike has no schema, so you can write a record without any setup. This step writes the bins name, age, and greeting to the record that the key identifies.

session.upsert(key)
.bin("name").setTo("John Doe")
.bin("age").setTo(32)
.bin("greeting").setTo("Hello, World!")
.execute();

An upsert creates the record, or replaces the listed bins if the record exists.

Read the record

Read the record with the same key.

Record record = session.query(key).execute().getFirstRecord();

Display the record

Print the values of the bins and the record’s generation. The generation counts the writes to the record. It is 1 after the first write and increases with each later write.

System.out.println("name: " + record.getString("name"));
System.out.println("age: " + record.getInt("age"));
System.out.println("greeting: " + record.getString("greeting"));
System.out.println("Generation: " + record.generation);
name: John Doe
age: 32
greeting: Hello, World!
Generation: 1
Output

Delete the record

Delete the record, so that the tutorial leaves no data behind and you can run it again.

session.delete(key).execute();

Close the connection

When your program is finished with the database, close the client.

cluster.close();

Complete program

This program combines the steps.

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 HelloWorld {
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", "demo").id("foo");
session.upsert(key)
.bin("name").setTo("John Doe")
.bin("age").setTo(32)
.bin("greeting").setTo("Hello, World!")
.execute();
Record record = session.query(key).execute().getFirstRecord();
System.out.println("name: " + record.getString("name"));
System.out.println("age: " + record.getInt("age"));
System.out.println("greeting: " + record.getString("greeting"));
System.out.println("Generation: " + record.generation);
session.delete(key).execute();
}
}
}
name: John Doe
age: 32
greeting: Hello, World!
Generation: 1
Output

What you learned

In this tutorial, you connected to a database and used a key to write and read a record. You read the record generation, deleted the record, and closed the connection.

Next steps