mirror of https://gitee.com/bigwinds/arangodb
287 lines
8.7 KiB
Plaintext
287 lines
8.7 KiB
Plaintext
!CHAPTER Miscellaneous functions
|
|
|
|
!SECTION Control flow functions
|
|
|
|
!SUBSECTION NOT_NULL()
|
|
|
|
`NOT_NULL(alternative, ...) → value`
|
|
|
|
Return the first alternative that is not *null*, and *null* if all alternatives
|
|
are *null* themselves.
|
|
|
|
- **alternative** (any, *repeatable*): input of arbitrary type
|
|
- returns **value** (any):
|
|
|
|
!SUBSECTION 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
|
|
|
|
!SUBSECTION 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
|
|
|
|
!SUBSECTION Ternary operator
|
|
|
|
For conditional evaluation, check out the
|
|
[ternary operator](../Operators.md#ternary-operator).
|
|
|
|
!SECTION Database functions
|
|
|
|
!SUBSECTION COLLECTION_COUNT()
|
|
|
|
`COLLECTION_COUNT(coll) → count`
|
|
|
|
Determine the amount of documents in a collection. [LENGTH()](#length)
|
|
is preferred.
|
|
|
|
!SUBSECTION COLLECTIONS()
|
|
|
|
`COLLECTIONS() → docArray`
|
|
|
|
Return an array of collections.
|
|
|
|
- returns **docArray** (array): each collection as a document with attributes
|
|
*name* and *_id* in an array
|
|
|
|
!SUBSECTION COUNT()
|
|
|
|
This is an alias for [LENGTH()](#length).
|
|
|
|
!SUBSECTION 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
|
|
|
|
!SUBSECTION 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" ] )
|
|
```
|
|
|
|
!SUBSECTION LENGTH()
|
|
|
|
`LENGTH(coll) → documentCount`
|
|
|
|
Determine the amount of documents in a collection.
|
|
|
|
It calls [COLLECTION_COUNT()](#collectioncount) 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](Array.md#length) in an array,
|
|
the [number of attribute keys](Document.md#length) of an object / document and
|
|
the [character length](String.md#length) of a string.
|
|
|
|
!SECTION 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.
|
|
|
|
!SECTION Function calling
|
|
|
|
!SUBSECTION 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"
|
|
```
|
|
|
|
!SUBSECTION 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"
|
|
```
|
|
|
|
!SECTION 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.
|
|
|
|
!SUBSECTION 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
|
|
```
|
|
|
|
!SUBSECTION 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*
|
|
|
|
```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( RAND() ) // C++ implementation
|
|
V8( RAND() ) // JavaScript implementation
|
|
```
|
|
|
|
!SUBSECTION 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
|
|
|
|
!SUBSECTION 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
|
|
```
|
|
|
|
!SUBSECTION 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*
|
|
|
|
```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) // const assignment
|
|
FOR i IN 1..3 RETURN NOOPT(V8(1 + 1)) // v8 expression
|
|
```
|