Migrating from legacy client

Applies to

• Aerospike Developer SDK (Java 21+ and Python 3.11+)
• Aerospike Database 6.0 or later unless a section states otherwise

Code examples

Examples assume a connected session from Connect to Aerospike. Each usage guide lists shared imports in a tabbed block near the top of the page; snippet blocks add imports only for types not already shown. The first code block in each section includes dataset setup; later blocks in that section reuse those values. When a page includes a Complete example section, that block is fully self-contained.

This guide helps you migrate an existing application from the Classic Aerospike client to the Developer SDK.

Why migrate?

The Developer SDK offers several advantages over the legacy client:

• Cleaner syntax — Chainable, fluent APIs reduce boilerplate
• AEL queries — Human-readable filter expressions
• Better error handling — Actionable errors with recovery suggestions
• Decoupled configuration — Separate connection from behavior

Before you start

1. Confirm your Aerospike server is compatible (version 6.0 or later).
2. Install the Developer SDK as a separate package. It does not replace the legacy client.
3. Plan to run both clients side by side during migration if you need a gradual cutover.
4. Inventory the secondary indexes your filtered queries depend on. See Query with filters.

Conceptual changes

Connection model

Classic: Direct client with embedded configuration

SDK: Separate Cluster (connection) and Session (behavior)

Java Classic

// Classic: Everything in one place
AerospikeClient client = new AerospikeClient(
    new ClientPolicy(),
    new Host("localhost", 3000)
);

📖 API reference: Host(String,int) | Host(String,String,int)

Java SDK

import com.aerospike.client.sdk.policy.Behavior;
import com.aerospike.client.sdk.Cluster;
import com.aerospike.client.sdk.ClusterDefinition;
import com.aerospike.client.sdk.Session;

// SDK: Connection separate from behavior
try (Cluster cluster = new ClusterDefinition("localhost", 3000).connect()) {
    Session session = cluster.createSession(Behavior.DEFAULT);
}

📖 API reference: ClusterDefinition(String,int) | ClusterDefinition.connect() | Cluster.createSession(Behavior) | Cluster.close()

Python Classic

# Classic: Everything in one place
client = aerospike.client({
    'hosts': [('localhost', 3000)]
}).connect()

📖 API reference: aerospike.client() | Client.connect()

Python SDK

from aerospike_sdk import Behavior, ClusterDefinition

# SDK: Connection separate from behavior
async with await ClusterDefinition("localhost", 3000).connect() as cluster:
    session = cluster.create_session(Behavior.DEFAULT)

📖 API reference: Behavior.DEFAULT

Key and record references

Classic: Explicit Key objects with namespace, set, and user key

SDK: DataSet represents namespace + set, .id() creates a Key

Java Classic

Key key = new Key("test", "users", "user-1");

📖 API reference: Key

Java SDK

DataSet users = DataSet.of("test", "users");
Key key = users.id("user-1");

📖 API reference: DataSet.of(...) | DataSet.id(...)

Python Classic

key = ("test", "users", "user-1")

📖 API reference: Key Tuple

Python SDK

users = DataSet.of("test", "users")
ref = users.id("user-1")

📖 API reference: DataSet.of() | DataSet.id()

Operation mapping

Create (put)

Java Classic

client.put(null, key, new Bin("name", "Alice"), new Bin("age", 30));

📖 API reference: com.aerospike.client.sdk

Java SDK

session.insert(users)
    .bins("name", "age")
    .id("user-1").values("Alice", 30)
    .execute();

📖 API reference: Session.insert(DataSet) | OperationObjectBuilder.bins(...) | IdValuesBuilder.id(...) | IdValuesRowBuilder.values(...) | ChainableQueryBuilder.execute()

Python Classic

client.put(key, {"name": "Alice", "age": 30})

📖 API reference: Client.put()

Python SDK

await session.insert(key=users.id("user-1")).put(
    {"name": "Alice", "age": 30}
).execute()

📖 API reference: DataSet.id() | Session.insert() | WriteSegmentBuilder.put() | WriteSegmentBuilder.execute()

Read (get)

Java Classic

Record record = client.get(null, key);
String name = record.getString("name");

📖 API reference: Record.getString(...)

Java SDK

import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordStream;

String name;
try (RecordStream stream = session.query(users.id("user-1")).execute()) {
    Record user = stream.getFirstRecord();
    name = user.getString("name");
}

📖 API reference: DataSet.id(...) | Session.query(Key) | ChainableQueryBuilder.execute() | RecordStream.getFirstRecord() | Record.getString(...)

Python Classic

key, meta, bins = client.get(key)
name = bins["name"]

📖 API reference: Client.get()

Python SDK

stream = await session.query(users.id("user-1")).execute()
row = await stream.first_or_raise()
user = row.record_or_raise()
name = user.bins.get("name")
stream.close()

📖 API reference: DataSet.id() | Session.query() | RecordResult.record_or_raise() | RecordStream.first_or_raise() | RecordStream.close() | QueryBuilder.execute()

Update

Java Classic

client.put(null, key, new Bin("visits", 1), new Bin("updated", true));

📖 API reference: com.aerospike.client.sdk

Java SDK

session.update(users.id("user-1"))
    .bin("visits").setTo(1)
    .bin("updated").setTo(true)
    .execute();

📖 API reference: DataSet.id(...) | Session.update(DataSet) | ChainableOperationBuilder.bin(...) | ChainableQueryBuilder.bin(...) | ChainableQueryBuilder.execute()

Python Classic

client.put(key, {"visits": 1, "updated": True})

📖 API reference: Client.put()

Python SDK

await (
    session.update(users.id("user-1"))
    .bin("visits").set_to(1)
    .bin("updated").set_to(True)
    .execute()
)

📖 API reference: DataSet.id() | Session.update() | QueryBuilder.bin() | WriteSegmentBuilder.set_to() | WriteSegmentBuilder.bin() | WriteSegmentBuilder.execute()

Delete

Java Classic

client.delete(null, key);

📖 API reference: com.aerospike.client.sdk

Java SDK

session.delete(users.id("user-1")).execute().close();

📖 API reference: DataSet.id(...) | Session.delete(Key) | ChainableQueryBuilder.execute() | ChainableNoBinsBuilder.execute() | RecordStream.close()

Python Classic

client.remove(key)

📖 API reference: Client.remove()

Python SDK

stream = await session.delete(key=users.id("user-1")).execute()
stream.close()

📖 API reference: DataSet.id() | Session.delete() | RecordStream.close() | WriteSegmentBuilder.execute()

Query with filters

Java Classic

Statement stmt = new Statement();
stmt.setNamespace("test");
stmt.setSetName("users");
stmt.setFilter(Filter.range("age", 21, 100));

RecordSet rs = client.query(null, stmt);
while (rs.next()) {
    Record record = rs.getRecord();
    // process record
}

Java SDK

import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordStream;

RecordStream stream = session.query(users)
    .where("$.age >= 21")
    .execute();
stream.forEach(result -> {
    Record row = result.recordOrThrow();
    // process record
});
stream.close();

📖 API reference: Session.query(DataSet) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordStream.close() | RecordResult.recordOrThrow()

Python Classic

query = client.query("test", "users")
query.where(aerospike.predicates.between("age", 21, 100))

for record in query.results():
    # process record
    pass

📖 API reference: Client.query() | Query.where() | predicates.between() | Query.results()

Python SDK

stream = await session.query(users).where("$.age >= 21").execute()
async for row in stream:
    row.record_or_raise()
    pass  # process the returned record
stream.close()

📖 API reference: Session.query() | QueryBuilder.where() | RecordResult.record_or_raise() | RecordStream.close() | QueryBuilder.execute()

Behavior change: the server now selects the index

A legacy filter names a secondary index. Without an index on that bin, the query fails with AS_ERR_SINDEX_NOT_FOUND (201).

An AEL where clause names a bin. The query optimizer selects a readable secondary index that can serve the predicate. If none matches, the query either runs as a primary index (PI) query and reads every record in the set, or fails with 201, depending on allowScansWithWhere.

A ported query therefore does not fail the way the original did when its index is missing. Confirm that every filtered bin still has a readable (RW) index before you cut over.

Migration strategy

Option 1: gradual migration

1. Add Developer SDK dependency alongside classic
2. Create new features with Developer SDK
3. Migrate existing code incrementally
4. Remove legacy client when migration complete

Option 2: full migration

1. Create a feature branch
2. Replace all legacy client calls with Developer SDK equivalents
3. Run comprehensive tests
4. Deploy with confidence

What’s not supported (yet)

Some advanced features from the legacy client are not yet available in the Developer SDK:

• Admin operations (cluster management)

HyperLogLog and GeoJSON are supported in the Python SDK. See Update records and Secondary indexes.

Next steps

• Quickstart — Get started with Developer SDK
• AEL Queries — Learn the query syntax
• Error Handling — Understand error recovery