From 659a45d3a8c6e38f179ee3a85b0125985a18e18f Mon Sep 17 00:00:00 2001 From: Simran Brucherseifer Date: Mon, 25 Jul 2016 18:40:08 +0200 Subject: [PATCH] Documentation improvements --- Documentation/Books/AQL/Examples/README.mdpp | 124 +++++++++--------- Documentation/Books/AQL/Functions/Array.mdpp | 41 +++--- .../Books/AQL/Functions/Document.mdpp | 8 +- Documentation/Books/AQL/Functions/README.mdpp | 8 +- Documentation/Books/AQL/Functions/String.mdpp | 4 +- .../Books/AQL/Operations/Filter.mdpp | 59 +++++---- Documentation/Books/AQL/Operations/Limit.mdpp | 18 ++- Documentation/Books/AQL/Operators.mdpp | 4 +- Documentation/Books/HTTP/Document/README.mdpp | 11 +- Documentation/Books/HTTP/General/README.mdpp | 2 +- 10 files changed, 148 insertions(+), 131 deletions(-) diff --git a/Documentation/Books/AQL/Examples/README.mdpp b/Documentation/Books/AQL/Examples/README.mdpp index e08402b8bc..ea38ee6b69 100644 --- a/Documentation/Books/AQL/Examples/README.mdpp +++ b/Documentation/Books/AQL/Examples/README.mdpp @@ -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" } ] ``` diff --git a/Documentation/Books/AQL/Functions/Array.mdpp b/Documentation/Books/AQL/Functions/Array.mdpp index 34aa8dc5ad..14275c329c 100644 --- a/Documentation/Books/AQL/Functions/Array.mdpp +++ b/Documentation/Books/AQL/Functions/Array.mdpp @@ -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 diff --git a/Documentation/Books/AQL/Functions/Document.mdpp b/Documentation/Books/AQL/Functions/Document.mdpp index 26f99da37e..25325a6c17 100644 --- a/Documentation/Books/AQL/Functions/Document.mdpp +++ b/Documentation/Books/AQL/Functions/Document.mdpp @@ -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) diff --git a/Documentation/Books/AQL/Functions/README.mdpp b/Documentation/Books/AQL/Functions/README.mdpp index 8015115b0f..be23e65d66 100644 --- a/Documentation/Books/AQL/Functions/README.mdpp +++ b/Documentation/Books/AQL/Functions/README.mdpp @@ -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 diff --git a/Documentation/Books/AQL/Functions/String.mdpp b/Documentation/Books/AQL/Functions/String.mdpp index 82f0b75f63..42168f5553 100644 --- a/Documentation/Books/AQL/Functions/String.mdpp +++ b/Documentation/Books/AQL/Functions/String.mdpp @@ -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. diff --git a/Documentation/Books/AQL/Operations/Filter.mdpp b/Documentation/Books/AQL/Operations/Filter.mdpp index 16b73deb5d..7ff455f865 100644 --- a/Documentation/Books/AQL/Operations/Filter.mdpp +++ b/Documentation/Books/AQL/Operations/Filter.mdpp @@ -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 diff --git a/Documentation/Books/AQL/Operations/Limit.mdpp b/Documentation/Books/AQL/Operations/Limit.mdpp index 9c0032181b..8cfa97f331 100644 --- a/Documentation/Books/AQL/Operations/Limit.mdpp +++ b/Documentation/Books/AQL/Operations/Limit.mdpp @@ -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. + \ No newline at end of file diff --git a/Documentation/Books/AQL/Operators.mdpp b/Documentation/Books/AQL/Operators.mdpp index 9be204cc75..7087390389 100644 --- a/Documentation/Books/AQL/Operators.mdpp +++ b/Documentation/Books/AQL/Operators.mdpp @@ -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: diff --git a/Documentation/Books/HTTP/Document/README.mdpp b/Documentation/Books/HTTP/Document/README.mdpp index 487cb8fd00..f9cae34ba1 100644 --- a/Documentation/Books/HTTP/Document/README.mdpp +++ b/Documentation/Books/HTTP/Document/README.mdpp @@ -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) diff --git a/Documentation/Books/HTTP/General/README.mdpp b/Documentation/Books/HTTP/General/README.mdpp index 92bf8bbf04..08c7482ae4 100644 --- a/Documentation/Books/HTTP/General/README.mdpp +++ b/Documentation/Books/HTTP/General/README.mdpp @@ -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.