Expressions

Jump to the Code block for a combined complete example.

Aerospike Expressions is a strongly typed, functional, domain-specific language designed for manipulating and comparing bins and record metadata. This page explores expression usage within single record commands.

For expression usage within multi-record requests see the Batch Operations and Queries pages.

Setup

The following examples will use the setup and record structure below to illustrate the use of expressions in single record commands.

import (
    "fmt"
    "github.com/aerospike/aerospike-client-go/v6"
)

// Establishes a connection to the server
client, err := aerospike.NewClient("127.0.0.1", 3000)
if err != nil {
    log.Fatal(err)
}
defer client.Close()

// Creates a key with the namespace "sandbox", set "ufodata", and user key 5001
key, err := aerospike.NewKey("sandbox", "ufodata", 5001)
if err != nil {
    log.Fatal(err)
}

The record structure:

+------+----------+----------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+
| PK   | occurred | reported | posted   | report                                                                                                                                                                                                                 | location                                                   |
+------+----------+----------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+
| 5001 | 20220531 | 20220601 | 20220601 | MAP('{"shape":["circle", "flash", "disc"], "summary":"Large flying disc flashed in the sky above the student union. Craziest thing I've ever seen!", "city":"Ann Arbor", "state":"Michigan", "duration":"5 minutes"}') | GeoJSON('{"type":"Point","coordinates":[42.2808,83.743]}') |
+------+----------+----------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+------------------------------------------------------------+

Filter Expressions

Introduced in Aerospike Database 5.2, Filter Expressions are commonly used to select records that satisfy a boolean expression and work with all single record commands (reads, writes, operations, and record UDFs), batch reads, and queries. Filters are only executed when a record exists, not executing when a record is created or not found.

Note

When a filter evaluates to false on the server, a record is filtered out from the operation, and the Java and C# clients by default return null. The failOnFilteredOut policy can be set to true to receive an exception instead of a null return value.

Refer to the client specific API reference for more information on how FILTERED_OUT is handled.

Read

When using a Filter Expression on a read command, the expression is defined within the read policy.

The following example creates a filter expression that checks the length of the shape list in the report map and only returns if there are more than two shapes.

// Create the policy
policy := aerospike.NewPolicy()
// Build the expression
policy.FilterExpression = aerospike.ExpGreater(
    aerospike.ExpListSize(
        aerospike.ExpMapGetByKey(aerospike.MapReturnType.VALUE, aerospike.ExpTypeLIST, aerospike.ExpStringVal("shape"), aerospike.ExpMapBin("report"))),
    aerospike.ExpIntVal(2))

// Read the record
record, err := client.Get(policy, key)
if err != nil {
    log.Fatal(err)
}

// Do something
fmt.Printf("Record: %v", record.Bins)

Write

When using a Filter Expression on a write command, the expression is defined within the write policy.

The following example creates a filter expression that checks if occurred is later than 20211231 and posted exists. If the filter returns true, a recent key with the value true will be added to the report map.

// Create the policy
writePolicy := aerospike.NewWritePolicy(0,0)
// Build the expression
writePolicy.FilterExpression = aerospike.ExpAnd(
    aerospike.ExpGreater(aerospike.ExpIntBin("occurred"), aerospike.ExpIntVal(20211231)),
    aerospike.ExpBinExists("posted"))

// Update the record
_, err = client.Operate(writePolicy, key, aerospike.MapPutOp(aerospike.DefaultMapPolicy(), "report", aerospike.NewValue("recent"), aerospike.NewValue(true)))
if err != nil {
    log.Fatal(err)
}

Operation Expressions

Introduced in Aerospike Database 5.6, Operation Expressions are bin operations that atomically compute a value from information within the record or provided by the expression. The result is either returned to the client, in a read expression, or written to a specified bin, in a write expression.

A Filter Expression can be defined in the write policy of the operate method to determine the execution of a Bin Operation using an Operation Expression.

Read

The read expression operation computes an expression, and returns that value. A defined name in the operation can be used as the synthetic bin name when retrieving results.

The folowing example takes the Read Filter Expression example from above and changes the scenario slightly. This command computes the length of the shape list in the report map and returns the value in a synthetic bin called numShapes.

// Build the expression
exp := aerospike.ExpListSize(
    aerospike.ExpMapGetByKey(aerospike.MapReturnType.VALUE, aerospike.ExpTypeLIST, aerospike.ExpStringVal("shape"), aerospike.ExpMapBin("report")))

// Read the record
record, err := client.Operate(nil, key, aerospike.ExpReadOp("numShapes", exp, aerospike.ExpReadFlagDefault))
if err != nil {
    log.Fatal(err)
}

// Do something
fmt.Printf("Record: %v", record.Bins)

Write

An operation that computes an expression and writes that value to a bin.

The folowing example takes the Write Filter Expression example from above and changes the scenario slightly. Using the same criteria to compute a recent value, reported bin value and posted bin exists, this command updates the report map with the recent value, true or false.

// Build the expression
exp := aerospike.ExpMapPut(aerospike.DefaultMapPolicy(), aerospike.ExpStringVal("recent"),
        aerospike.ExpAnd(
            aerospike.ExpGreater(aerospike.ExpIntBin("occurred"), aerospike.ExpIntVal(20211231)),
            aerospike.ExpBinExists("posted")),
        aerospike.ExpMapBin("report"))

// Update the record
_, err = client.Operate(nil, key, aerospike.ExpWriteOp("report", exp, aerospike.ExpWriteFlagDefault))
if err != nil {
    log.Fatal(err)
}

Code block

Expand this section for a single code block to create a Operation Expression

import (
    "fmt"
    "github.com/aerospike/aerospike-client-go/v6"
)

func main() {
    // Establishes a connection to the server
    client, err := aerospike.NewClient("127.0.0.1", 3000)
    if err != nil {
        log.Fatal(err)
    }
    defer client.Close()

    // Creates a key with the namespace "sandbox", set "ufodata", and user key 5001
    key, err := aerospike.NewKey("sandbox", "ufodata", 5001)
    if err != nil {
        log.Fatal(err)
    }

    // Build the expression
    exp := aerospike.ExpMapPut(aerospike.DefaultMapPolicy(), aerospike.ExpStringVal("recent"),
            aerospike.ExpAnd(
                aerospike.ExpGreater(aerospike.ExpIntBin("occurred"), aerospike.ExpIntVal(20211231)),
                aerospike.ExpBinExists("posted")),
            aerospike.ExpMapBin("report"))

    // Update the record
    _, err = client.Operate(nil, key, aerospike.ExpWriteOp("report", exp, aerospike.ExpWriteFlagDefault))
    if err != nil {
        log.Fatal(err)
    }
}