Build your first Aerospike app

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</version>
   </dependency>

   Gradle (Groovy)

   Add to your build.gradle:

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

   Gradle (Kotlin)

   Add to your build.gradle.kts:

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

   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 ...
   }

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

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

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

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

   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

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.

   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:
   # Found 2 users over 25:
   #   - Alice Smith
   #   - Bob Jones

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

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

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 →