Skip to main content

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 that execute in the Aerospike server process. 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
record["recent"] = false

-- 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}
d1 = getDate(record[date1])
d2 = getDate(record[date2])
days = os.difftime(d1, d2) / (24 * 60 * 60)
return math.floor(days)

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

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

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


The following examples will use the setup below to illustrate UDF registration in an Aerospike database.

Register with the server

The UDF Lua package will be registered on all server's in the cluster. /home/user/udf/example.lua is location of the Lua package on the client's filesystem. 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 filesystem will be /opt/aerospike/usr/udf/lua/example.lua.

Using the client

The registration is asynchronous on the server. The server will immediately return an acknowledgement of the registration command and then register 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.

Using asadm

A UDF may also be registered through 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'

Registering the Lua package only needs to happen once.

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. There may be a need to manually clear this cache with the udf-clear-cache command.

The UDF cache will automatically be cleared when a UDF file is updated. That said, there are conditions that requires manual clearing of the cache:

  • If there exist interdependencies among the updated UDF. This could lead to an invalid cache and requires a clearing of the cache.
  • If the UDF is in use while being updated. This could also lead to an invalid cache and requires a clearing of the cache.

Follow the registration example above to register the updated UDF.

Using the client

Clear the UDF cache with the Aerospike Client.

Using asadm

Clear the UDF cache with the following asadm command.

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

Remove a udf

UDFs that are no longer used can be removed from the server through the Aerospike Client or asadm.

Using the client

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

Using asadm

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

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

Code block

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