Developer SDK

The Aerospike Developer SDK is a modern, developer-friendly interface for Aerospike. It provides intuitive APIs that feel native to your language, with built-in Aerospike Expression Language (AEL) queries and intelligent error handling.

Why use the Developer SDKs?

• Fluent, chainable methods that feel natural in Java and Python. No more verbose configuration objects.

• Filter queries with readable expressions like "$.status == 'active' and $.age > 21". No more complex, hard-to-maintain filter expressions.

• Actionable errors with recovery suggestions. Know exactly what went wrong and how to fix it.

• Separate development from operational concerns. Focus on writing application logic, not database plumbing.

• Mix reads, writes, deletes, and UDFs across different keys in a single heterogeneous batch round-trip.

• Multi-record ACID transactions with automatic retry on transient failures.

• Async and reactive support — CompletableFuture and Flow.Publisher in Java, asyncio in Python — alongside a synchronous API for simpler workloads.

Quick example

Java

import com.aerospike.client.sdk.policy.Behavior;
import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import com.aerospike.client.sdk.DataSet;
import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordResult;
import com.aerospike.client.sdk.RecordStream;
import com.aerospike.client.sdk.Session;

public class FluentQuickStart {
    public static void main(String[] args) {
        DataSet users = DataSet.of("test", "users");

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

            // Create or update a record.
            session.upsert(users)
                .bins("name", "email", "status", "age")
                .id("user-1").values("Alice", "alice@example.com", "active", 28)
                .execute();

            // Query and print active users.
            RecordStream stream = session.query(users)
                .where("$.status == 'active'")
                .execute();

            stream.forEach(result -> {
                Record record = result.recordOrThrow();
                System.out.println(record);
            });

            // Cleanup for repeatable local runs.
            session.delete(users.id("user-1")).execute().close();
        }
    }
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | Cluster.createSession(Behavior) | Cluster.close() | DataSet.of(...) | DataSet.id(...) | Session.upsert(DataSet) | Session.delete(Key) | Session.query(DataSet) | OperationObjectBuilder.bins(...) | IdValuesBuilder.id(...) | IdValuesRowBuilder.values(...) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.execute() | ChainableNoBinsBuilder.execute() | RecordStream.forEach(...) | RecordStream.close() | RecordResult.recordOrThrow()

Python (async)

Use the async API when your application runs on asyncio, such as web servers, task workers, or other concurrent workloads. Connect with ClusterDefinition, use async with for lifecycle management, await on .execute(), and async for to read query streams.

import asyncio

from aerospike_sdk import Behavior, ClusterDefinition, DataSet


async def main() -> None:
    async with await ClusterDefinition("localhost", 3000).connect() as cluster:
        session = cluster.create_session(Behavior.DEFAULT)
        users = DataSet.of("test", "users")

        await session.upsert(users.id(1)).put(
            {"name": "Alice", "age": 28, "country": "UK"}
        ).execute()
        await session.upsert(users.id(2)).put(
            {"name": "Bob", "age": 35, "country": "US"}
        ).execute()

        results = await (
            session.query(users)
            .where("$.age > 25 and $.country == 'US'")
            .execute()
        )
        async for row in results:
            if row.is_ok and row.record is not None:
                print(row.record.bins)

        await session.delete(users.id(1)).execute()
        await session.delete(users.id(2)).execute()


if __name__ == "__main__":
    asyncio.run(main())

📖 API reference: ClusterDefinition | Cluster.create_session() | DataSet.of() | DataSet.id() | Session.query() | Session.upsert() | Session.delete() | QueryBuilder.where() | WriteSegmentBuilder.put() | RecordResult.record_or_raise() | RecordStream.close() | QueryBuilder.execute() | WriteSegmentBuilder.execute()

Choose your path

New to Aerospike?

Start with the Quickstart to build your first app in 5 minutes.

Quickstart →

Migrating from Legacy client?

See what’s different and how to migrate your code.

Migration Guide →

Language support

Language	Status	Package
Java	✅ Available	com.aerospike:aerospike-client-sdk
Python	✅ Available	aerospike-sdk
Rust	Not yet available	—

The Python SDK supports Python 3.11 and later. For best performance under high concurrency, use the free-threaded build of Python 3.14 or later — these builds have a t suffix in the executable name (e.g., python3.14t) and ABI tag (e.g., cp314t). The free-threaded build removes GIL contention and unlocks the SDK’s AsyncPool and multi-loop async modes. See the Python 3.14 release notes (specifically the Free-threaded CPython section — 3.14 is the release that stabilized this build mode) and PEP 703 for background.

Next steps

• Install the SDK
• Connect to Aerospike
• Tune performance & reliability
• Update records (including Java CDT examples)
• Use transactions