Hawkin
/
arangodb
mirror of https://gitee.com/bigwinds/arangodb
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Doc - Add cross-refs & better AQL function descriptions (#8395)

This commit is contained in:
Simran 2019-03-13 14:28:06 +01:00 committed by GitHub
parent 02d170e4c2
commit 764bc55d05
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 225 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
Documentation/Books/AQL/Functions/Array.md
View File

@ -13,7 +13,7 @@ Apart from that, AQL also offers several language constructs:
optionally with inline filter, limit and projection,
- [array comparison operators](../Operators.md#array-comparison-operators) to compare
each element in an array to a value or the elements of another array,
- loop-based operations using [FOR](../Operations/For.md),
- loop-based operations on arrays using [FOR](../Operations/For.md),
[SORT](../Operations/Sort.md),
[LIMIT](../Operations/Limit.md),
as well as [COLLECT](../Operations/Collect.md) for grouping,
@ -26,8 +26,11 @@ Apart from that, AQL also offers several language constructs:
Add all elements of an array to another array. All values are added at the end of the
array (right side).
It can also be used to append a single element to an array. It is not necessary to wrap
it in an array (unless it is an array itself). You may also use [PUSH()](#push) instead.
- **anyArray** (array): array with elements of arbitrary type
- **values** (array): array, whose elements shall be added to *anyArray*
- **values** (array|any): array, whose elements shall be added to *anyArray*
- **unique** (bool, *optional*): if set to *true*, only those *values* will be added
that are not already contained in *anyArray*. The default is *false*.
- returns **newArray** (array): the modified array
@ -114,6 +117,8 @@ Turn an array of arrays into a flat array. All array elements in *array* will be
expanded in the result array. Non-array elements are added as they are. The function
will recurse into sub-arrays up to the specified depth. Duplicates will not be removed.
Also see [array contraction](../Advanced/ArrayOperators.md#array-contraction).
- **array** (array): array with elements of arbitrary type, including nested arrays
- **depth** (number, *optional*): flatten up to this many levels, the default is 1
- returns **flatArray** (array): a flattened array
@ -141,6 +146,10 @@ RETURN FLATTEN( [ 1, 2, [ 3, 4 ], 5, [ 6, 7 ], [ 8, [ 9, 10 ] ] ], 2 )
Return the intersection of all arrays specified. The result is an array of values that
occur in all arguments.
Other set operations are [UNION()](#union),
[MINUS()](#minus) and
[OUTERSECTION()](#outersection).
- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple arguments
(at least 2)
- returns **newArray** (array): a single array with only the elements, which exist in all
@ -239,6 +248,10 @@ RETURN LENGTH( {a:1, b:2, c:3, d:4, e:{f:5,g:6}} )
Return the difference of all arrays specified.
Other set operations are [UNION()](#union),
[INTERSECTION()](#intersection) and
[OUTERSECTION()](#outersection).
- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
arguments (at least 2)
- returns **newArray** (array): an array of values that occur in the first array,
@ -292,6 +305,10 @@ RETURN NTH( [ "foo", "bar", "baz" ], -1 )
Return the values that occur only once across all arrays specified.
Other set operations are [UNION()](#union),
[MINUS()](#minus) and
[INTERSECTION()](#intersection).
- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple arguments
(at least 2)
- returns **newArray** (array): a single array with only the elements that exist only once
@ -309,7 +326,11 @@ RETURN OUTERSECTION( [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ] )
`POP(anyArray) → newArray`
Remove the element at the end (right side) of *array*.
Remove the last element of *array*.
To append an element (right side), see [PUSH()](#push).<br>
To remove the first element, see [SHIFT()](#shift).<br>
To remove an element at an arbitrary position, see [REMOVE_NTH()](#removenth).
- **anyArray** (array): an array with elements of arbitrary type
- returns **newArray** (array): *anyArray* without the last element. If it's already
@ -364,7 +385,11 @@ RETURN POSITION( [2,4,6,8], 4, true )
`PUSH(anyArray, value, unique) → newArray`
Append *value* to the array specified by *anyArray*.
Append *value* to *anyArray* (right side).
To remove the last element, see [POP()](#pop).<br>
To prepend a value (left side), see [UNSHIFT()](#unshift).<br>
To append multiple elements, see [APPEND()](#append).
- **anyArray** (array): array with elements of arbitrary type
- **value** (any): an element of arbitrary type
@ -397,6 +422,9 @@ RETURN PUSH([ 1, 2, 2, 3 ], 2, true)
Remove the element at *position* from the *anyArray*.
To remove the first element, see [SHIFT()](#shift).<br>
To remove the last element, see [POP()](#pop).
- **anyArray** (array): array with elements of arbitrary type
- **position** (number): the position of the element to remove. Positions start
at 0. Negative positions are supported, with -1 being the last array element.
@ -484,7 +512,11 @@ RETURN REVERSE ( [2,4,6,8,10] )
`SHIFT(anyArray) → newArray`
Remove the element at the start (left side) of *anyArray*.
Remove the first element of *anyArray*.
To prepend an element (left side), see [UNSHIFT()](#unshift).<br>
To remove the last element, see [POP()](#pop).<br>
To remove an element at an arbitrary position, see [REMOVE_NTH()](#removenth).
- **anyArray** (array): array with elements with arbitrary type
- returns **newArray** (array): *anyArray* without the left-most element. If *anyArray*
@ -600,6 +632,10 @@ RETURN SORTED_UNIQUE( [ 8,4,2,10,6,2,8,6,4 ] )
Return the union of all arrays specified.
Other set operations are [MINUS()](#minus),
[INTERSECTION()](#intersection) and
[OUTERSECTION()](#outersection).
- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
arguments (at least 2)
- returns **newArray** (array): all array elements combined in a single array,
@ -676,7 +712,10 @@ RETURN UNIQUE( [ 1,2,2,3,3,3,4,4,4,4,5,5,5,5,5 ] )
`UNSHIFT(anyArray, value, unique) → newArray`
Prepend *value* to *anyArray*.
Prepend *value* to *anyArray* (left side).
To remove the first element, see [SHIFT()](#shift).<br>
To append a value (right side), see [PUSH()](#push).
- **anyArray** (array): array with elements of arbitrary type
- **value** (any): an element of arbitrary type

4
Documentation/Books/AQL/Functions/Document.md
View File

@ -134,6 +134,8 @@ KEEP()
Keep only the attributes *attributeName* to *attributeNameN* of *document*.
All other attributes will be removed from the result.
To do the opposite, see [UNSET()](#unset).
- **document** (object): a document / object
- **attributeNames** (string, *repeatable*): an arbitrary number of attribute
names as multiple arguments
@ -370,6 +372,8 @@ UNSET()
Remove the attributes *attributeName1* to *attributeNameN* from *document*.
All other attributes will be preserved.
To do the opposite, see [KEEP()](#keep).
- **document** (object): a document / object
- **attributeNames** (string, *repeatable*): an arbitrary number of attribute
names as multiple arguments (at least 1)

20
Documentation/Books/AQL/Functions/Miscellaneous.md
View File

@ -163,7 +163,8 @@ DOCUMENT("users/john")
DOCUMENT( [ "users/john", "users/amy" ] )
```
Please also consider [to use `DOCUMENT` in conjunction with `WITH`](../Operations/With.md)
Please also consider to use
[`DOCUMENT` in conjunction with `WITH`](../Operations/With.md)
### LENGTH()
@ -183,6 +184,8 @@ the [character length](String.md#length) of a string.
Hash functions
--------------
### HASH()
`HASH(value) → hashNumber`
Calculate a hash value for *value*.
@ -204,6 +207,14 @@ 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:
- [SHA1()](String.md#sha1)
- [SHA512()](String.md#sha512)
- [MD5()](String.md#md5)
Function calling
----------------
@ -228,15 +239,16 @@ APPLY( "SUBSTRING", [ "this is a test", 0, 7 ] )
### ASSERT() / WARN()
`ASSERT(expression, message) → retVal`
`ASSERT(expr, message) → retVal`<br>
`WARN(expr, message) → retVal`
The 2 functions evaluate an expression. In case the expression evaluates to
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.
- **expression** (AqlValue): AQL expression to be evaluated
- **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

10
Documentation/Books/AQL/Functions/Numeric.md
View File

@ -114,6 +114,9 @@ CEIL()
Return the integer closest but not less than *value*.
To round downward, see [FLOOR()](#floor).<br>
To round to the nearest integer value, see [ROUND()](#round).
- **value** (number): any number
- returns **roundedValue** (number): the value rounded to the ceiling
@ -196,8 +199,11 @@ FLOOR()
Return the integer closest but not greater than *value*.
To round upward, see [CEIL()](#ceil).<br>
To round to the nearest integer value, see [ROUND()](#round).
- **value** (number): any number
- returns **roundedValue** (number): the value rounded to the floor
- returns **roundedValue** (number): the value rounded downward
```js
FLOOR(2.49) // 2
@ -467,7 +473,7 @@ a combination of the [ternary operator](../Operators.md#ternary-operator),
and [FLOOR()](#floor):
```js
LET rounded = value >= 0 ? FLOOR(value) : CEIL(value)
value >= 0 ? FLOOR(value) : CEIL(value)
```
SIN()

52
Documentation/Books/AQL/Functions/String.md
View File

@ -210,13 +210,17 @@ JSON_STRINGIFY("[1, 2, 3]") // "[1,2,3]"
LEFT()
------
`LEFT(value, length) → substring`
`LEFT(value, n) → substring`
Return the *length* leftmost characters of the string *value*.
Return the *n* leftmost characters of the string *value*.
To return the rightmost characters, see [RIGHT()](#right).<br>
To take a part from an arbitrary position off the string,
see [SUBSTRING()](#substring).
- **value** (string): a string
- **length** (number): how many characters to return
- returns **substring** (string): at most *length* characters of *value*,
- **n** (number): how many characters to return
- returns **substring** (string): at most *n* characters of *value*,
starting on the left-hand side of the string
```js
@ -315,6 +319,9 @@ LTRIM()
Return the string *value* with whitespace stripped from the start only.
To strip from the end only, see [RTRIM()](#rtrim).<br>
To strip both sides, see [TRIM()](#trim).
- **value** (string): a string
- **chars** (string, *optional*): override the characters that should
be removed from the string. It defaults to `\r\n \t` (i.e. `0x0d`, `0x0a`,
@ -362,7 +369,7 @@ RANDOM_TOKEN(8) // "m9w50Ft9"
```
REGEX_MATCHES()
------------
---------------
`REGEX_MATCHES(text, regex, caseInsensitive) → stringArray`
@ -427,7 +434,7 @@ REGEX_MATCHES("john@doe.com", "^([a-z0-9_\.-]+)@([\da-z-]+)\.([a-z\.]{2,6})$", f
```
REGEX_SPLIT()
------------
-------------
`REGEX_SPLIT(text, splitExpression, caseInsensitive, limit) → stringArray`
@ -613,6 +620,10 @@ RIGHT()
Return the *length* rightmost characters of the string *value*.
To return the leftmost characters, see [LEFT()](#left).<br>
To take a part from an arbitrary position off the string,
see [SUBSTRING()](#substring).
- **value** (string): a string
- **length** (number): how many characters to return
- returns **substring** (string): at most *length* characters of *value*,
@ -630,6 +641,9 @@ RTRIM()
Return the string *value* with whitespace stripped from the end only.
To strip from the start only, see [LTRIM()](#ltrim).<br>
To strip both sides, see [TRIM()](#trim).
- **value** (string): a string
- **chars** (string, *optional*): override the characters that should
be removed from the string. It defaults to `\r\n \t` (i.e. `0x0d`, `0x0a`,
@ -795,6 +809,9 @@ SUBSTRING()
Return a substring of *value*.
To return the rightmost characters, see [RIGHT()](#right).<br>
To return the leftmost characters, see [LEFT()](#left).
- **value** (string): a string
- **offset** (number): start at *offset*, offsets start at position 0
- **length** (number, *optional*): at most *length* characters, omit to get the
@ -804,14 +821,16 @@ Return a substring of *value*.
TOKENS()
--------
`TOKENS(input, analyzer) → array`
`TOKENS(input, analyzer) → strArray`
Split the **input** string with the help of the specified **analyzer** into an array.
The resulting array can i.e. be used in subsequent `FILTER` statements with the **IN** operator.
This can be used to better understand how the specific analyzer is going to behave.
Split the *input* string with the help of the specified *analyzer* into a token array.
The resulting array can be used e.g. in subsequent `FILTER` statements with the *IN* operator.
It can help to better understand how the specific analyzer is going to behave.
- *input* string to tokenize
- *analyzer* one of the [available string analyzers](../../Manual/Views/ArangoSearch/Analyzers.html)
- **input** (string): text to tokenize
- **analyzer** (string): one of the available
[ArangoSearch string analyzers](../../Manual/Views/ArangoSearch/Analyzers.html)
- returns **strArray** (array): array of strings, each element being a token
TO_BASE64()
@ -848,10 +867,9 @@ however.
- **value** (string): a string
- **type** (number, *optional*): strip whitespace from the
- 0 – start and end of the string
- 1 – start of the string only
- 2 – end of the string only
The default is 0.
- `0` – start and end of the string (default)
- `1` – start of the string only
- `2` – end of the string only
`TRIM(value, chars) → strippedString`
@ -866,7 +884,7 @@ Return the string *value* with whitespace stripped from the start and end.
```js
TRIM("foo bar") // "foo bar"
TRIM(" foo bar ") // "foo bar"
TRIM("--==[foo-bar]==--", "-=[]") // "foo-bar"
TRIM("--==[foo-bar]==--", "-=[]") // "foo-bar"
TRIM(" foobar\t \r\n ") // "foobar"
TRIM(";foo;bar;baz, ", ",; ") // "foo;bar;baz"
```

137
Documentation/Books/AQL/Functions/TypeCast.md
View File

@ -1,5 +1,5 @@
Type cast
=========
Type check and cast functions
=============================
Some operators expect their operands to have a certain data type. For example,
logical operators expect their operands to be boolean values, and the arithmetic
@ -146,33 +146,128 @@ following type check functions are available. Each of these functions takes an
argument of any data type and returns true if the value has the type that is
checked for, and false otherwise.
The following type check functions are available:
### IS_NULL()
- `IS_NULL(value) → bool`: Check whether *value* is a *null* value, also see
[HAS()](Document.md#has)
`IS_NULL(value) → bool`
- `IS_BOOL(value) → bool`: Check whether *value* is a *boolean* value
Check whether *value* is *null*. Identical to `value == null`.
- `IS_NUMBER(value) → bool`: Check whether *value* is a *numeric* value
To test if an attribute exists, see [HAS()](Document.md#has) instead.
- `IS_STRING(value) → bool`: Check whether *value* is a *string* value
- **value** (any): value to test
- returns **bool** (boolean): *true* if *value* is `null`,
*false* otherwise
- `IS_ARRAY(value) → bool`: Check whether *value* is an *array* value
### IS_BOOL()
- `IS_LIST(value) → bool`: This is an alias for *IS_ARRAY()*
`IS_BOOL(value) → bool`
- `IS_OBJECT(value) → bool`: Check whether *value* is an *object* /
*document* value
Check whether *value* is a *boolean* value
- `IS_DOCUMENT(value) → bool`: This is an alias for *IS_OBJECT()*
- **value** (any): value to test
- returns **bool** (boolean): *true* if *value* is `true` or `false`,
*false* otherwise
- `IS_DATESTRING(value) → bool`: Check whether *value* is a string that can be used
in a date function. This includes partial dates such as *"2015"* or *"2015-10"* and
strings containing invalid dates such as *"2015-02-31"*. The function will return
false for all non-string values, even if some of them may be usable in date functions.
### IS_NUMBER()
- `IS_KEY(value) → bool`: Check whether *value* is a string that can be used as a
document key, i.e. as the value of the *_key* attribute.
`IS_NUMBER(value) → bool`
- `TYPENAME(value) → typeName`: Return the data type name of *value*. The data type
name can be either *"null"*, *"bool"*, *"number"*, *"string"*, *"array"* or *"object"*.
Check whether *value* is a number
- **value** (any): value to test
- returns **bool** (boolean): *true* if *value* is a number,
*false* otherwise
### IS_STRING()
`IS_STRING(value) → bool`
Check whether *value* is a string
- **value** (any): value to test
- returns **bool** (boolean): *true* if *value* is a string,
*false* otherwise
### IS_ARRAY()
`IS_ARRAY(value) → bool`
Check whether *value* is an array / list
- **value** (any): value to test
- returns **bool** (boolean): *true* if *value* is an array / list,
*false* otherwise
### IS_LIST()
`IS_LIST(value) → bool`
This is an alias for [IS_ARRAY()](#isarray)
### IS_OBJECT()
`IS_OBJECT(value) → bool`
Check whether *value* is an object / document
- **value** (any): value to test
- returns **bool** (boolean): *true* if *value* is an object / document,
*false* otherwise
### IS_DOCUMENT()
`IS_DOCUMENT(value) → bool`
This is an alias for [IS_OBJECT()](#isobject)
### IS_DATESTRING()
`IS_DATESTRING(str) → bool`
Check whether *value* is a string that can be used in a date function.
This includes partial dates such as *"2015"* or *"2015-10"* and strings
containing properly formatted but invalid dates such as *"2015-02-31"*.
- **str** (string): date string to test
- returns **bool** (boolean): *true* if *str* is a correctly formatted date string,
*false* otherwise including all non-string values, even if some of them may be usable
in date functions (numeric timestamps)
### IS_KEY()
`IS_KEY(str) → bool`
Check whether *value* is a string that can be used as a
document key, i.e. as the value of the *_key* attribute.
See [Naming Conventions for Document Keys](../../Manual/DataModeling/NamingConventions/DocumentKeys.html).
- **str** (string): document key to test
- returns **bool** (boolean): whether *str* can be used as document key
### TYPENAME()
`TYPENAME(value) → typeName`
Return the data type name of *value*.
- **value** (any): input of arbitrary type
- returns **typeName** (string): data type name of *value*
(`"null"`, `"bool"`, `"number"`, `"string"`, `"array"` or `"object"`)
Example Value | Data Type Name
---------------:|---------------
`null` | `"null"`
`true` | `"bool"`
`false` | `"bool"`
`123` | `"number"`
`-4.56` | `"number"`
`0` | `"number"`
`"foobar"` | `"string"`
`"123"` | `"string"`
`""` | `"string"`
`[ 1, 2, 3 ]` | `"array"`
`["foo",true]` | `"array"`
`[ ]` | `"array"`
`{"foo":"bar"}` | `"object"`
`{"foo": null}` | `"object"`
`{ }` | `"object"`

2
Documentation/Books/AQL/SUMMARY.md
View File

@ -45,7 +45,7 @@
* [Miscellaneous](Functions/Miscellaneous.md)
* [Numeric](Functions/Numeric.md)
* [String](Functions/String.md)
* [Type cast](Functions/TypeCast.md)
* [Type check & cast](Functions/TypeCast.md)
* [Graphs](Graphs/README.md)
* [Traversals explained](Graphs/TraversalsExplained.md)
* [Traversals](Graphs/Traversals.md)