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
    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 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'
note

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