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 blocking API for applications that do not run an event loop.

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")

        # Create or update a record.
        await session.upsert(users.id("user-1")).put(
            {"name": "Alice", "email": "alice@example.com", "status": "active", "age": 28}
        ).execute()

        # Query and print active users.
        results = await (
            session.query(users)
            .where("$.status == 'active'")
            .execute()
        )
        async for row in results:
            print(row.record_or_raise().bins)

        # Cleanup for repeatable local runs.
        await session.delete(users.id("user-1")).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()

Python (sync)

Use the sync API when your application does not run an event loop, such as scripts, batch jobs, or frameworks that call blocking code. It is the same surface without async/await: connect with the sync ClusterDefinition and every builder chain reads the same.

from aerospike_sdk import Behavior, DataSet
from aerospike_sdk.sync import ClusterDefinition


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

        # Create or update a record.
        session.upsert(users.id("user-1")).put(
            {"name": "Alice", "email": "alice@example.com", "status": "active", "age": 28}
        ).execute()

        # Query and print active users.
        results = (
            session.query(users)
            .where("$.status == 'active'")
            .execute()
        )
        for row in results:
            print(row.record_or_raise().bins)

        # Cleanup for repeatable local runs.
        session.delete(users.id("user-1")).execute()


if __name__ == "__main__":
    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 (such as python3.14t) and ABI tag (such as 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