Skip to content
Inviting nominations for the Champions of Scale - Nominate a leader building internet-scale data infastructure today! Nominate someone
Database ( latest 8.1.0 )
/Learn/Tutorials/Expression indexes

Tutorial for Expression Indexes

This tutorial introduces expression indexes in Aerospike Database. This tutorial assumes you are familiar with secondary indexes and expressions in Aerospike Database.

Overview

Expression indexes build sparse secondary indexes over computed values defined by an Aerospike expression. Instead of indexing every record or persisting derived bins, the index evaluates your expression and includes only the records that match.

In this tutorial, you will:

  • Create your first expression index
  • Run your first query against it
  • Compare expression indexes against traditional secondary indexes

Why it matters

  • Simpler application code — push filter logic into the index; no extra bins or duplicated client filters.
  • Reduced memory footprint — indexes include only relevant records.
  • Total cost of ownership — reduced RAM and compute requirements lower infrastructure spend.
  • Faster queries — less to scan means lower latency.

When to use expression indexes

Use them when you would otherwise:

  • Persist a derived value solely to make it indexable.
  • Index every record even though only a subset are needed for business logic.
  • Re-implement the same filter logic across multiple clients or languages.

Get started

Prerequisites

Verify your server version using asinfo:

Terminal window
    # Verify you’re running Aerospike 8.1.0+
    asinfo -v build

Create expression, index, and query

  1. Create the expression.

    The following example creates the “adult users in target countries” expression. For this example, let’s assume an adult is someone 18 or older, and our target countries are Australia, Canada and Botswana.

    For this tutorial, we’ll generate the Base64 representation of the expression in the client and then use the asadm command-line tool to create the index. This approach separates application logic (defining the filter) from database administration (creating the index).

    // Build an expression that indexes age only for adults in AU/CA/BW that are 18 or older
    Expression filterExp = Exp.build(
            Exp.cond(
                Exp.and(
                    Exp.ge(// Is the age 18 or older?
                            Exp.intBin("age"),
                            Exp.val(18)
                    ),
                    ListExp.getByValue( // Do they live in a target country?
                            ListReturnType.EXISTS,
                            Exp.stringBin("country"),
                            Exp.val(List.of("Australia", "Canada", "Botswana"))
                    )
                ),
                Exp.intBin("age"), // If true, return the age of the customer to be indexed
                Exp.unknown() // returns "unknown" to exclude the record from the index
            )
        );
    System.out.println(filterExp.getBase64());
    // Prints: lHuTEJMEk1ECo2FnZRKVfwEAkxYNk1EDp2NvdW50cnmSfpOqA0F1c3RyYWxpYacDQ2FuYWRhqQNCb3Rzd2FuYZNRAqNhZ2WRAA==

    All the client examples above print similar Base64-encoded expression strings to the console.

  2. Create the expression index.

    Use the asadm command-line tool to create a numeric secondary index on the expression. Copy the full Base64 string from the previous step’s output and use it in the command below.

    Terminal window
    asadm -e "enable; manage sindex create numeric cust_index ns test set cust_data exp_base64 lHuTEJMEk1ECo2FnZRKVfwEAkxYNk1EDp2NvdW50cnmSfpOqA0F1c3RyYWxpYacDQ2FuYWRhqQNCb3Rzd2FuYZNRAqNhZ2WRAA=="

  3. Insert some test data.

    // Define the namespace and set for the records
    final String NAMESPACE = "test";
    final String SET = "cust_data";
    

    // A helper method to insert a customer record
    public void insert(int key, String name, int age, String country) {
        client.put(null,
                new Key(NAMESPACE, SET, key),
                new Bin("name", name),
                new Bin("age", age),
                new Bin("country", country));
    }
    

    // Insert sample customers to demonstrate which records get indexed
    public void insertData() {
        insert(1, "Tim", 312, "Australia");
        insert(2, "Bob", 47, "Canada");
        insert(3, "Jo", 15, "USA"); // not indexed
        insert(4, "Steven", 23, "Botswana");
        insert(5, "Susan", 32, "Canada");
        insert(6, "Jess", 17, "Botswana"); // not indexed
        insert(7, "Sam", 18, "USA"); // not indexed
        insert(8, "Alex", 47, "Canada");
        insert(9, "Pam", 56, "Australia");
        insert(10, "Vivek", 12, "India"); // not indexed
        insert(11, "Kiril", 22, "Sweden"); // not indexed
        insert(12, "Bill", 23, "UK"); // not indexed
    }

  4. Validate index entries.

    You should see 6 entries in the expression index (records 1, 2, 4, 5, 8, 9).

    Terminal window
    # Confirm only matching records (6) were indexed
    asinfo -v 'sindex-stat:namespace=test;indexname=cust_index' -l
    

    entries=6
    ...

  5. Query your Expression Index.

    Run a query to filter for ages 5 and above. Notice the results still only shows ages 18 and above.

    // Query via the expression index to fetch records for customers that are 5 and older
    Statement stmt = new Statement();
    stmt.setNamespace("test");
    stmt.setSetName("cust_data");
    // Use `rangeByIndex` to query the expression index
    stmt.setFilter(Filter.rangeByIndex("cust_index", 5, Integer.MAX_VALUE));
    

    // Execute the query and print the results
    try (RecordSet recordSet = client.query(null, stmt)) {
        while (recordSet.next()) {
            System.out.println(recordSet.getRecord());
        }
    }

    Since we stored age, you can filter for records above 25 by simply modifying the query:

    // Query via the expression index to fetch records for customers that are 25 and older
    Statement stmt = new Statement();
    stmt.setNamespace("test");
    stmt.setSetName("cust_data");
    // Update the range to start at 25
    stmt.setFilter(Filter.rangeByIndex("cust_index", 25, Integer.MAX_VALUE));
    

    try (RecordSet recordSet = client.query(null, stmt)) {
        while (recordSet.next()) {
            System.out.println(recordSet.getRecord());
        }
    }

  6. That’s it. You’re done!

    Have questions or feedback? You can submit them or schedule a call with the product team using this form.

Feedback

Was this page helpful?

What type of feedback are you giving?

What would you like us to know?

+Capture screenshot

Can we reach out to you?