arangodb/Documentation/Books/AQL/functions-miscellaneous.md

---
layout: default
description: Miscellaneous functions
---
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** (array\|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](operators.html#ternary-operator).

Database functions
------------------

### CHECK_DOCUMENT()

<small>Introduced in: v3.3.22, v3.4.2</small>

`CHECK_DOCUMENT(document) → checkResult`

Returns *true* if *document* is a valid document object, i.e. a document
without any duplicate attribute names. Will return *false* for any
non-objects/non-documents or documents with duplicate attribute names.

{% hint 'warning' %}
This is an internal function for validating database objects and
is not supposed to be useful for anything else.
{% endhint %}

The primary use case for this function is to apply it on all
documents in a given collection as follows:

```js
FOR doc IN collection
  FILTER !CHECK_DOCUMENT(doc)
  RETURN JSON_STRINGIFY(doc)
```

This query will return all documents in the given collection with redundant
attribute names and export them. This output can be used for subsequent
cleanup operations.

{% hint 'info' %}
When using object literals in AQL, there will be an automatic 
removal/cleanup of duplicate attribute names, so the function will be effective
only for **already stored** database documents. Therefore,
`RETURN CHECK_DOCUMENT( { a: 1, a: 2 } )` is expected to return `true`.
{% endhint %}

- **document** (object): an arbitrary document / object
- returns **checkResult** (bool): *true* for any valid objects/documents without
  duplicate attribute names, and *false* for any non-objects/non-documents or 
  objects/documents with duplicate attribute names

### COLLECTION_COUNT()

`COLLECTION_COUNT(coll) → count`

Determine the amount of documents in a collection. [LENGTH()](#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()](#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

### DECODE_REV()

`DECODE_REV(revision) → details`

Decompose the specified `revision` string into its components.
The resulting object has a `date` and a `count` attribute.
This function is supposed to be called with the `_rev` attribute value
of a database document as argument.

- **revision** (string): revision ID string
- returns **details** (object\|null): object with two attributes
  *date* (string in ISO 8601 format) and *count* (integer number),
  or *null*

If the input revision ID is not a string or cannot be processed, the function
issues a warning and returns *null*.

Please note that the result structure may change in future versions of
ArangoDB in case the internal format of revision strings is modified. Please 
also note that the *date* value in the current result provides the date and
time of when the document record was put together on the server, but not
necessarily the time of insertion into the underlying storage engine. Therefore
in case of concurrent document operations the exact document storage order 
cannot be derived unambiguously from the revision value. It should thus be
treated as a rough estimate of when a document was created or last updated.

```js
DECODE_REV( "_YU0HOEG---" )
// { "date" : "2019-03-11T16:15:05.314Z", "count" : 0 }
```

### 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

```js
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

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

Please also consider to use
[`DOCUMENT` in conjunction with `WITH`](operations-with.html)

### LENGTH()

`LENGTH(coll) → documentCount`

Determine the amount of documents in a collection.

It calls [COLLECTION_COUNT()](#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](functions-array.html#length) in an array,
the [number of attribute keys](functions-document.html#length) of an object / document and
the [character length](functions-string.html#length) of a string.

Hash functions
--------------

### HASH()

`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 equal 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.

### String-based hashing

See the following string functions:

- [CRC32()](functions-string.html#crc32)
- [FNV64()](functions-string.html#fnv64)
- [MD5()](functions-string.html#md5)
- [SHA1()](functions-string.html#sha1)
- [SHA512()](functions-string.html#sha512)

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

```js
APPLY( "SUBSTRING", [ "this is a test", 0, 7 ] )
// "this is"
```

### ASSERT() / WARN()

`ASSERT(expr, message) → retVal`<br>
`WARN(expr, message) → retVal`

The two functions evaluate an expression. In case the expression evaluates to
*true* both functions will return *true*. If the expression evaluates to
*false* *ASSERT* will throw an error and *WARN* will issue a warning and return
*false*. This behavior allows the use of *ASSERT* and *WARN* in `FILTER`
conditions.

- **expr** (expression): AQL expression to be evaluated
- **message** (string): message that will be used in exception or warning if expression evaluates to false
- returns **retVal** (bool): returns true if expression evaluates to true

```js
FOR i IN 1..3 FILTER ASSERT(i > 0, "i is not greater 0") RETURN i
FOR i IN 1..3 FILTER WARN(i < 2, "i is not smaller 2") RETURN i
```

### 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

```js
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

```js
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(value) → retVal`

No-operation that prevents certain query compile-time and run-time optimizations. 
Constant expressions can be forced to be evaluated at runtime with this.
This function is marked as non-deterministic so its argument withstands
query optimization. There is no need to call this function explicitly, it is 
mainly used for internal testing.

- **value** (any): a value of arbitrary type
- returns **retVal** (any): *value*

```js
// 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( 123 ) // evaluates 123 at runtime
NOOPT( CONCAT("a", "b") ) // evaluates concatenation at runtime
```

### PASSTHRU()

`PASSTHRU(value) → retVal`

Simply returns its call argument unmodified. There is no need to call this function 
explicitly, it is mainly used for internal testing.

- **value** (any): a value of arbitrary type
- returns **retVal** (any): *value*

### 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

```js
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. There is
no need to call this function explicitly, it is mainly used for internal
testing.

- **expression** (any): arbitrary expression
- returns **retVal** (any): the return value of the *expression*

```js
// differences in execution plan (explain)
FOR i IN 1..3 RETURN (1 + 1)          // const assignment
FOR i IN 1..3 RETURN V8(1 + 1)        // simple expression
```

### VERSION()

`VERSION() → serverVersion`

Returns the server version as a string. In a cluster, returns the version
of the coordinator.

- returns **serverVersion** (string): the server version string

```js
RETURN VERSION()        // e.g. "3.4.0" 
```