Extending AQL with User Functions
AQL comes with a built-in set of functions, but it is not a fully-featured programming language.
In order to avoid conflicts with existing or future built-in function names, all user defined functions (UDF) have to be put into separate namespaces. Invoking a UDF is then possible by referring to the fully-qualified function name, which includes the namespace, too; see Conventions.
UDFs can have serious effects on the performance of your queries and the resource usage in ArangoDB. Especially in cluster setups they should not be used against much data, because this data will need to be sent over the network back and forth between DB-Servers and Coordinators, potentially adding a lot of latency. This can be mitigated by very selective
FILTERs before calls to UDFs.
Since the optimizer doesn’t know anything about the nature of your function,
the optimizer can’t use indexes for UDFs. So you should never lean on a UDF
as the primary criterion for a
FILTER statement to reduce your query result set.
Instead, put a another
FILTER statement in front of it. You should make sure
FILTER statement is effective
to reduce the query result before passing it to your UDF.
Rule of thumb is, the closer the UDF is to your final
(or maybe even inside it), the better.
When used in clusters, UDFs are always executed on a
engine is available on DB-Servers. Queries that would push UDF execution to
DB-Servers are aborted with a parse error. This includes using UDFs in traversal
PRUNE conditions, as well as
FILTER conditions that can be moved into the
traversal execution on a DB-Server. These limitations also apply to the
single server deployment mode to keep the differences to cluster deployments minimal.
Internally, UDFs are stored in a system collection named
of the selected database. When an AQL statement refers to such a UDF,
it is loaded from that collection. The UDFs will be exclusively
available for queries in that particular database.
Since the Coordinator doesn’t have own local collections, the
collection is sharded across the cluster. Therefore (as usual), it has to be
accessed through a Coordinator - you mustn’t talk to the shards directly.
Once it is in the
_aqlfunctions collection, it is available on all
Coordinators without additional effort.
Keep in mind that system collections are excluded from dumps created with arangodump by default. To include AQL UDF in a dump, the dump needs to be started with the option --include-system-collections true.