Quickstart

Applies to

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

Create, read, and query records in Aerospike using the Developer SDK. This quickstart gets you from zero to working code in under 5 minutes.

Prerequisites

• Java 21+ or Python 3.10+
• Access to an Aerospike cluster (or run one locally)

Procedure

1. Install the SDK.

   Java

   Maven

   Add the dependency to your pom.xml:

   <dependency>
       <groupId>com.aerospike</groupId>
       <artifactId>aerospike-client-sdk</artifactId>
       <version>0.9.0-alpha.2</version>
   </dependency>

   Gradle (Groovy)

   Add to your build.gradle:

   dependencies {
       implementation 'com.aerospike:aerospike-client-sdk:0.9.0-alpha.2'
   }

   Gradle (Kotlin)

   Add to your build.gradle.kts:

   dependencies {
       implementation("com.aerospike:aerospike-client-sdk:0.9.0-alpha.2")
   }

   Python

   pip install aerospike-sdk

2. Connect to Aerospike.

   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.Session;
   
   try (Cluster cluster = new ClusterDefinition("localhost", 3000).connect()) {
       Session session = cluster.createSession(Behavior.DEFAULT);
       System.out.println("Connected to Aerospike!");
       // ... your code here ...
   }

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

   Python

   import asyncio
   from aerospike_sdk import Behavior, Client
   
   async def main():
       async with Client("localhost:3000") as client:
           session = client.create_session(Behavior.DEFAULT)
           print("Connected to Aerospike!")
           # ... your code here ...
   
   asyncio.run(main())

   📖 API reference: Client | Client.create_session() | Behavior.DEFAULT

3. Create a record.

   Java

   // Define your dataset (namespace + set)
   DataSet users = DataSet.of("test", "users");
   
   // Create or update a record
   session.upsert(users)
       .bins("name", "email", "age")
       .id("user-1").values("Alice Smith", "alice@example.com", 28)
       .execute();
   
   System.out.println("Record created!");

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

   Python

   # Define your dataset (namespace + set)
   users = DataSet.of("test", "users")
   
   # Create or update a record
   await session.upsert(key=users.id("user-1")).put({
       "name": "Alice Smith",
       "email": "alice@example.com",
       "age": 28,
   }).execute()
   
   print("Record created!")

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

4. Read it back.

   Java

   // Read the record by key
   RecordStream readStream = session.query(users.id("user-1")).execute();
   readStream.getFirst().ifPresent(result -> {
       Record user = result.recordOrThrow();
       System.out.println("Name: " + user.getString("name"));
       System.out.println("Email: " + user.getString("email"));
       System.out.println("Age: " + user.getInt("age"));
   });
   // Output:
   // Name: Alice Smith
   // Email: alice@example.com
   // Age: 28

   📖 API reference: DataSet.id(...) | Session.query(Key) | ChainableQueryBuilder.execute() | RecordStream.getFirst() | RecordResult.recordOrThrow() | Record.getString(...) | Record.getInt(...)

   Python

   # Read the record by key
   stream = await session.query(users.id("user-1")).execute()
   row = await stream.first_or_raise()
   user = row.record_or_raise()
   print(f"Name: {user.bins.get('name')}")
   print(f"Email: {user.bins.get('email')}")
   print(f"Age: {user.bins.get('age')}")
   stream.close()
   # Output:
   # Name: Alice Smith
   # Email: alice@example.com
   # Age: 28

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

5. Query with AEL.

   Java

   // Add a few more users first
   session.upsert(users)
       .bins("name", "age")
       .id("user-2").values("Bob Jones", 35)
       .id("user-3").values("Carol White", 22)
       .execute();
   
   // Query users over 25
   RecordStream queryStream = session.query(users)
       .where("$.age > 25")
       .execute();
   int count = 0;
   while (queryStream.hasNext()) {
       RecordResult result = queryStream.next();
       Record r = result.recordOrThrow();
       count++;
       System.out.println("  - " + r.getString("name"));
   }
   queryStream.close();
   System.out.println("Found " + count + " users over 25");
   // Output:
   // - Alice Smith
   // - Bob Jones
   // Found 2 users over 25
   // NOTE: A dataset-wide query without an ordering
   // clause can return records in any order.

   📖 API reference: Session.upsert(DataSet) | Session.query(DataSet) | OperationObjectBuilder.bins(...) | IdValuesBuilder.id(...) | IdValuesRowBuilder.values(...) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.execute() | RecordStream.hasNext() | RecordStream.next() | RecordStream.close() | RecordResult.recordOrThrow() | Record.getString(...)

   Python

   # Add a few more users first
   await session.upsert(key=users.id("user-2")).put({"name": "Bob Jones", "age": 35}).execute()
   await session.upsert(key=users.id("user-3")).put({"name": "Carol White", "age": 22}).execute()
   
   # Query users over 25
   stream = await session.query(users).where("$.age > 25").execute()
   count = 0
   async for row in stream:
       if row.is_ok:
           count += 1
           print(f"  - {row.record_or_raise().bins.get('name')}")
   stream.close()
   print(f"Found {count} users over 25")
   # Output:
   # - Alice Smith
   # - Bob Jones
   # Found 2 users over 25

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

Complete code

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 QuickstartApp {
    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 / update a few records
            session.upsert(users)
                .bins("name", "email", "age", "status")
                .id("user-1").values("Alice Smith", "alice@example.com", 28, "active")
                .id("user-2").values("Bob Jones", "bob@example.com", 35, "active")
                .id("user-3").values("Carol White", "carol@example.com", 22, "inactive")
                .execute();

            // Read one record

            // Query active adults
            RecordStream queryStream = session.query(users)
                .where("$.status == 'active' and $.age >= 18")
                .execute();
            int adultCount = 0;
            while (queryStream.hasNext()) {
                RecordResult result = queryStream.next();
                Record record = result.recordOrThrow();
                adultCount++;
                System.out.println("Adult user: " + record.getString("name"));
            }
            queryStream.close();
            System.out.println("Found " + adultCount + " active adults");

            // Cleanup so the example is repeatable.
            session.delete(users.ids("user-1", "user-2", "user-3")).execute();
        }
    }
}

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

Python

import asyncio

from aerospike_sdk import Behavior, DataSet, Client


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

        # Create / update a few records
        await session.upsert(key=users.id("user-1")).put(
            {
                "name": "Alice Smith",
                "email": "alice@example.com",
                "age": 28,
                "status": "active",
            }
        ).execute()
        await session.upsert(key=users.id("user-2")).put(
            {
                "name": "Bob Jones",
                "email": "bob@example.com",
                "age": 35,
                "status": "active",
            }
        ).execute()
        await session.upsert(key=users.id("user-3")).put(
            {
                "name": "Carol White",
                "email": "carol@example.com",
                "age": 22,
                "status": "inactive",
            }
        ).execute()

        # Read one record
        stream = await session.query(users.id("user-1")).execute()
        row = await stream.first_or_raise()
        print(f"Found: {row.record_or_raise().bins.get('name')}")
        stream.close()

        # Query active adults
        stream = await session.query(users).where("$.status == 'active' and $.age >= 18").execute()
        adult_count = 0
        async for row in stream:
            if row.is_ok:
                adult_count += 1
                print(f"Adult user: {row.record_or_raise().bins.get('name')}")
        stream.close()
        print(f"Found {adult_count} active adults")

        # Cleanup so the example is repeatable.
        await session.delete(key=users.id("user-1")).execute()
        await session.delete(key=users.id("user-2")).execute()
        await session.delete(key=users.id("user-3")).execute()


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

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

Verify

Confirm the quickstart succeeded using the output from step 5 (Query with AEL) in Procedure:

  - Alice Smith
  - Bob Jones
Found 2 users over 25

If you ran the complete example program (Python), you should also see Found: Alice Smith from the single-key read and Found 2 active adults from the query before cleanup. Cleanup deletes should finish without errors.

If connection fails, see Connect to Aerospike and Common issues.

Next steps

Create Records

Learn all the ways to insert, upsert, and configure records.

Create Records →

Query by Field Values

Filter and search your data with intuitive syntax.

Find Records →

Tune Performance & Reliability

Configure timeouts, retries, and consistency levels.

Configure the Client →

Handle Errors Gracefully

Handle errors with actionable diagnostics.

Error Handling →