Skip to content

Expressions and SDK code

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

The expression you build in Aerospike Voyager is the same string your application ships with. There is no rewrite step when moving from prototype to production. The filter you build on day one is the same filter your production code uses.

This is the core portability promise of Voyager’s expression support: build, test, and refine your filter visually, then copy the expression string into the Aerospike Developer SDKs.

From visual filter to expression to SDK code

Here is a complete walkthrough showing how a visual filter becomes production code.

Step 1: Build a visual filter

On the Filters tab of the sample_users set, create two conditions joined with and:

  1. age > greater than 30, with Data type integer.
  2. active is true.

Click Apply.

Step 2: View the expression string

Click the Expression tab. Voyager displays the expression it generated and confirms it with Expression valid.:

$.age > 30 and $.active == true
Expression tab showing the generated expression $.age > 30 and $.active == true with the message Expression valid. and the Apply button

In the Aerospike Expression Language (AEL), the $. prefix refers to a bin. For example, $.age > 30 keeps the records whose age bin is greater than 30. The same string works as the where clause in the Aerospike Developer SDKs.

For the complete operator list, see Operators in the filtering guide.

Step 3: Copy the expression

On the Filters tab, click the Copy expression icon beside the expression preview. On the Expression tab, select the text in the editor and copy it.

Step 4: Use the expression in SDK code

Paste the expression into your application. In the Aerospike Java SDK, the AEL string is what the .where(...) clause accepts, so the paste is literal, with no builder rewrite.

Java:

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


public class FilterExample {
    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", "sample_users");


            // Paste the expression copied from Voyager, unchanged
            try (RecordStream stream = session.query(users)
                    .where("$.age > 30 and $.active == true")
                    .execute()) {
                stream.forEach(r -> {
                    if (r.isOk()) {
                        System.out.println(r.recordOrThrow());
                    }
                });
            }
        }
    }
}

Python:

import asyncio


from aerospike_sdk import Behavior, ClusterDefinition




async def main() -> None:
    # Connect to the cluster
    async with await ClusterDefinition("localhost", 3000).connect() as cluster:
        session = cluster.create_session(Behavior.DEFAULT)


        # Paste the expression copied from Voyager, unchanged
        stream = await (
            session.query(namespace="test", set_name="sample_users")
            .where("$.age > 30 and $.active == true")
            .execute()
        )


        async for row in stream:
            if row.record:
                print(row.record.bins)




asyncio.run(main())

Copying expressions

To copy an expression string from Voyager, use either tab:

  • On the Filters tab, click the Copy expression icon at the right of the expression preview below the conditions. The tooltip changes to Copied.
  • On the Expression tab, select the text in the editor and copy it with CMD+C on macOS or CTRL+C on Windows and Linux.

Troubleshoot

SymptomCauseFix
The filter runs in Voyager, but the SDK query fails on the same clusterThe SDK’s .where(...) sends the AEL text to the server, which needs Aerospike Database 8.2.0 and later. Voyager compiles the filter itself.Upgrade the cluster to Aerospike Database 8.2.0.
The server rejects a string function copied from VoyagerThe expression used a positional argument, such as contains('x'). The server needs the named form.Write contains(needle: 'x'). See String path functions for the argument names.
The SDK query returns different records than VoyagerThe copied expression changed, or the data changed between runsCopy the expression again with Copy expression, and compare the counts on the same data.

For other problems, see Voyager troubleshooting.