HTTP interface for user-defined AQL functions

The HTTP API for user-defined functions (UDFs) lets you add, delete, and list registered AQL extensions

AQL user functions are a means to extend the functionality of ArangoDB’s query language (AQL) with user-defined JavaScript code.

For an overview of over AQL user functions and their implications, please refer to Extending AQL.

All user functions managed through this interface are stored in the _aqlfunctions system collection. You should not modify the documents in this collection directly, but only via the dedicated interfaces.

Create a user-defined AQL function

POST /_api/aqlfunction

Registers a user-defined function (UDF) written in JavaScript for the use in AQL queries in the current database.

In case of success, HTTP 200 is returned. If the function isn’t valid etc. HTTP 400 including a detailed error message will be returned.

Request Body

  • name (string, required): the fully qualified name of the user functions.

  • code (string, required): a string representation of the function body.

  • isDeterministic (boolean, optional): an optional boolean value to indicate whether the function results are fully deterministic (function return value solely depends on the input value and return value is the same for repeated calls with same input). The isDeterministic attribute is currently not used but may be used later for optimizations.

Responses

HTTP 200: If the function already existed and was replaced by the call, the server will respond with HTTP 200.

  • error (boolean): boolean flag to indicate whether an error occurred (false in this case)

  • code (integer): the HTTP status code

  • isNewlyCreated (boolean): boolean flag to indicate whether the function was newly created (false in this case)

HTTP 201: If the function can be registered by the server, the server will respond with HTTP 201.

  • error (boolean): boolean flag to indicate whether an error occurred (false in this case)

  • code (integer): the HTTP status code

  • isNewlyCreated (boolean): boolean flag to indicate whether the function was newly created (true in this case)

HTTP 400: If the JSON representation is malformed or mandatory data is missing from the request, the server will respond with HTTP 400.

  • error (boolean): boolean flag to indicate whether an error occurred (true in this case)

  • code (integer): the HTTP status code

  • errorNum (integer): the server error number

  • errorMessage (string): a descriptive error message

Examples

shell> curl -X POST --header 'accept: application/json' --data-binary @- --dump - http://localhost:8529/_api/aqlfunction <<EOF
{ 
  "name" : "myfunctions::temperature::celsiustofahrenheit", 
  "code" : "function (celsius) { return celsius * 1.8 + 32; }", 
  "isDeterministic" : true 
}
EOF

HTTP/1.1 201 Created
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 48
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

Remove a user-defined AQL function

DELETE /_api/aqlfunction/{name}

Deletes an existing user-defined function (UDF) or function group identified by name from the current database.

Path Parameters

  • name (string, required): the name of the AQL user function.

Query Parameters

  • group (string, optional):
    • true: The function name provided in name is treated as a namespace prefix, and all functions in the specified namespace will be deleted. The returned number of deleted functions may become 0 if none matches the string.
    • false: The function name provided in name must be fully qualified, including any namespaces. If none matches the name, HTTP 404 is returned.

Responses

HTTP 200: If the function can be removed by the server, the server will respond with HTTP 200.

  • error (boolean): boolean flag to indicate whether an error occurred (false in this case)

  • code (integer): the HTTP status code

  • deletedCount (integer): The number of deleted user functions, always 1 when group is set to false. Any number >= 0 when group is set to true.

HTTP 400: If the user function name is malformed, the server will respond with HTTP 400.

  • error (boolean): boolean flag to indicate whether an error occurred (true in this case)

  • code (integer): the HTTP status code

  • errorNum (integer): the server error number

  • errorMessage (string): a descriptive error message

HTTP 404: If the specified user function does not exist, the server will respond with HTTP 404.

  • error (boolean): boolean flag to indicate whether an error occurred (true in this case)

  • code (integer): the HTTP status code

  • errorNum (integer): the server error number

  • errorMessage (string): a descriptive error message

Examples

deletes a function:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/square::x::y

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 43
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

function not found:

shell> curl -X DELETE --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/myfunction::x::y

HTTP/1.1 404 Not Found
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 114
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body

List the registered user-defined AQL functions

GET /_api/aqlfunction

Returns all registered user-defined functions (UDFs) for the use in AQL of the current database.

The call returns a JSON array with status codes and all user functions found under result.

Query Parameters

  • namespace (string, optional): Returns all registered AQL user functions from the specified namespace.

Responses

HTTP 200: on success HTTP 200 is returned.

  • error (boolean): boolean flag to indicate whether an error occurred (false in this case)

  • code (integer): the HTTP status code

  • result (array): All functions, or the ones matching the namespace parameter

    • name (string): The fully qualified name of the user function

    • code (string): A string representation of the function body

    • isDeterministic (boolean): an optional boolean value to indicate whether the function results are fully deterministic (function return value solely depends on the input value and return value is the same for repeated calls with same input). The isDeterministic attribute is currently not used but may be used later for optimizations.

HTTP 400: If the user function name is malformed, the server will respond with HTTP 400.

  • error (boolean): boolean flag to indicate whether an error occurred (true in this case)

  • code (integer): the HTTP status code

  • errorNum (integer): the server error number

  • errorMessage (string): a descriptive error message

Examples

shell> curl --header 'accept: application/json' --dump - http://localhost:8529/_api/aqlfunction/test

HTTP/1.1 200 OK
content-type: application/json
cache-control: no-cache, no-store, must-revalidate, pre-check=0, post-check=0, max-age=0, s-maxage=0
connection: Keep-Alive
content-length: 38
content-security-policy: frame-ancestors 'self'; form-action 'self';
expires: 0
pragma: no-cache
server: ArangoDB
strict-transport-security: max-age=31536000 ; includeSubDomains
x-arango-queue-time-seconds: 0.000000
x-content-type-options: nosniff
Show response body
❮  AQL query results cache

© ArangoDB - Graph and Beyond