Developer SDK

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

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.

Quick example

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

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

import asyncio

from aerospike_sdk import Client, DataSet


async def main() -> None:
    # Connect and create a session
    async with Client("localhost:3000") as client:
        session = client.create_session()
        users = DataSet.of("test", "users")
        key = users.id("user-1")

        # Create / update a record
        await session.upsert(key=key).put(
            {
                "name": "Alice",
                "email": "alice@example.com",
                "status": "active",
                "age": 28,
            }
        ).execute()

        # Query with AEL and stream results
        stream = await session.query(users).where("$.status == 'active'").execute()
        try:
            async for row in stream:
                record = row.record_or_raise()
                print(record.bins)
        finally:
            stream.close()

        # Cleanup
        await session.delete(key=key).execute()


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

📖 API reference: Client | Client.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()

Use the sync API for scripts, CLIs, and code that does not use asyncio. The fluent builder surface matches the async API: chain methods, then call .execute(). Operations block until they finish, and query streams use a regular for loop. No async/await required. Connect with SyncClient.

from aerospike_sdk import SyncClient, DataSet, Behavior

with SyncClient("localhost:3000") as client:
    session = client.create_session(Behavior.DEFAULT)
    users = DataSet.of("test", "users")

    # Write
    session.upsert(users.id(1)).bin("name").set_to("Alice").bin("age").set_to(30).execute()

    # Read
    stream = session.query(users.id(1)).execute()
    result = stream.first_or_raise()
    print(result.record.bins)

    # Query with AEL filter
    stream = session.query(users).where("$.age > 25").execute()
    for result in stream:
        print(result.record.bins)
    stream.close()

📖 API reference: SyncClient | SyncClient.create_session() | DataSet.of() | DataSet.id() | SyncSession.query() | SyncSession.upsert() | SyncQueryBuilder.where() | SyncWriteSegmentBuilder.set_to() | RecordStream.first_or_raise() | RecordStream.close() | SyncQueryBuilder.execute() | SyncWriteSegmentBuilder.execute()

Choose your path

New to Aerospike?

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

Quickstart →

Migrating from Classic 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	🚧 Coming Soon	—

The Python SDK supports Python 3.10 and later. For best performance, use Python 3.14 or later to take advantage of free-threading and other runtime improvements in the 3.14 series. See the Python 3.14 release notes for details.