Apply a UDF

Jump to the Code block for a combined complete example.

UDFs that execute on a single record are Record UDFs. The record may or may not exist in the database, and the UDF may create, read, and/or update a record.

Setup

The following examples will use the setup below to illustrate applying a record UDF.

import com.aerospike.client.AerospikeClient;
import com.aerospike.client.Key;
import com.aerospike.client.Record;
import com.aerospike.client.Value;
import com.aerospike.client.BatchRecord;
import com.aerospike.client.BatchResults;
import com.aerospike.client.ResultCode;
import com.aerospike.client.exp.Exp;
import com.aerospike.client.policy.WritePolicy;
import com.aerospike.client.query.Statement;
import com.aerospike.client.task.ExecuteTask;

// Establishes a connection to the server
AerospikeClient client = new AerospikeClient("127.0.0.1", 3000);

The record structure:

Occurred: Integer
Reported: Integer
Posted: Integer
Report: Map
{
    shape: List,
    summary: String,
    city: String,
    state: String,
    duration: String
}
Location: GeoJSON

Single record commands

Single argument

This example uses the setRecent function in the module example.lua. See Manage UDFs for example.lua code and information on registering the UDF.

This compares the posted bin to a supplied value and writes true/false to a recent bin based on the result.

// Creates a key with the namespace "sandbox", set "ufodata", and user key 5000
Key key = new Key("sandbox", "ufodata", 5000);

// Execute the UDF
Object result = client.execute(
    null, key, "example", "setRecent", Value.get(20210101)
);

// View the updated record
Record record = client.get(null, key);
System.out.format("Record: %s", record.bins);

// Close the connection to the server
client.close();

Multiple argument

This example uses the getDaysBetween function in the module example.lua. See Manage UDFs for example.lua code and information on registering the UDF.

This compares two dates, provided by passing the bin names with the date values, and returns the days between. The following example returns the days between the sighting occurrence and posting to the site.

// Creates a key with the namespace "sandbox", set "ufodata", and user key 5000
Key key = new Key("sandbox", "ufodata", 5000);

// Execute the UDF
Object result = client.execute(
    null, key, "example", "getDaysBetween", Value.get("occurred"), Value.get("posted")
);

// Do something
System.out.format("%s days between occurrence and post", result);

// Close the connection to the server
client.close();

Batch operation with a UDF

Note

Server version 6.0.0 and above is required for batch UDF operations

Batch UDF execution has no cross-record atomicity: each record’s UDF call succeeds or fails independently, so a batch can complete with some records updated and others not. Check batchRecord.resultCode or record.getUDFError() rather than only record != null to detect a per-record failure.

This example uses the multi-argument example from above, and apply it to a batch of records.

// Create batch of keys
Key[] keys = new Key[10];
for (int i = 0; i < 10; i++) {
    keys[i] = new Key("sandbox", "ufodata", (i + 100));
}

// Execute the UDF
BatchResults batchResult = client.execute(
    null, null, keys, "example", "getDaysBetween", Value.get("occurred"), Value.get("posted")
);

// Access the results
for (BatchRecord batchRecord : batchResult.records){
    // A non-null batchRecord.record does not by itself mean the UDF call succeeded -
    // check resultCode, since a per-record UDF failure still returns a record
    // containing a "FAILURE" bin.
    if (batchRecord.resultCode == ResultCode.OK) {
        // Do something
        System.out.format("%s days between occurrence and post\n", batchRecord.record.getUDFResult());
    } else if (batchRecord.record != null) {
        System.out.format("UDF failed for key %s: %s\n", batchRecord.key.userKey, batchRecord.record.getUDFError());
    }
}
// Close the connection to the server
client.close();

Background query with a UDF

This example will use the single argument example from above, and apply it to all records that match a Filter Expression through a background query.

Each matching record is processed independently: if the background query is interrupted, some records may have already been updated and others not.

// Create the policy
WritePolicy writePolicy = new WritePolicy();
// Build the expression
writePolicy.filterExp = Exp.build(
    Exp.binExists("posted")
);

// Create statement
Statement stmt = new Statement();

// Set namespace and set name
stmt.setNamespace("sandbox");
stmt.setSetName("ufodata");

ExecuteTask task = client.execute(
    writePolicy, stmt, "example", "setRecent", Value.get(20210101)
);

// Return the query status
int status = task.queryStatus();

String queryStatus;
switch (status){
    case 0: queryStatus = "not found";
            break;
    case 1: queryStatus = "in progress";
            break;
    case 2: queryStatus = "complete";
            break;
    default: queryStatus = "unknown";
            break;
}
System.out.format("Query %s.", queryStatus);

// Close the connection to the server
client.close();

Code block

Expand this section for a single code block to apply a record UDF

import com.aerospike.client.AerospikeClient;
import com.aerospike.client.Key;
import com.aerospike.client.Record;
import com.aerospike.client.Value;
import com.aerospike.client.BatchRecord;
import com.aerospike.client.BatchResults;
import com.aerospike.client.exp.Exp;
import com.aerospike.client.policy.WritePolicy;
import com.aerospike.client.task.ExecuteTask;

// Establishes a connection to the server
AerospikeClient client = new AerospikeClient("127.0.0.1", 3000);

// Creates a key with the namespace "sandbox", set "ufodata", and user key 5000
Key key = new Key("sandbox", "ufodata", 5000);

// Execute the UDF
Object result = client.execute(
    null, key, "example", "getDaysBetween", Value.get("occurred"), Value.get("posted")
);

// Do something
System.out.format("%s days between occurrence and post", result);

// Close the connection to the server
client.close();