Aerospike Java SDK

Note

This is a developer preview, not yet ready for production use, but with future releases planned. We encourage feedback from the Aerospike developer community through GitHub issues.

A ground-up redesign of the Aerospike Java client — fluent, type-safe, and built for modern Java (21+).

Quick Start

importcom.aerospike.client.sdk.*;
importjava.util.List;
importjava.util.Map;
publicclassQuickStart {
publicstaticvoidmain(String[] args) {
// Connect to the clustertry (Clustercluster = newClusterDefinition("localhost", 3000)
.withNativeCredentials("admin", "password")
.connect()) {
Sessionsession = cluster.createSession(Behavior.DEFAULT);
DataSetusers = DataSet.of("test", "users");
// --- Insert some data ---session.upsert(users.id("alice"))
.bin("name").setTo("Alice")
.bin("age").setTo(30)
.bin("tags").setTo(List.of("admin", "active"))
.bin("scores").setTo(List.of(95, 87, 92, 78))
.bin("prefs").setTo(Map.of("theme", "dark", "lang", "en"))
.execute();
// --- Read it back ---Recordrecord = session.query(users.id("alice"))
.execute()
.getFirstRecord();
System.out.println(record.getString("name")); // AliceSystem.out.println(record.getLong("age")); // 30// --- Update a bin ---session.update(users.id("alice"))
.bin("age").setTo(31)
.execute();
// --- Append to a list ---session.upsert(users.id("alice"))
.bin("scores").listAppend(99)
.execute();
// --- Query a list range ---session.query(users.id("alice"))
.bin("scores").onListValueRange(90, 100).getValues()
.execute();
// --- Set a map entry ---session.upsert(users.id("alice"))
.bin("prefs").onMapKey("notifications").upsert(true)
.execute();
// --- Read a map key ---session.query(users.id("alice"))
.bin("prefs").onMapKey("theme").getValues()
.execute();
// --- Filter with AEL ---session.query(users)
.where("$.age > 25 and 'active' in $.tags")
.execute();
}
}
}

What's happening

1. Connect — ClusterDefinition configures the connection (hosts, credentials, TLS); calling .connect() returns a Cluster that manages node discovery and connection pooling. Cluster is Closeable — wrap it in try-with-resources.

2. Session — A lightweight handle through which all operations flow. Create as many as you need with different Behavior profiles to vary timeouts, retries, and consistency settings without changing application code.

3. Write verbs — upsert, insert, update, replace, and replaceIfExists each enforce intent at the method level. No more runtime policy flags.

4. Reads — session.query(key) returns a RecordStream that works as an Iterator, a Java Stream, or a CompletableFuture.

5. CDT operations — Bins containing Lists and Maps are manipulated through a fluent navigation chain: select elements (.onListValueRange(...), .onMapKey(...)), then choose an action (.getValues(), .remove(), .count()). See the List Operations and Map Operations references for every available operation.

6. AEL filtering — The Aerospike Expression Language lets you write server-side filters as concise strings ("$.age > 25"). When a matching secondary index exists, the SDK selects it automatically. See the AEL Documentation for the full language reference.

Features

For comprehensive documentation with code examples for every feature, see the Key Features Guide.

Feature	Description	Details
Fluent write verbs	insert, update, upsert, replace, replaceIfExists — intent is explicit at the method level	Write Operations
Reads & RecordStream	Universal RecordStream return type with Iterator, Stream, and CompletableFuture support	Read Operations, RecordStream
Heterogeneous batching	Mix reads, writes, deletes, and UDFs across different keys in a single server round-trip	Batch Chains
AEL (Expression Language)	Text-based server-side filters with automatic secondary index selection	AEL Reference
Expression bin ops	Compute derived values server-side (selectFrom, upsertFrom)	Expression Ops
List & Map CDT operations	Fluent navigation and manipulation of nested collection data types	List Ops, Map Ops
Async & reactive	executeAsync() with CompletableFuture and Flow.Publisher (backpressure)	Async Operations
Transactions	Multi-record ACID transactions with automatic retry on transient failures	Transactions
Behavior (policy config)	Cascading, selector-based configuration — separate dev concerns from ops concerns	Behavior
Object mapping	RecordMapper and TypeSafeDataSet for mapping Java objects to/from records	Object Mapping
Queries & scans	Dataset-level queries with pagination, sorting, partition targeting, and throttling	Queries
Background operations	Server-side bulk updates, deletes, and UDF execution across entire sets	Background Ops
UDFs	Register, execute, and chain Lua User Defined Functions	UDFs
Secondary indexes	Create and drop indexes; AEL queries use them automatically	Indexes
Info commands	Typed, structured access to cluster metadata (namespaces, sets, indexes)	Info Commands
Exception hierarchy	Fine-grained unchecked exceptions with result codes for programmatic handling	Exceptions

Building

mvn compile # Compile
mvn test# Run tests
mvn javadoc:javadoc # Generate Javadoc

Requirements

• Java 21+ (Java 24+ recommended for improved virtual thread performance)
• Maven 3.9.5+