Miscellaneous functions

Control flow functions

NOT_NULL()

NOT_NULL(alternative, ...) → value

Return the first element that is not null, and null if all alternatives are null themselves. It is also known as COALESCE() in SQL.

  • alternative (any, repeatable): input of arbitrary type
  • returns value (any): first non-null parameter, or null if all arguments are null

FIRST_LIST()

Return the first alternative that is an array, and null if none of the alternatives is an array.

  • alternative (any, repeatable): input of arbitrary type
  • returns list (list|null): array / list or null

FIRST_DOCUMENT()

FIRST_DOCUMENT(value) → doc

Return the first alternative that is a document, and null if none of the alternatives is a document.

  • alternative (any, repeatable): input of arbitrary type
  • returns doc (object|null): document / object or null

Ternary operator

For conditional evaluation, check out the ternary operator.

Database functions

COLLECTION_COUNT()

COLLECTION_COUNT(coll) → count

Determine the amount of documents in a collection. LENGTH() is preferred.

COLLECTIONS()

COLLECTIONS() → docArray

Return an array of collections.

  • returns docArray (array): each collection as a document with attributes name and _id in an array

COUNT()

This is an alias for LENGTH().

CURRENT_USER()

CURRENT_USER() → userName

Return the name of the current user.

The current user is the user account name that was specified in the Authorization HTTP header of the request. It will only be populated if authentication on the server is turned on, and if the query was executed inside a request context. Otherwise, the return value of this function will be null.

  • returns userName (string|null): the current user name, or null if authentication is disabled

DOCUMENT()

DOCUMENT(collection, id) → doc

Return the document which is uniquely identified by its id. ArangoDB will try to find the document using the _id value of the document in the specified collection.

If there is a mismatch between the collection passed and the collection specified in id, then null will be returned. Additionally, if the collection matches the collection value specified in id but the document cannot be found, null will be returned.

This function also allows id to be an array of ids. In this case, the function will return an array of all documents that could be found.

It is also possible to specify a document key instead of an id, or an array of keys to return all documents that can be found.

  • collection (string): name of a collection
  • id (string|array): a document handle string (consisting of collection name and document key), a document key, or an array of both document handle strings and document keys
  • returns doc (document|array|null): the content of the found document, an array of all found documents or null if nothing was found
DOCUMENT( users, "users/john" )
DOCUMENT( users, "john" )

DOCUMENT( users, [ "users/john", "users/amy" ] )
DOCUMENT( users, [ "john", "amy" ] )

DOCUMENT(id) → doc

The function can also be used with a single parameter id as follows:

  • id (string|array): either a document handle string (consisting of collection name and document key) or an array of document handle strings
  • returns doc (document|null): the content of the found document or null if nothing was found
DOCUMENT("users/john")
DOCUMENT( [ "users/john", "users/amy" ] )

Please also consider to use DOCUMENT in conjunction with WITH

LENGTH()

LENGTH(coll) → documentCount

Determine the amount of documents in a collection.

It calls COLLECTION_COUNT() internally.

  • coll (collection): a collection (not string)
  • returns documentCount (number): the total amount of documents in coll

LENGTH() can also determine the number of elements in an array, the number of attribute keys of an object / document and the character length of a string.

Hash functions

HASH(value) → hashNumber

Calculate a hash value for value.

  • value (any): an element of arbitrary type
  • returns hashNumber (number): a hash value of value

value is not required to be a string, but can have any data type. The calculated hash value will take the data type of value into account, so for example the number 1 and the string "1" will have different hash values. For arrays the hash values will be creared if the arrays contain exactly the same values (including value types) in the same order. For objects the same hash values will be created if the objects have exactly the same attribute names and values (including value types). The order in which attributes appear inside objects is not important for hashing.

The hash value returned by this function is a number. The hash algorithm is not guaranteed to remain the same in future versions of ArangoDB. The hash values should therefore be used only for temporary calculations, e.g. to compare if two documents are the same, or for grouping values in queries.

Function calling

APPLY()

APPLY(functionName, arguments) → retVal

Dynamically call the function funcName with the arguments specified. Arguments are given as array and are passed as separate parameters to the called function.

Both built-in and user-defined functions can be called.

  • funcName (string): a function name
  • arguments (array, optional): an array with elements of arbitrary type
  • returns retVal (any): the return value of the called function
APPLY( "SUBSTRING", [ "this is a test", 0, 7 ] )
// "this is"

CALL()

CALL(funcName, arg1, arg2, ... argN) → retVal

Dynamically call the function funcName with the arguments specified. Arguments are given as multiple parameters and passed as separate parameters to the called function.

Both built-in and user-defined functions can be called.

  • funcName (string): a function name
  • args (any, repeatable): an arbitrary number of elements as multiple arguments, can be omitted
  • returns retVal (any): the return value of the called function
CALL( "SUBSTRING", "this is a test", 0, 4 )
// "this"

Internal functions

The following functions are used during development of ArangoDB as a database system, primarily for unit testing. They are not intended to be used by end users, especially not in production environments.

FAIL()

FAIL(reason)

Let a query fail on purpose. Can be used in a conditional branch, or to verify if lazy evaluation / short circuiting is used for instance.

  • reason (string): an error message
  • returns nothing, because the query is aborted
RETURN 1 == 1 ? "okay" : FAIL("error") // "okay"
RETURN 1 == 1 || FAIL("error") ? true : false // true
RETURN 1 == 2 && FAIL("error") ? true : false // false
RETURN 1 == 1 && FAIL("error") ? true : false // aborted with error

NOOPT()

NOOPT(expression) → retVal

No-operation that prevents query compile-time optimizations. Constant expressions can be forced to be evaluated at runtime with this.

If there is a C++ implementation as well as a JavaScript implementation of an AQL function, then it will enforce the use of the C++ version.

  • expression (any): arbitray expression
  • returns retVal (any): the return value of the expression
// differences in execution plan (explain)
FOR i IN 1..3 RETURN (1 + 1)      // const assignment
FOR i IN 1..3 RETURN NOOPT(1 + 1) // simple expression

NOOPT( RAND() ) // C++ implementation
V8( RAND() )    // JavaScript implementation

PASSTHRU()

PASSTHRU(value) → retVal

This function is marked as non-deterministic so its argument withstands query optimization.

  • value (any): a value of arbitrary type
  • returns retVal (any): value, without optimizations

SLEEP()

SLEEP(seconds) → null

Wait for a certain amount of time before continuing the query.

  • seconds (number): amount of time to wait
  • returns a null value
SLEEP(1)    // wait 1 second
SLEEP(0.02) // wait 20 milliseconds

V8()

V8(expression) → retVal

No-operation that enforces the usage of the V8 JavaScript engine. If there is a JavaScript implementation of an AQL function, for which there is also a C++ implementation, the JavaScript version will be used.

  • expression (any): arbitray expression
  • returns retVal (any): the return value of the expression
// differences in execution plan (explain)
FOR i IN 1..3 RETURN (1 + 1)          // const assignment
FOR i IN 1..3 RETURN V8(1 + 1)        // const assignment
FOR i IN 1..3 RETURN NOOPT(V8(1 + 1)) // v8 expression

© ArangoDB - the native multi-model NoSQL database