HTTP Interface for AQL User Functions Management

AQL User Functions Management

This is an introduction to ArangoDB's HTTP interface for managing AQL user functions. 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 how AQL user functions and their implications, please refer to the Extending AQL chapter.

The HTTP interface provides an API for adding, deleting, and listing previously registered AQL user functions.

All user functions managed through this interface will be stored in the system collection _aqlfunctions. Documents in this collection should not be accessed directly, but only via the dedicated interfaces.

Create AQL user function

create a new AQL user function

POST /_api/aqlfunction

A JSON object with these properties is required:

  • isDeterministic: 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.
  • code: a string representation of the function body.
  • name: the fully qualified name of the user functions.

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.

HTTP 200 A json document with these Properties is returned:

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

  • code: the HTTP status code
  • isNewlyCreated: boolean flag to indicate whether the function was newly created (false in this case)
  • error: boolean flag to indicate whether an error occurred (false in this case)

HTTP 201 A json document with these Properties is returned:

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

  • code: the HTTP status code
  • isNewlyCreated: boolean flag to indicate whether the function was newly created (true in this case)
  • error: boolean flag to indicate whether an error occurred (false in this case)

HTTP 400 A json document with these Properties is returned:

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

  • errorMessage: a descriptive error message
  • errorNum: the server error number
  • code: the HTTP status code
  • error: boolean flag to indicate whether an error occurred (true in this case)

Return Codes

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

Response Body

  • code: the HTTP status code
  • isNewlyCreated: boolean flag to indicate whether the function was newly created (false in this case)
  • error: boolean flag to indicate whether an error occurred (false in this case)

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

Response Body

  • code: the HTTP status code
  • isNewlyCreated: boolean flag to indicate whether the function was newly created (true in this case)
  • error: boolean flag to indicate whether an error occurred (false in this case)

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

Response Body

  • errorMessage: a descriptive error message
  • code: the HTTP status code
  • errorNum: the server error number
  • error: boolean flag to indicate whether an error occurred (true in this case)

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 Created
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Remove existing AQL user function

remove an existing AQL user function

DELETE /_api/aqlfunction/{name}

Path Parameters

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

Query Parameters

  • group (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.

Removes an existing AQL user function or function group, identified by name.

HTTP 200 A json document with these Properties is returned:

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

  • deletedCount: The number of deleted user functions, always 1 when group is set to false. Any number >= 0 when group is set to true
  • code: the HTTP status code
  • error: boolean flag to indicate whether an error occurred (false in this case)

HTTP 400 A json document with these Properties is returned:

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

  • errorMessage: a descriptive error message
  • errorNum: the server error number
  • code: the HTTP status code
  • error: boolean flag to indicate whether an error occurred (true in this case)

HTTP 404 A json document with these Properties is returned:

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

  • errorMessage: a descriptive error message
  • errorNum: the server error number
  • code: the HTTP status code
  • error: boolean flag to indicate whether an error occurred (true in this case)

Return Codes

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

Response Body

  • deletedCount: The number of deleted user functions, always 1 when group is set to false. Any number >= 0 when group is set to true
  • code: the HTTP status code
  • error: boolean flag to indicate whether an error occurred (false in this case)

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

Response Body

  • errorMessage: a descriptive error message
  • code: the HTTP status code
  • errorNum: the server error number
  • error: boolean flag to indicate whether an error occurred (true in this case)

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

Response Body

  • errorMessage: a descriptive error message
  • code: the HTTP status code
  • errorNum: the server error number
  • error: boolean flag to indicate whether an error occurred (true in this case)

Examples

deletes a function:

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
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 Not Found
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body

Return registered AQL user functions

gets all reqistered AQL user functions

GET /_api/aqlfunction

Query Parameters

  • namespace (optional): Returns all registered AQL user functions from namespace namespace under result.

Returns all registered AQL user functions.

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

HTTP 200 A json document with these Properties is returned:

on success HTTP 200 is returned.

  • code: the HTTP status code
  • result: All functions, or the ones matching the namespace parameter
    • isDeterministic: 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.
    • code: A string representation of the function body
    • name: The fully qualified name of the user function
  • error: boolean flag to indicate whether an error occurred (false in this case)

HTTP 400 A json document with these Properties is returned:

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

  • errorMessage: a descriptive error message
  • errorNum: the server error number
  • code: the HTTP status code
  • error: boolean flag to indicate whether an error occurred (true in this case)

Return Codes

  • 200: on success HTTP 200 is returned.

Response Body

  • code: the HTTP status code
  • result: All functions, or the ones matching the namespace parameter
    • isDeterministic: 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.
    • code: A string representation of the function body
    • name: The fully qualified name of the user function
  • error: boolean flag to indicate whether an error occurred (false in this case)

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

Response Body

  • errorMessage: a descriptive error message
  • code: the HTTP status code
  • errorNum: the server error number
  • error: boolean flag to indicate whether an error occurred (true in this case)

Examples

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

HTTP/1.1 OK
content-type: application/json; charset=utf-8
x-content-type-options: nosniff

Show response body