Manage UDFs

Jump to the Code block for a combined complete example.

The Aerospike Client can be used to register User-Defined Functions (UDFs). UDFs are written in the Lua programming language. These functions can be grouped together into Lua packages and registered with the Aerospike server cluster.

Click to view the example Lua package.

-- Compare 'posted' bin value with provided value and update/create recent bin
function setRecent(record, value)
    if (record["posted"] >= value) then
        record["recent"] = true
    else
        record["recent"] = false
    end
    aerospike:update(record)
end

-- Get number of days between two dates
function getDaysBetween(record, date1, date2)
    function getDate(date)
        year = math.floor(date/10000)
        month = math.floor((date - (year * 10000))/100)
        day = math.floor(date - (year * 10000) - (month * 100))
        return os.time{year=year, month=month, day=day}
    end
    d1 = getDate(record[date1])
    d2 = getDate(record[date2])
    days = os.difftime(d1, d2) / (24 * 60 * 60)
    return math.floor(days)
end

-- Aggregation function to count records
local function one(rec)
    return 1
end

local function add(a, b)
    return a + b
end

function count(stream)
    return stream : map(one) : reduce(add);
end

Setup

The following code blocks provide examples of UDF registration in an Aerospike database.

using Aerospike.Client;
using System;
using System.Collections;

// Define host configuration
Host config = new Host("127.0.0.1", 3000);
// Establishes a connection to the server
AerospikeClient client = new AerospikeClient(null, config);

Register with the server

The UDF Lua package is registered on all servers in the cluster. The location on the client’s filesystem is /home/user/udf/example.lua example.lua is the filename of the Lua package relative to each server’s configured mod-lua user-path in aerospike.conf.

mod-lua {
    user-path /opt/aerospike/usr/udf/lua
}

In this configuration, the Lua package’s full path on each server’s file system is /opt/aerospike/usr/udf/lua/example.lua.

Using the client

The registration is asynchronous on the server. The server immediately returns an acknowledgement of the registration command and registers the UDF with other servers in the cluster. The client has the option of waiting for the registration task to complete using the returned RegisterTask instance.

// Register the UDF
RegisterTask task = client.Register(null, "/home/user/udf/example.lua", "example.lua", Language.LUA);

// Wait for the task to complete
task.Wait();

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

Using asadm

A UDF may also be registered through the Aerospike Admin tool (asadm). The following example uses asadm to register the same example.lua file.

asadm -e 'enable; manage udfs add example.lua path /home/user/udf/example.lua'

Remove a UDF

You can remove obsolete UDFs from the server through the Aerospike Client or with the asadm tool.

Using the client

The following example removes a UDF from the server with the Aerospike Client.

// Remove a UDF
client.RemoveUdf("example.lua");

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

Using `asadm`

The following example removes a UDF from the server with asadm:

asadm -e 'enable; manage udfs remove example.lua '

Update a registered UDF

UDF files are cached on the server to improve performance. This prevents the server from reopening and recompiling the UDF unnecessarily.

UDFs cannot be updated in-place. To update a UDF:

Remove the existing UDF
Re-add the updated UDF

You may need to manually clear the UDF cache with the udf-clear-cache command.

The UDF cache is automatically cleared when a UDF file is updated. However, under some conditions, the cache must be cleared manually beforehand:

Interdependencies related to the updated UDF could cause an invalid cache, and require clearing the cache.
If the UDF is in use while being updated, the cache may become invalid and require clearing, as well.

Follow the registration example above to register the updated UDF.

Using the client

Clear the UDF cache with the Aerospike Client.

// Using an info command
String response = Info.Request("127.0.0.1", 3000, "udf-clear-cache:");

Console.WriteLine(response);

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

Using `asadm`

Clear the UDF cache with the following asadm command.

asadm -e "enable; asinfo -v 'udf-clear-cache:'"

Code block

Expand this section for a single code block to register a UDF

using Aerospike.Client;
using System;
using System.Collections;

// Define host configuration
Host config = new Host("127.0.0.1", 3000);
// Establishes a connection to the server
AerospikeClient client = new AerospikeClient(null, config);

// Register the UDF
RegisterTask task = client.Register(null, "/home/user/udf/example.lua", "example.lua", Language.LUA);

// Wait for the task to complete
task.Wait();

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