UDF Development With AQL

Summary

Learn how AQL can be used in the UDF development process. Aql is useful for registering, listing, describing, and removing UDFs from the Aerospike server. Aql can also be used to run UDFs.

For a guide on writing UDFs see the UDF Developer Guide.

Registering a Module

The following is the command to register a UDF Module:

REGISTER MODULE '<filepath>'

This command uploads the file at the given path <filepath>. The name of the file will be the module's name.

The following is an example of uploading a UDF module at ~/tmp/my_udf.lua

aql> register module '~/tmp/my_udf.lua'

When you register a module, the module is automatically copied to all nodes in the cluster. If you can run the module from one cluster node but not another, verify the following:

• The cluster is healthy
• The user that runs Aerospike also owns owns /opt/aerospike/smd/*

Running UDFs

Once you register a UDF module you can use the UDFs it contains with the following command formats.

EXECUTE <module>.<function>(<args>) ON <ns>[.<set>]
EXECUTE <module>.<function>(<args>) ON <ns>[.<set>] WHERE PK = <key>
EXECUTE <module>.<function>(<args>) ON <ns>[.<set>] WHERE <bin> = <value>
EXECUTE <module>.<function>(<args>) ON <ns>[.<set>] WHERE <bin> BETWEEN <lower> AND <upper>'

Where

• module is the UDF module containing the function to invoke.
• function is the UDF to invoke.
• args is a comma-separated list of argument values for the UDF.
• ns is the namespace for the records to be queried.
• set is the set name for the record to be queried.
• key is the record's primary key.
• bin is the name of a bin.
• value is the value of a bin.
• lower is the lower bound for a numeric range query.
• upper is the lower bound for a numeric range query.

The following is an example of invoking the UDF "udf1" from the module "myudfs.lua". The "udf1" function will return the value of bin "bar" on the record in namespace "test", set "demo" with the primary key "key1".

aql> select * from test.demo
+--------+-----+--------+------+
| PK     | foo | bar    | baz  |
+--------+-----+--------+------+
| "key1" | 123 | "abc"  | true |
| "key2" | 24  |        |      |
| "key3" | 123 | "abcd" | true |
+--------+-----+--------+------+
3 rows in set (0.012 secs)

aql> EXECUTE myudfs.udf1('bar') ON test.demo WHERE PK = "key1"
+-------+
| udf1  |
+-------+
| "abc" |
+-------+

UDFs can also be used as streams with aggregation queries. See Aggregations.

Listing Modules

The following is the command to list all registered modules:

SHOW MODULES

The following is an example of a listing:

aql> show modules
+---------------------------+-------+------------------------+
| module                    | type  | hash                   |
+---------------------------+-------+------------------------+
| "example1.lua"            | "lua" | "033671e05067888fce09" |
| "example2.lua"            | "lua" | "07b42082cca8e73a96b2" |
+---------------------------+-------+------------------------+
2 rows in set (0.000 secs)

The module information includes the module name and type (currently, only Lua is supported) and the hash value of the file. Most users will not find the hash value useful, but some may use it to verify the version or instance of a UDF on the server.

Describe a Module

The following is the command to describe a registered module:

DESC MODULE <module>

This will describe the UDF module named <module>.

The describe command shows the UDF. In the gen field (basically, a hash value), the module type (Lua) and the text of the entire UDF in the content field. The output is most legible in raw format ('set output raw').

The following is an example:

aql> set output raw
OUTPUT = RAW
aql> desc module example2.lua
*************************** 1. row ***************************
content: "
local function bin(name)
    local function x(rec)
        return rec[name]
    end
    return x
end

local function even(a)
    return a % 2 == 0
end

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

local function multiplier(factor)
    local function x(a)
        return a * factor
    end
    return x
end

function foo(rec)
    return bin("a")(rec)
end

function a(stream)
    return stream : map(bin("a"))
end

function even_a(stream)
    return stream : map(bin("a")) : filter(even)
end

function sum_even_a(stream)
    return stream : map(bin("a")) : filter(even) : reduce(add)
end

function sum_even_a_x(stream, factor)
    return stream : map(bin("a")) : filter(even) : reduce(add) : map(multiplier(factor))
end"
gen: "13fgxKWlQDHukDDp0/fsrjxvcMA="
type: "LUA"

[127.0.0.1:3000] 1 row in set (0.011 secs)

Dropping a Module

The following is the command to drop (remove) a registered module from the cluster:

REMOVE MODULE <module>

This will drop (remove) the UDF module named <module>.

The following is an example:

aql> remove module example2.lua