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