1
0
Fork 0

Documentation improvements

This commit is contained in:
Simran Brucherseifer 2016-07-25 18:40:08 +02:00
parent 0bcd75921f
commit 659a45d3a8
10 changed files with 148 additions and 131 deletions

View File

@ -36,76 +36,76 @@ for brevity as well.
Some of the following example queries are executed on a collection *users*
with the following initial data:
```js
```json
[
{ "id" : 100, "name" : "John", "age" : 37, "active" : true, "gender" : "m" },
{ "id" : 101, "name" : "Fred", "age" : 36, "active" : true, "gender" : "m" },
{ "id" : 102, "name" : "Jacob", "age" : 35, "active" : false, "gender" : "m" },
{ "id" : 103, "name" : "Ethan", "age" : 34, "active" : false, "gender" : "m" },
{ "id" : 104, "name" : "Michael", "age" : 33, "active" : true, "gender" : "m" },
{ "id" : 105, "name" : "Alexander", "age" : 32, "active" : true, "gender" : "m" },
{ "id" : 106, "name" : "Daniel", "age" : 31, "active" : true, "gender" : "m" },
{ "id" : 107, "name" : "Anthony", "age" : 30, "active" : true, "gender" : "m" },
{ "id" : 108, "name" : "Jim", "age" : 29, "active" : true, "gender" : "m" },
{ "id" : 109, "name" : "Diego", "age" : 28, "active" : true, "gender" : "m" },
{ "id" : 200, "name" : "Sophia", "age" : 37, "active" : true, "gender" : "f" },
{ "id" : 201, "name" : "Emma", "age" : 36, "active" : true, "gender" : "f" },
{ "id" : 202, "name" : "Olivia", "age" : 35, "active" : false, "gender" : "f" },
{ "id" : 203, "name" : "Madison", "age" : 34, "active" : true, "gender": "f" },
{ "id" : 204, "name" : "Chloe", "age" : 33, "active" : true, "gender" : "f" },
{ "id" : 205, "name" : "Eva", "age" : 32, "active" : false, "gender" : "f" },
{ "id" : 206, "name" : "Abigail", "age" : 31, "active" : true, "gender" : "f" },
{ "id" : 207, "name" : "Isabella", "age" : 30, "active" : true, "gender" : "f" },
{ "id" : 208, "name" : "Mary", "age" : 29, "active" : true, "gender" : "f" },
{ "id" : 209, "name" : "Mariah", "age" : 28, "active" : true, "gender" : "f" }
{ "id": 100, "name": "John", "age": 37, "active": true, "gender": "m" },
{ "id": 101, "name": "Fred", "age": 36, "active": true, "gender": "m" },
{ "id": 102, "name": "Jacob", "age": 35, "active": false, "gender": "m" },
{ "id": 103, "name": "Ethan", "age": 34, "active": false, "gender": "m" },
{ "id": 104, "name": "Michael", "age": 33, "active": true, "gender": "m" },
{ "id": 105, "name": "Alexander", "age": 32, "active": true, "gender": "m" },
{ "id": 106, "name": "Daniel", "age": 31, "active": true, "gender": "m" },
{ "id": 107, "name": "Anthony", "age": 30, "active": true, "gender": "m" },
{ "id": 108, "name": "Jim", "age": 29, "active": true, "gender": "m" },
{ "id": 109, "name": "Diego", "age": 28, "active": true, "gender": "m" },
{ "id": 200, "name": "Sophia", "age": 37, "active": true, "gender": "f" },
{ "id": 201, "name": "Emma", "age": 36, "active": true, "gender": "f" },
{ "id": 202, "name": "Olivia", "age": 35, "active": false, "gender": "f" },
{ "id": 203, "name": "Madison", "age": 34, "active": true, "gender": "f" },
{ "id": 204, "name": "Chloe", "age": 33, "active": true, "gender": "f" },
{ "id": 205, "name": "Eva", "age": 32, "active": false, "gender": "f" },
{ "id": 206, "name": "Abigail", "age": 31, "active": true, "gender": "f" },
{ "id": 207, "name": "Isabella", "age": 30, "active": true, "gender": "f" },
{ "id": 208, "name": "Mary", "age": 29, "active": true, "gender": "f" },
{ "id": 209, "name": "Mariah", "age": 28, "active": true, "gender": "f" }
]
```
For some of the examples, we'll also use a collection *relations* to store
relationships between users. The example data for *relations* are as follows:
```js
```json
[
{ "from" : 209, "to" : 205, "type" : "friend" },
{ "from" : 206, "to" : 108, "type" : "friend" },
{ "from" : 202, "to" : 204, "type" : "friend" },
{ "from" : 200, "to" : 100, "type" : "friend" },
{ "from" : 205, "to" : 101, "type" : "friend" },
{ "from" : 209, "to" : 203, "type" : "friend" },
{ "from" : 200, "to" : 203, "type" : "friend" },
{ "from" : 100, "to" : 208, "type" : "friend" },
{ "from" : 101, "to" : 209, "type" : "friend" },
{ "from" : 206, "to" : 102, "type" : "friend" },
{ "from" : 104, "to" : 100, "type" : "friend" },
{ "from" : 104, "to" : 108, "type" : "friend" },
{ "from" : 108, "to" : 209, "type" : "friend" },
{ "from" : 206, "to" : 106, "type" : "friend" },
{ "from" : 204, "to" : 105, "type" : "friend" },
{ "from" : 208, "to" : 207, "type" : "friend" },
{ "from" : 102, "to" : 108, "type" : "friend" },
{ "from" : 207, "to" : 203, "type" : "friend" },
{ "from" : 203, "to" : 106, "type" : "friend" },
{ "from" : 202, "to" : 108, "type" : "friend" },
{ "from" : 201, "to" : 203, "type" : "friend" },
{ "from" : 105, "to" : 100, "type" : "friend" },
{ "from" : 100, "to" : 109, "type" : "friend" },
{ "from" : 207, "to" : 109, "type" : "friend" },
{ "from" : 103, "to" : 203, "type" : "friend" },
{ "from" : 208, "to" : 104, "type" : "friend" },
{ "from" : 105, "to" : 104, "type" : "friend" },
{ "from" : 103, "to" : 208, "type" : "friend" },
{ "from" : 203, "to" : 107, "type" : "boyfriend" },
{ "from" : 107, "to" : 203, "type" : "girlfriend" },
{ "from" : 208, "to" : 109, "type" : "boyfriend" },
{ "from" : 109, "to" : 208, "type" : "girlfriend" },
{ "from" : 106, "to" : 205, "type" : "girlfriend" },
{ "from" : 205, "to" : 106, "type" : "boyfriend" },
{ "from" : 103, "to" : 209, "type" : "girlfriend" },
{ "from" : 209, "to" : 103, "type" : "boyfriend" },
{ "from" : 201, "to" : 102, "type" : "boyfriend" },
{ "from" : 102, "to" : 201, "type" : "girlfriend" },
{ "from" : 206, "to" : 100, "type" : "boyfriend" },
{ "from" : 100, "to" : 206, "type" : "girlfriend" }
{ "from": 209, "to": 205, "type": "friend" },
{ "from": 206, "to": 108, "type": "friend" },
{ "from": 202, "to": 204, "type": "friend" },
{ "from": 200, "to": 100, "type": "friend" },
{ "from": 205, "to": 101, "type": "friend" },
{ "from": 209, "to": 203, "type": "friend" },
{ "from": 200, "to": 203, "type": "friend" },
{ "from": 100, "to": 208, "type": "friend" },
{ "from": 101, "to": 209, "type": "friend" },
{ "from": 206, "to": 102, "type": "friend" },
{ "from": 104, "to": 100, "type": "friend" },
{ "from": 104, "to": 108, "type": "friend" },
{ "from": 108, "to": 209, "type": "friend" },
{ "from": 206, "to": 106, "type": "friend" },
{ "from": 204, "to": 105, "type": "friend" },
{ "from": 208, "to": 207, "type": "friend" },
{ "from": 102, "to": 108, "type": "friend" },
{ "from": 207, "to": 203, "type": "friend" },
{ "from": 203, "to": 106, "type": "friend" },
{ "from": 202, "to": 108, "type": "friend" },
{ "from": 201, "to": 203, "type": "friend" },
{ "from": 105, "to": 100, "type": "friend" },
{ "from": 100, "to": 109, "type": "friend" },
{ "from": 207, "to": 109, "type": "friend" },
{ "from": 103, "to": 203, "type": "friend" },
{ "from": 208, "to": 104, "type": "friend" },
{ "from": 105, "to": 104, "type": "friend" },
{ "from": 103, "to": 208, "type": "friend" },
{ "from": 203, "to": 107, "type": "boyfriend" },
{ "from": 107, "to": 203, "type": "girlfriend" },
{ "from": 208, "to": 109, "type": "boyfriend" },
{ "from": 109, "to": 208, "type": "girlfriend" },
{ "from": 106, "to": 205, "type": "girlfriend" },
{ "from": 205, "to": 106, "type": "boyfriend" },
{ "from": 103, "to": 209, "type": "girlfriend" },
{ "from": 209, "to": 103, "type": "boyfriend" },
{ "from": 201, "to": 102, "type": "boyfriend" },
{ "from": 102, "to": 201, "type": "girlfriend" },
{ "from": 206, "to": 100, "type": "boyfriend" },
{ "from": 100, "to": 206, "type": "girlfriend" }
]
```

View File

@ -39,17 +39,6 @@ APPEND([ 1, 2, 3 ], [ 3, 4, 5, 2, 9 ], true)
This is an alias for [LENGTH()](#length).
!SUBSECTION OUTERSECTION()
`OUTERSECTION(array1, array2, ... arrayN) → newArray`
Return the values that occur only once across all arrays specified.
- **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
across all provided arrays. The element order is random.
!SUBSECTION FIRST()
`FIRST(anyArray) → firstElement`
@ -125,8 +114,8 @@ collection and the [character length](String.md#length) of a string.
Return the difference of all arrays specified.
- **arrays** (array, *repeatable*): an arbitrary of arrays as multiple arguments,
at least two
- **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,
but not in any of the subsequent arrays. The order of the result array is undefined
and should not be relied on. Duplicates will be removed.
@ -144,6 +133,28 @@ for positive positions, but does not support negative positions.
If *position* is negative or beyond the upper bound of the array,
then *null* will be returned.
```js
NTH( [ "foo", "bar", "baz" ], 2 ) // "baz"
NTH( [ "foo", "bar", "baz" ], 3 ) // null
NTH( [ "foo", "bar", "baz" ], -1 ) // null
```
!SUBSECTION OUTERSECTION()
`OUTERSECTION(array1, array2, ... arrayN) → newArray`
Return the values that occur only once across all arrays specified.
- **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
across all provided arrays. The element order is random.
```js
OUTERSECTION( [ 1, 2, 3 ], [ 2, 3, 4 ], [ 3, 4, 5 ] )
// [ 1, 5 ]
```
!SUBSECTION POP()
`POP(anyArray) → newArray`
@ -309,7 +320,7 @@ SLICE( [ 1, 2, 3, 4, 5 ], -3, 2 ) // [ 3, 4 ]
Return the union of all arrays specified.
- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
arguments, at least 2
arguments (at least 2)
- returns **newArray** (array): all array elements combined in a single array,
in any order
@ -342,7 +353,7 @@ UNIQUE(
Return the union of distinct values of all arrays specified.
- **arrays** (array, *repeatable*): an arbitrary number of arrays as multiple
arguments, at least 2
arguments (at least 2)
- returns **newArray** (array): the elements of all given arrays in a single
array, without duplicates, in any order

View File

@ -208,7 +208,7 @@ of the documents contained later in the argument list.
- **documents** (object, *repeatable*): an arbitrary number of documents as
multiple arguments, at least 2
multiple arguments (at least 2)
- returns **mergedDocument** (object): a combined document
Note that merging will only be done for top-level attributes. If you wish to
@ -273,7 +273,7 @@ If document attribute keys are ambiguous, the merged result will contain the val
of the documents contained later in the argument list.
- **documents** (object, *repeatable*): an arbitrary number of documents as
multiple arguments, at least 2
multiple arguments (at least 2)
- returns **mergedDocument** (object): a combined document
For example, two documents with distinct attribute names can easily be merged into one:
@ -346,7 +346,7 @@ All other attributes will be preserved.
- **document** (object): a document / object
- **attributeNames** (string, *repeatable*): an arbitrary number of attribute
names as multiple arguments, at least 1
names as multiple arguments (at least 1)
- returns **doc** (object): *document* without the specified attributes on the
top-level
@ -374,7 +374,7 @@ Recursively remove the attributes *attributeName1* to *attributeNameN* from
- **document** (object): a document / object
- **attributeNames** (string, *repeatable*): an arbitrary number of attribute
names as multiple arguments, at least 1
names as multiple arguments (at least 1)
- returns **doc** (object): *document* without the specified attributes on
all levels (top-level as well as nested objects)

View File

@ -27,11 +27,9 @@ i.e. *LENGTH(foo)* and *length(foo)* are equivalent.
!SUBSUBSECTION Extending AQL
Since ArangoDB 1.3, it is possible to extend AQL with user-defined functions.
These functions need to be written in JavaScript, and be registered before usage
in a query.
Please refer to [Extending AQL](../Extending/index.html) for more details on this.
It is possible to extend AQL with user-defined functions. These functions need to
be written in JavaScript, and be registered before usage in a query. Please refer
to [Extending AQL](../Extending/index.html) for more details on this.
By default, any function used in an AQL query will be sought in the built-in
function namespace *_aql*. This is the default namespace that contains all AQL

View File

@ -15,7 +15,7 @@ This is a synonym for [LENGTH()](#length).
Concatenate the values passed as *value1* to *valueN*.
- **values** (any, *repeatable*): elements of arbitrary type, at least one
- **values** (any, *repeatable*): elements of arbitrary type (at least 1)
- returns **str** (string): a concatenation of the elements. *null* values
are ignored.
@ -47,7 +47,7 @@ Concatenate the strings passed as arguments *value1* to *valueN* using the
- **separator** (string): an arbitrary separator string
- **values** (string|array, *repeatable*): strings or arrays of strings as multiple
arguments, at least one
arguments (at least 1)
- returns **joinedString** (string): a concatenated string of the elements, using
*separator* as separator string. *null* values are ignored. Array value arguments
are expanded automatically, and their individual members will be concatenated.

View File

@ -1,7 +1,9 @@
!CHAPTER FILTER
The *FILTER* statement can be used to restrict the results to elements that
match an arbitrary logical condition. The general syntax is:
match an arbitrary logical condition.
!SECTION General syntax
```
FILTER condition
@ -22,7 +24,7 @@ FOR u IN users
It is allowed to specify multiple *FILTER* statements in a query, even in
the same block. If multiple *FILTER* statements are used, their results will be
combined with a logical and, meaning all filter conditions must be true to
combined with a logical AND, meaning all filter conditions must be true to
include an element.
```
@ -32,29 +34,32 @@ FOR u IN users
RETURN u
```
In the above example, will be included in the result all array elements from *users* that have
an attribute *active* with value *true* and that have an attribute *age* with a
value less than *39* (including *null* ones). All other elements from *users*
will be skipped and not be included in the result produced by *RETURN*.
You may refer to the chapter [Accessing Data from Collections](../Fundamentals/DocumentData.md) for
a description of the impact of non-existent or null attributes.
In the above example, all array elements of *users* that have an attribute
*active* with value *true* and that have an attribute *age* with a value less
than *39* (including *null* ones) will be included in the result. All other
elements of *users* will be skipped and not be included in the result produced
by *RETURN*. You may refer to the chapter [Accessing Data from Collections](../Fundamentals/DocumentData.md)
for a description of the impact of non-existent or null attributes.
!SECTION Order of operations
Note that the positions of *FILTER* statements can influence the result of a query.
There are 16 active users in the test data for instance:
There are 16 active users in the [test data](../Examples/README.md#example-data)
for instance:
```js
FOR u IN users
FILTER u.active == true
RETURN u
FILTER u.active == true
RETURN u
```
We can limit the result set to 5 users at most:
```js
FOR u IN users
FILTER u.active == true
LIMIT 5
RETURN u
FILTER u.active == true
LIMIT 5
RETURN u
```
This may return the user documents of Jim, Diego, Anthony, Michael and Chloe for
@ -64,10 +69,10 @@ women...
```js
FOR u IN users
FILTER u.active == true
LIMIT 5
FILTER u.gender == "f"
RETURN u
FILTER u.active == true
LIMIT 5
FILTER u.gender == "f"
RETURN u
```
... it might just return the Chloe document, because the *LIMIT* is applied before
@ -78,11 +83,11 @@ by adding a *SORT* block:
```js
FOR u IN users
FILTER u.active == true
SORT u.age ASC
LIMIT 5
FILTER u.gender == "f"
RETURN u
FILTER u.active == true
SORT u.age ASC
LIMIT 5
FILTER u.gender == "f"
RETURN u
```
This will return the users Mariah and Mary. If sorted by age in *DESC* order,
@ -91,10 +96,10 @@ then the Sophia, Emma and Madison documents are returned. A *FILTER* after a
```js
FOR u IN users
FILTER u.active == true AND u.gender == "f"
SORT u.age ASC
LIMIT 5
RETURN u
FILTER u.active == true AND u.gender == "f"
SORT u.age ASC
LIMIT 5
RETURN u
```
The significance of where *FILTER* blocks are placed allows that this single

View File

@ -2,9 +2,9 @@
The *LIMIT* statement allows slicing the result array using an
offset and a count. It reduces the number of elements in the result to at most
the specified number. Two general forms of *LIMIT* are followed:
the specified number. Two general forms of *LIMIT* are followed:
```
```js
LIMIT count
LIMIT offset, count
```
@ -14,13 +14,23 @@ allows specifying both *offset* and *count*. The first form is identical using
the second form with an *offset* value of *0*.
The *offset* value specifies how many elements from the result shall be
discarded. It must be 0 or greater. The *count* value specifies how many
skipped. It must be 0 or greater. The *count* value specifies how many
elements should be at most included in the result.
```
```js
FOR u IN users
SORT u.firstName, u.lastName, u.id DESC
LIMIT 0, 5
RETURN u
```
Note that variables and expressions can not be used for *offset* and *count*.
Their values must be known at query compile time, which means that you can
use number literals and bind parameters only.
Where a *LIMIT* is used in relation to other operations in a query has meaning.
*LIMIT* operations before *FILTER*s in particular can change the result
significantly, because the operations are executed in the order in which they
are written in the query. See [FILTER](Filter.md#order-of-operations) for a
detailed example.

View File

@ -182,7 +182,6 @@ true && 23 // 23
Arithmetic operators perform an arithmetic operation on two numeric
operands. The result of an arithmetic operation is again a numeric value.
Operators are supported.
AQL supports the following arithmetic operators:
@ -236,7 +235,8 @@ applied by the [TO_NUMBER()](Functions/TypeCast.md#tonumber) function:
- objects / documents are converted to the number `0`.
An arithmetic operation that produces an invalid value, such as `1 / 0` (division by zero)
will also produce a result value of `null`.
will also produce a result value of `null`. The query is not aborted, but you may see a
warning.
Here are a few examples:

View File

@ -1,13 +1,6 @@
!CHAPTER HTTP Interface for Documents
In this chapter we describe the REST API of ArangoDB for documents.
We begin with a
- [section on the basic approach](AddressAndEtag.md)
before we proceed with
- [the detailed API description](WorkingWithDocuments.md),
which has all the gory details.
- [Basic approach](AddressAndEtag.md)
- [Detailed API description](WorkingWithDocuments.md)

View File

@ -76,7 +76,7 @@ response to the client instantly and thus finish this HTTP-request.
The server will execute the tasks from the queue asynchronously as fast
as possible, while clients can continue to do other work.
If the server queue is full (i.e. contains as many tasks as specified by the
option ["--scheduler.maximal-queue-size"](../../Manual/Administration/Configuration/Communication.html),
option ["--scheduler.maximal-queue-size"](../../Manual/Administration/Configuration/Communication.html)),
then the request will be rejected instantly with an *HTTP 500* (internal
server error) response.