Query records

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Applies to

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

Learn how to find records in Aerospike using the Developer SDK’s AEL (Aerospike Expression Language) queries. AEL provides a readable, SQL-like syntax for filtering data.

Basic query

All operations which read data are queries, regardless of whether you are reading one record, 100 records, or performing an index query. Use query() to find records, and a where clause to provide filtering if desired:

Java
Python

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

DataSet users = DataSet.of("test", "users");

RecordStream stream = session.query(users)
    .where("$.status == 'active'")
    .execute();
stream.forEach(result -> {
    Record user = result.recordOrThrow();
    System.out.println("Name: " + user.getString("name"));
});

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

async def demo(session):
    users = DataSet.of("test", "users")
    stream = await session.query(users).where("$.status == 'active'").execute()
    async for row in stream:
        record = row.record_or_raise()
        print(f"Name: {record.bins.get('name')}")
    stream.close()

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

AEL operators

Use $.binName to get the contents of a bin called binName. String literals can be in either single or double quotes. Floats are numbers with a decimal point and integers are just digits.

Comparison operators

Operator	Description	Example
`==`	Equal	`"$.status == 'active'"`
`!=`	Not equal	`"$.status != 'inactive'"`
`>`	Greater than	`"$.age > 21"`
`>=`	Greater than or equal	`"$.age >= 18"`
`<`	Less than	`"$.balance < 0"`
`<=`	Less than or equal	`"$.score <= 100"`

See the AEL reference for a complete list of AEL operators.

Java
Python

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

// Numeric comparisons
RecordStream s1 = session.query(users).where("$.age >= 18").execute();
s1.forEach((RecordResult result) -> { /* use result.recordOrThrow() */ });

// String equality
RecordStream s2 = session.query(users).where("$.role == 'admin'").execute();
s2.forEach((RecordResult result) -> { /* ... */ });

// Not equal
RecordStream s3 = session.query(users).where("$.deleted != true").execute();
s3.forEach((RecordResult result) -> { /* ... */ });

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

async def demo(session):
    users = DataSet.of("test", "users")
    # Numeric comparisons
    stream = await session.query(users).where("$.age >= 18").execute()
    async for row in stream:
        pass
    stream.close()

    # String equality
    stream = await session.query(users).where("$.role == 'admin'").execute()
    async for row in stream:
        pass
    stream.close()

    # Not equal
    stream = await session.query(users).where("$.deleted != true").execute()
    async for row in stream:
        pass
    stream.close()

📖 API reference: DataSet.of() | Session.query() | QueryBuilder.where() | RecordStream.close() | QueryBuilder.execute()

Logical operators

Combine conditions with and, or, and not:

Java
Python

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

// AND
RecordStream a = session.query(users)
    .where("$.status == 'active' and $.age >= 18")
    .execute();
a.forEach((RecordResult result) -> { /* ... */ });

// OR
RecordStream b = session.query(users)
    .where("$.role == 'admin' or $.role == 'moderator'")
    .execute();
b.forEach((RecordResult result) -> { /* ... */ });

// NOT
RecordStream c = session.query(users)
    .where("not($.status == 'banned')")
    .execute();
c.forEach((RecordResult result) -> { /* ... */ });

// Complex combinations
RecordStream d = session.query(users)
    .where("($.status == 'active' or $.status == 'pending') and $.age >= 18")
    .execute();
d.forEach((RecordResult result) -> { /* ... */ });

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

async def demo(session):
    users = DataSet.of("test", "users")
    # AND
    stream = await session.query(users).where(
        "$.status == 'active' and $.age >= 18"
    ).execute()
    async for row in stream:
        pass
    stream.close()

    # OR
    stream = await session.query(users).where(
        "$.role == 'admin' or $.role == 'moderator'"
    ).execute()
    async for row in stream:
        pass
    stream.close()

    # NOT
    stream = await session.query(users).where("not($.status == 'banned')").execute()
    async for row in stream:
        pass
    stream.close()

    # Complex combinations
    stream = await session.query(users).where(
        "($.status == 'active' or $.status == 'pending') and $.age >= 18"
    ).execute()
    async for row in stream:
        pass
    stream.close()

📖 API reference: DataSet.of() | Session.query() | QueryBuilder.where() | RecordStream.close() | QueryBuilder.execute()

Membership and existence operators

Operator	Description	Example
`in`	Membership in a list	`"'admin' in $.roles"`
`exists()`	Path/bin existence check	`"$.email.exists()"`
`count()`	Collection cardinality	`"$.tags.count() > 3"`

Java
Python

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

// Membership in list
RecordStream s1 = session.query(users)
    .where("'admin' in $.roles")
    .execute();
s1.forEach((RecordResult result) -> { /* ... */ });

// Exists tests for the presence of the bin in the record
RecordStream s2 = session.query(users)
    .where("$.email.exists()")
    .execute();
s2.forEach((RecordResult result) -> { /* ... */ });

// Collection size
RecordStream s3 = session.query(users)
    .where("$.tags.count() > 3")
    .execute();
s3.forEach((RecordResult result) -> { /* ... */ });

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

async def demo(session):
    users = DataSet.of("test", "users")
    # Membership in list
    stream = await session.query(users).where(
        "'admin' in $.roles"
    ).execute()
    async for row in stream:
        pass
    stream.close()

    # Exists tests for the presence of the bin in the record
    stream = await session.query(users).where("$.email.exists()").execute()
    async for row in stream:
        pass
    stream.close()

    # Collection size
    stream = await session.query(users).where("$.tags.count() > 3").execute()
    async for row in stream:
        pass
    stream.close()

📖 API reference: DataSet.of() | Session.query() | QueryBuilder.where() | RecordStream.close() | QueryBuilder.execute()

Select specific bins

Return only the bins you need:

Java
Python

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

RecordStream stream = session.query(users)
    .where("$.status == 'active'")
    .readingOnlyBins("name", "email")  // Only return name and email
    .execute();
stream.forEach((RecordResult result) -> {
    Record user = result.recordOrThrow();
    System.out.println(user.getString("name"));
});

📖 API reference: Session.query(...) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.readingOnlyBins(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordResult.recordOrThrow() | Record.getString(...)

async def demo(session):
    users = DataSet.of("test", "users")
    stream = await (
        session.query(users)
        .where("$.status == 'active'")
        .bins(["name", "email"])
        .execute()
    )
    async for row in stream:
        record = row.record_or_raise()
        print(record.bins.get("name"))
    stream.close()

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

Limit results

Limit the number of records returned:

Java
Python

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

// Get first 10 active users
RecordStream stream = session.query(users)
    .where("$.status == 'active'")
    .limit(10)
    .execute();
stream.forEach((RecordResult result) -> { /* ... */ });

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

async def demo(session):
    users = DataSet.of("test", "users")
    # Get first 10 active users
    stream = await (
        session.query(users)
        .where("$.status == 'active'")
        .limit(10)
        .execute()
    )
    async for row in stream:
        pass
    stream.close()

📖 API reference: DataSet.of() | Session.query() | QueryBuilder.where() | QueryBuilder.limit() | RecordStream.close() | QueryBuilder.execute()

Stream results

The record streams buffer results returned from the server efficiently when queries which return large numbers of results are executed. This is transparent to the API, but it means that large result sets are not loaded into memory in their entirety.

Record streams should be closed when finished, freeing up resources on both the client side and server side. In Java, terminal helpers such as getFirst, getFirstRecord, and forEach close the stream when the call finishes. In Python, helpers like first(), first_or_raise(), collect(), and failures() consume the stream but do not auto-close it. Always call stream.close() (or wrap the work in a try / finally) to release client and server resources promptly.

For large result sets, stream records instead of loading all into memory:

Java
Python

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

// Process records one at a time
RecordStream stream = session.query(users)
    .where("$.status == 'active'")
    .execute();
stream.forEach((RecordResult result) -> {
    if (result.isOk()) {
        Record user = result.recordOrThrow();
        if (user != null) {
            System.out.println("Processing: " + user.getString("name"));
        }
    }
});

📖 API reference: Session.query(...) | ChainableQueryBuilder.where(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordResult.isOk() | RecordResult.recordOrThrow() | Record.getString(...)

async def demo(session):
    users = DataSet.of("test", "users")
    stream = await session.query(users).where("$.status == 'active'").execute()
    async for row in stream:
        record = row.record_or_raise()
        print(f"Processing: {record.bins.get('name')}")
    stream.close()

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

Java iteration patterns and key access

Accessing the record key

The Record class holds only bin data (bins, generation, expiration). The key is on the RecordResult wrapper, accessible via result.key():

stream.forEach(result -> {
    Key k = result.key();

    // String key:
    String strKey = k.userKey.toString();

    // Integer key (userKey is a Value; call toLong()):
    long intKey = k.userKey.toLong();

    Record record = result.recordOrThrow();
    // use record.getString("name"), record.getInt("age"), etc.
});

record.key and record.getKey() do not exist. Always use result.key() on the RecordResult, not on the Record itself.

userKey

k.userKey is only non-null when the user key was stored with the record at write time. Records written by external tooling, older clients, or any write that does not enable key storage will have k.userKey == null. Calling .toString() or .toLong() on a null userKey throws a NullPointerException.

Always guard userKey access before using it:

stream.forEach(result -> {
    Key k = result.key();
    // userKey is null if the key was not stored with the record
    String strKey = (k.userKey != null) ? k.userKey.toString() : null;
    if (strKey != null && strKey.startsWith("prefix-")) {
        Record record = result.recordOrThrow();
        // process record ...
    }
});

Accessing bins on a `Record`

Record exposes typed getters (getString, getInt, getLong, getBoolean, getMap, getList) as well as the raw bins map and getValue(String):

// Typed getter (preferred):
String name = record.getString("name");
int age     = record.getInt("age");

// Generic:
Object raw = record.getValue("profile");    // same as record.bins.get("profile")
Object raw2 = record.bins.get("profile");   // also fine

There is no record.get("binName") method. Use record.getValue("binName") or record.bins.get("binName") for untyped access.

`record.getMap()` returns `AerospikeMap<?,?>`, not `Map<String, Object>`

record.getMap("binName") returns AerospikeMap<?, ?>. Because of Java’s wildcard bounds, this cannot be directly assigned to Map<String, Object> without a cast, even though AerospikeMap does implement Map. The two simplest approaches:

// Option 1: via bins field (cleanest, no annotation needed):
// record.bins is Map<String,Object>, so .get() returns Object
Map<?, ?> profile = (Map<?, ?>) record.bins.get("profile");
String level = (String) profile.get("level");

// Option 2: via getValue(), with unchecked cast to typed Map:
@SuppressWarnings("unchecked")
Map<String, Object> profile2 = (Map<String, Object>) record.getValue("profile");
String level2 = (String) profile2.get("level");

`Record` import disambiguation: don’t use wildcard imports

Don’t use import com.aerospike.client.sdk.*;. It causes a compile error in Java 16+ because both com.aerospike.client.sdk.Record and java.lang.Record are pulled into scope and the compiler cannot resolve the ambiguity. Always import every class explicitly:

import com.aerospike.client.sdk.Record;        // required to avoid java.lang.Record conflict
import com.aerospike.client.sdk.RecordResult;
import com.aerospike.client.sdk.RecordStream;

Mutable captures in lambdas

Java lambdas require all captured local variables to be effectively final. This applies to every mutable type: booleans, integer counters, long accumulators, and any other variable modified inside the lambda. Use the matching Atomic* wrapper:

import java.util.concurrent.atomic.AtomicBoolean;
import java.util.concurrent.atomic.AtomicInteger;
import java.util.concurrent.atomic.AtomicLong;

AtomicBoolean found       = new AtomicBoolean(false);
AtomicInteger chunkNumber = new AtomicInteger(1);
AtomicLong    recordCount = new AtomicLong(0L);

stream.forEach(result -> {
    if (result.isOk()) {
        found.set(true);
        chunkNumber.getAndIncrement();
        recordCount.incrementAndGet();
    }
});

if (found.get()) { System.out.println("Record found!"); }

Query without filter (scan)

Query all records in a set:

Java
Python

import com.aerospike.client.sdk.Record;
import com.aerospike.client.sdk.RecordResult;
import com.aerospike.client.sdk.RecordStream;
import java.util.ArrayList;
import java.util.List;

// Get all users (use with caution on large datasets!)
RecordStream allStream = session.query(users).execute();
List<Record> allUsers = new ArrayList<>();
allStream.forEach(result -> {
    if (result.isOk()) {
        allUsers.add(result.recordOrThrow());
    }
});
// forEach closes allStream.

// Better: stream one record at a time without building a full list
RecordStream scan = session.query(users).execute();
scan.forEach(result -> {
    if (result.isOk()) {
        Record user = result.recordOrThrow();
        System.out.println(user.getString("name"));
    }
});

📖 API reference: Session.query(...) | ChainableQueryBuilder.execute() | RecordStream.forEach(...) | RecordResult.isOk() | RecordResult.recordOrThrow() | Record.getString(...)

async def demo(session):
    users = DataSet.of("test", "users")
    # Get all users (use with caution on large datasets!)
    stream = await session.query(users).execute()
    all_users = []
    async for row in stream:
        all_users.append(row.record_or_raise())
    stream.close()

    # Better: iterate without building a full list
    stream = await session.query(users).execute()
    async for row in stream:
        record = row.record_or_raise()
        print(record.bins.get("name"))
    stream.close()

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

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;
import com.aerospike.client.sdk.policy.Behavior;

public class QueryRecordsExample {
    public static void main(String[] args) {
        try (Cluster cluster = new ClusterDefinition("localhost", 3000).connect()) {
            Session session = cluster.createSession(Behavior.DEFAULT);
            DataSet users = DataSet.of("test", "users");
            String k1 = "query-example-1";
            String k2 = "query-example-2";
            String k3 = "query-example-3";
            String k4 = "query-example-4";

            // Cleanup so the example is repeatable.
            session.delete(users.ids(k1, k2, k3, k4)).execute().close();

            // Create sample data
            session.insert(users)
                .bins("name", "age", "status")
                .id(k1).values("Alice", 28, "active")
                .id(k2).values("Bob", 35, "active")
                .id(k3).values("Carol", 22, "inactive")
                .id(k4).values("David", 45, "active")
                .execute();

            // Simple query
            System.out.println("Active users:");
            RecordStream q1 = session.query(users)
                .where("$.status == 'active'")
                .execute();
            q1.forEach((RecordResult result) -> {
                Record u = result.recordOrThrow();
                System.out.println("  - " + u.getString("name"));
            });

            // Complex query
            System.out.println("\nActive adults over 30:");
            RecordStream q2 = session.query(users)
                .where("$.status == 'active' and $.age > 30")
                .readingOnlyBins("name", "age")
                .execute();
            q2.forEach(result -> {
                if (result.isOk()) {
                    Record u = result.recordOrThrow();
                    System.out.println(
                        "  - " + u.getString("name") + " (" + u.getInt("age") + ")"
                    );
                }
            });

            // Count
            RecordStream q3 = session.query(users)
                .where("$.status == 'active'")
                .execute();
            long activeCount = 0;
            while (q3.hasNext()) {
                RecordResult rr = q3.next();
                activeCount++;
            }
            q3.close();
            System.out.println("\nActive user count: " + activeCount);
        }
    }
}

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

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")
        k1 = users.id("query-example-1")
        k2 = users.id("query-example-2")
        k3 = users.id("query-example-3")
        k4 = users.id("query-example-4")

        # Cleanup so the example is repeatable.
        stream = await session.batch().delete(k1).delete(k2).delete(k3).delete(k4).execute()
        stream.close()

        # Create sample data
        await (
            session.batch()
            .insert(k1).put({"name": "Alice", "age": 28, "status": "active"})
            .insert(k2).put({"name": "Bob", "age": 35, "status": "active"})
            .insert(k3).put({"name": "Carol", "age": 22, "status": "inactive"})
            .insert(k4).put({"name": "David", "age": 45, "status": "active"})
            .execute()
        )

        # Simple query
        print("Active users:")
        stream = await session.query(users).where("$.status == 'active'").execute()
        async for row in stream:
            record = row.record_or_raise()
            print(f"  - {record.bins.get('name')}")
        stream.close()

        # Complex query
        print("\nActive adults over 30:")
        stream = await (
            session.query(users)
            .where("$.status == 'active' and $.age > 30")
            .bins(["name", "age"])
            .execute()
        )
        async for row in stream:
            r = row.record_or_raise()
            print(f"  - {r.bins.get('name')} ({r.bins.get('age')})")
        stream.close()

        # Count
        stream = await session.query(users).where("$.status == 'active'").execute()
        active_count = 0
        async for row in stream:
            row.record_or_raise()
            active_count += 1
        stream.close()
        print(f"\nActive user count: {active_count}")


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

📖 API reference: Client | Client.create_session() | DataSet.of() | DataSet.id() | Behavior.DEFAULT | Session.query() | Session.batch() | QueryBuilder.where() | QueryBuilder.bins() | RecordResult.record_or_raise() | RecordStream.close() | BatchOperationBuilder.execute() | BatchKeyOperationBuilder.put() | QueryBuilder.execute()

AEL and secondary indexes

AEL text does not force a full scan. The planner can use available secondary indexes for selective predicates and fall back to scans when no useful index exists.

📖 Learn more: AEL Reference covers the full AEL syntax.

API reference summary

Method	Description
`session.query(dataSet)`	Start a query on a DataSet
`.where("expression")`	Filter with AEL expression (use `$.bin` for bin paths)
`.readingOnlyBins(bins...)` / `.bins([...])` on `session.query(DataSet)`	Select specific bins to return
`.limit(n)`	Limit number of results
`.execute()`	Run the query and return a `RecordStream`
`RecordStream` / `async for`	Iterate results; call `stream.close()` when done

Next steps

AEL Reference

Full AEL syntax and operators.

AEL Reference →

Batch Operations

Efficient multi-record operations.

Batch Operations →

Async Operations

Non-blocking queries for high throughput.

Async Operations →

Query records

Applies to

Basic query

AEL operators

Comparison operators

Logical operators

Membership and existence operators

Select specific bins

Limit results

Stream results

Java iteration patterns and key access

Accessing the record key

Accessing bins on a Record

record.getMap() returns AerospikeMap<?,?>, not Map<String, Object>

Record import disambiguation: don’t use wildcard imports

Mutable captures in lambdas

Query without filter (scan)

Complete example

AEL and secondary indexes

API reference summary

Next steps

Accessing bins on a `Record`

`record.getMap()` returns `AerospikeMap<?,?>`, not `Map<String, Object>`

`Record` import disambiguation: don’t use wildcard imports