From 64da8757e27bc7fa8f6ac30d11aad235e4d88e65 Mon Sep 17 00:00:00 2001 From: Simran Brucherseifer Date: Mon, 18 Jul 2016 11:26:59 +0200 Subject: [PATCH] Documentation improvements --- Documentation/Books/AQL/Functions/String.mdpp | 8 +- .../Books/AQL/Graphs/Traversals.mdpp | 16 +-- .../AQL/Invocation/WithWebInterface.mdpp | 6 +- Documentation/Books/AQL/Operators.mdpp | 97 +++++++++++-------- .../Documents/DocumentMethods.mdpp | 37 ++++--- .../DataModeling/GraphsVerticesEdges.mdpp | 2 +- .../DocuBlocks/WalLogfileThrottling.md | 10 +- .../DocuBlocks/collectionByExample.md | 29 ++++-- .../DocuBlocks/collectionByExampleSkiplist.md | 31 ++++-- 9 files changed, 140 insertions(+), 96 deletions(-) diff --git a/Documentation/Books/AQL/Functions/String.mdpp b/Documentation/Books/AQL/Functions/String.mdpp index 99e342460e..82f0b75f63 100644 --- a/Documentation/Books/AQL/Functions/String.mdpp +++ b/Documentation/Books/AQL/Functions/String.mdpp @@ -185,7 +185,8 @@ using wildcard matching. - **text** (string): the string to search in - **search** (string): a search pattern that can contain the wildcard characters `%` (meaning any sequence of characters, including none) and `_` (any single - character). Literal *%* and *:* must be escaped with two backslashes. + character). Literal *%* and *:* must be escaped with two backslashes (four + in arangosh). *search* cannot be a variable or a document attribute. The actual value must be present at query parse time already. - **caseInsensitive** (bool, *optional*): if set to *true*, the matching will be @@ -306,8 +307,9 @@ characters and sequences: Note that the characters `.`, `*`, `?`, `[`, `]`, `(`, `)`, `{`, `}`, `^`, and `$` have a special meaning in regular expressions and may need to be -escaped using a backslash (`\\`). A literal backslash should also be escaped -using another backslash, i.e. `\\\\`. +escaped using a backslash, which requires escaping itself (`\\`). A literal +backslash needs to be escaped using another escaped backslash, i.e. `\\\\`. +In arangosh, the amount of backslashes needs to be doubled. Characters and sequences may optionally be repeated using the following quantifiers: diff --git a/Documentation/Books/AQL/Graphs/Traversals.mdpp b/Documentation/Books/AQL/Graphs/Traversals.mdpp index 705120baf0..2d54d0dd3a 100644 --- a/Documentation/Books/AQL/Graphs/Traversals.mdpp +++ b/Documentation/Books/AQL/Graphs/Traversals.mdpp @@ -122,28 +122,28 @@ FOR vertex[, edge[, path]] - `OPTIONS` **options** (object, *optional*): used to modify the execution of the traversal. Only the following attributes have an effect, all others are ignored: - **uniqueVertices** (string): optionally ensure vertex uniqueness - - "path" → it is guaranteed that there is no path returned with a duplicate vertex - - "global" → it is guaranteed that each vertex is visited at most once during + - "path" – it is guaranteed that there is no path returned with a duplicate vertex + - "global" – it is guaranteed that each vertex is visited at most once during the traversal, no matter how many paths lead from the start vertex to this one. If you start with a `min depth > 1` a vertex that was found before *min* depth might not be returned at all (it still might be part of a path). **Note:** Using this configuration the result is not deterministic any more. If there are multiple paths from *startVertex* to *vertex*, one of those is picked. - - "none" (default) → no uniqueness check is applied on vertices + - "none" (default) – no uniqueness check is applied on vertices - **uniqueEdges** (string): optionally ensure edge uniqueness - - "path" → it is guaranteed that there is no path returned with a duplicate edge - - "global" → it is guaranteed that each edge is visited at most once during + - "path" – it is guaranteed that there is no path returned with a duplicate edge + - "global" – it is guaranteed that each edge is visited at most once during the traversal, no matter how many paths lead from the start vertex to this edge. If you start with a `min depth > 1`, an edge that was found before *min* depth might not be returned at all (it still might be part of a path). **Note:** Using this configuration the result is not deterministic any more. If there are multiple paths from *startVertex* over *edge* one of those is picked. - - "none" (default) → no uniqueness check is applied on edges. **Note:** + - "none" (default) – no uniqueness check is applied on edges. **Note:** Using this configuration the traversal will follow cycles in edges. - **bfs** (bool): optionally use the alternative breadth-first traversal algorithm - - true → the traversal will be executed breadth-first. The results will first + - true – the traversal will be executed breadth-first. The results will first contain all vertices at depth 1. Than all vertices at depth 2 and so on. - - false (default) → the traversal will be executed depth-first. It will first + - false (default) – the traversal will be executed depth-first. It will first return all paths from *min* depth to *max* depth for one vertex at depth 1. Than for the next vertex at depth 1 and so on. diff --git a/Documentation/Books/AQL/Invocation/WithWebInterface.mdpp b/Documentation/Books/AQL/Invocation/WithWebInterface.mdpp index df4b212d17..8edefc4c68 100644 --- a/Documentation/Books/AQL/Invocation/WithWebInterface.mdpp +++ b/Documentation/Books/AQL/Invocation/WithWebInterface.mdpp @@ -18,9 +18,9 @@ application code. Here is an example: ```js -FOR doc IN @@collection -FILTER CONTAINS(LOWER(doc.author), @search, false) -RETURN { "name": doc.name, "descr": doc.description, "author": doc.author } +FOR doc IN @@collection + FILTER CONTAINS(LOWER(doc.author), @search, false) + RETURN { "name": doc.name, "descr": doc.description, "author": doc.author } ``` Bind parameters (table view mode): diff --git a/Documentation/Books/AQL/Operators.mdpp b/Documentation/Books/AQL/Operators.mdpp index aa94408d22..9be204cc75 100644 --- a/Documentation/Books/AQL/Operators.mdpp +++ b/Documentation/Books/AQL/Operators.mdpp @@ -58,7 +58,8 @@ The supported wildcards are *_* to match a single arbitrary character, and *%* t match any number of arbitrary characters. Literal *%* and *_* need to be escaped with a backslash. Backslashes need to be escaped themselves, which effectively means that two reverse solidus characters need to preceed a literal percent sign -or underscore. +or underscore. In arangosh, additional escaping is required, making it four +backslashes in total preceeding the to-be-escaped character. ``` "abc" LIKE "a%" // true @@ -140,10 +141,12 @@ The result of the logical operators in AQL is defined as follows: Some examples for logical operations in AQL: - u.age > 15 && u.address.city != "" - true || false - ! u.isInvalid - 1 || ! 0 +```js +u.age > 15 && u.address.city != "" +true || false +NOT u.isInvalid +1 || ! 0 +``` Passing non-boolean values to a logical operator is allowed. Any non-boolean operands will be casted to boolean implicitly by the operator, without making the query abort. @@ -160,17 +163,20 @@ type and is not necessarily a boolean value. For example, the following logical operations will return boolean values: - 25 > 1 && 42 != 7 // true - 22 IN [ 23, 42 ] || 23 NOT IN [ 22, 7 ] // true - 25 != 25 // false +```js +25 > 1 && 42 != 7 // true +22 IN [ 23, 42 ] || 23 NOT IN [ 22, 7 ] // true +25 != 25 // false +``` whereas the following logical operations will not return boolean values: - 1 || 7 // 1 - null || "foo" // "foo" - null && true // null - true && 23 // 23 - +```js +1 || 7 // 1 +null || "foo" // "foo" +null && true // null +true && 23 // 23 +``` !SUBSUBSECTION Arithmetic operators @@ -196,6 +202,7 @@ RETURN [-x, +y] ``` For exponentiation, there is a [numeric function](Functions/Numeric.md#pow) *POW()*. +The syntax `base ** exp` is not supported. For string concatenation, you must use the [string function](Functions/String.md#concat) *CONCAT()*. Combining two strings with a plus operator (`"foo" + "bar"`) will not work! @@ -203,13 +210,15 @@ Also see [Common Errors](CommonErrors.md). Some example arithmetic operations: - 1 + 1 - 33 - 99 - 12.4 * 4.5 - 13.0 / 0.1 - 23 % 7 - -15 - +9.99 +``` +1 + 1 +33 - 99 +12.4 * 4.5 +13.0 / 0.1 +23 % 7 +-15 ++9.99 +``` The arithmetic operators accept operands of any type. Passing non-numeric values to an arithmetic operator will cast the operands to numbers using the type casting rules @@ -231,20 +240,21 @@ will also produce a result value of `null`. Here are a few examples: - 1 + "a" // 1 - 1 + "99" // 100 - 1 + null // 1 - null + 1 // 1 - 3 + [ ] // 3 - 24 + [ 2 ] // 26 - 24 + [ 2, 4 ] // 0 - 25 - null // 25 - 17 - true // 16 - 23 * { } // 0 - 5 * [ 7 ] // 35 - 24 / "12" // 2 - 1 / 0 // 0 - +``` +1 + "a" // 1 +1 + "99" // 100 +1 + null // 1 +null + 1 // 1 +3 + [ ] // 3 +24 + [ 2 ] // 26 +24 + [ 2, 4 ] // 0 +25 - null // 25 +17 - true // 16 +23 * { } // 0 +5 * [ 7 ] // 35 +24 / "12" // 2 +1 / 0 // 0 +``` !SUBSUBSECTION Ternary operator @@ -255,7 +265,9 @@ evaluates to true, and the third operand otherwise. *Examples* - u.age > 15 || u.active == true ? u.userId : null +```js +u.age > 15 || u.active == true ? u.userId : null +``` !SUBSUBSECTION Range operator @@ -268,18 +280,23 @@ both bounding values included. *Examples* - 2010..2013 +``` +2010..2013 +``` will produce the following result: - [ 2010, 2011, 2012, 2013 ] +```json +[ 2010, 2011, 2012, 2013 ] +``` +There is also a [RANGE() function](Functions/Numeric.md#range). !SUBSUBSECTION Array operators -AQL provides [array operators](Advanced/ArrayOperators.md) [\*] for -array variable expansion and [\*\*] for array contraction. - +AQL provides array operators [\*] for +[array variable expansion](Advanced/ArrayOperators.md#array-expansion) and +[\*\*] for [array contraction](Advanced/ArrayOperators.md#array-contraction). !SUBSUBSECTION Operator precedence diff --git a/Documentation/Books/Manual/DataModeling/Documents/DocumentMethods.mdpp b/Documentation/Books/Manual/DataModeling/Documents/DocumentMethods.mdpp index 736f2eeab2..e9fe97eea2 100644 --- a/Documentation/Books/Manual/DataModeling/Documents/DocumentMethods.mdpp +++ b/Documentation/Books/Manual/DataModeling/Documents/DocumentMethods.mdpp @@ -63,20 +63,20 @@ An attribute name of the form *a.b* is interpreted as attribute path, not as attribute. If you use ```json -{ a : { c : 1 } } +{ "a" : { "c" : 1 } } ``` as example, then you will find all documents, such that the attribute *a* contains a document of the form *{c : 1 }*. For example the document ```json -{ a : { c : 1 }, b : 1 } +{ "a" : { "c" : 1 }, "b" : 1 } ``` will match, but the document ```json -{ a : { c : 1, b : 1 } } +{ "a" : { "c" : 1, "b" : 1 } } ``` will not. @@ -84,20 +84,20 @@ will not. However, if you use ```json -{ a.c : 1 } +{ "a.c" : 1 } ``` then you will find all documents, which contain a sub-document in *a* that has an attribute *c* of value *1*. Both the following documents ```json -{ a : { c : 1 }, b : 1 } +{ "a" : { "c" : 1 }, "b" : 1 } ``` and ```json -{ a : { c : 1, b : 1 } } +{ "a" : { "c" : 1, "b" : 1 } } ``` will match. @@ -194,15 +194,15 @@ The function may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection within a specific range is to use an AQL query as follows: - FOR doc IN @@collection - FILTER doc.value >= @left && doc.value < @right - LIMIT @skip, @limit - RETURN doc - +```js +FOR doc IN @@collection + FILTER doc.value >= @left && doc.value < @right + LIMIT @skip, @limit + RETURN doc +``` **Examples** - Use *toArray* to get all documents at once: @startDocuBlockInline 005_collectionRange @@ -218,7 +218,6 @@ Use *toArray* to get all documents at once: @endDocuBlock 005_collectionRange - !SUBSECTION Closed range @@ -240,15 +239,15 @@ The function may be removed in future versions of ArangoDB. The preferred way for retrieving documents from a collection within a specific range is to use an AQL query as follows: - FOR doc IN @@collection - FILTER doc.value >= @left && doc.value <= @right - LIMIT @skip, @limit - RETURN doc - +```js +FOR doc IN @@collection + FILTER doc.value >= @left && doc.value <= @right + LIMIT @skip, @limit + RETURN doc +``` **Examples** - Use *toArray* to get all documents at once: @startDocuBlockInline 006_collectionClosedRange diff --git a/Documentation/Books/Manual/DataModeling/GraphsVerticesEdges.mdpp b/Documentation/Books/Manual/DataModeling/GraphsVerticesEdges.mdpp index aec9966b5c..be39cae870 100644 --- a/Documentation/Books/Manual/DataModeling/GraphsVerticesEdges.mdpp +++ b/Documentation/Books/Manual/DataModeling/GraphsVerticesEdges.mdpp @@ -5,6 +5,6 @@ Graphs, vertices & edges are defined in the [Graphs](../Graphs/README.md) chapte Related blog posts: - [Graphs in data modeling - is the emperor naked?]( - https://medium.com/@neunhoef/graphs-in-data-modeling-is-the-emperor-naked-2e65e2744413#.x0a5z66ji + https://medium.com/@neunhoef/graphs-in-data-modeling-is-the-emperor-naked-2e65e2744413#.x0a5z66ji) - [Index Free Adjacency or Hybrid Indexes for Graph Databases]( https://www.arangodb.com/2016/04/index-free-adjacency-hybrid-indexes-graph-databases/) diff --git a/Documentation/DocuBlocks/WalLogfileThrottling.md b/Documentation/DocuBlocks/WalLogfileThrottling.md index 883b9ffbaa..c1e797759e 100644 --- a/Documentation/DocuBlocks/WalLogfileThrottling.md +++ b/Documentation/DocuBlocks/WalLogfileThrottling.md @@ -5,10 +5,8 @@ waiting for garbage collection `--wal.throttle-when-pending` The maximum value for the number of write-ahead log garbage-collection -queue -elements. If set to *0*, the queue size is unbounded, and no -writtle-throttling will occur. If set to a non-zero value, -writte-throttling +queue elements. If set to *0*, the queue size is unbounded, and no +write-throttling will occur. If set to a non-zero value, write-throttling will automatically kick in when the garbage-collection queue contains at least as many elements as specified by this option. While write-throttling is active, data-modification operations will @@ -28,8 +26,6 @@ specified amount of time for the write-ahead log garbage-collection queue size to fall below the throttling threshold. If the queue size decreases before the maximum wait time is over, the operation will be executed normally. If the queue size does not decrease before the wait time is -over, -the operation will be aborted with an error. +over, the operation will be aborted with an error. This option only has an effect if `--wal.throttle-when-pending` has a non-zero value, which is not the default. - diff --git a/Documentation/DocuBlocks/collectionByExample.md b/Documentation/DocuBlocks/collectionByExample.md index ea98d73964..dad24ea982 100644 --- a/Documentation/DocuBlocks/collectionByExample.md +++ b/Documentation/DocuBlocks/collectionByExample.md @@ -13,29 +13,44 @@ operator. An attribute name of the form *a.b* is interpreted as attribute path, not as attribute. If you use -*{ a : { c : 1 } }* +```json +{ "a": { "c": 1 } } +``` as example, then you will find all documents, such that the attribute -*a* contains a document of the form *{c : 1 }*. For example the document +*a* contains a document of the form *{ "c": 1 }*. For example the document -*{ a : { c : 1 }, b : 1 }* +```json +{ "a" : { "c" : 1 }, "b" : 1 } +``` will match, but the document -*{ a : { c : 1, b : 1 } }* +```json +{ "a" : { "c" : 1, "b" : 1 } } +``` will not. However, if you use -*{ a.c : 1 }*, +```json +{ "a.c" : 1 } +``` then you will find all documents, which contain a sub-document in *a* that has an attribute *c* of value *1*. Both the following documents -*{ a : { c : 1 }, b : 1 }* and +```json +{ "a" : { "c" : 1 }, "b" : 1 } -*{ a : { c : 1, b : 1 } }* +``` + +and + +```json +{ "a" : { "c" : 1, "b" : 1 } } +``` will match. diff --git a/Documentation/DocuBlocks/collectionByExampleSkiplist.md b/Documentation/DocuBlocks/collectionByExampleSkiplist.md index fb5023482d..57fca56e16 100644 --- a/Documentation/DocuBlocks/collectionByExampleSkiplist.md +++ b/Documentation/DocuBlocks/collectionByExampleSkiplist.md @@ -13,29 +13,44 @@ operator. An attribute name of the form *a.b* is interpreted as attribute path, not as attribute. If you use -*{ a : { c : 1 } }* +```json +{ "a": { "c": 1 } } +``` as example, then you will find all documents, such that the attribute -*a* contains a document of the form *{c : 1 }*. For example the document +*a* contains a document of the form *{ "c": 1 }*. For example the document -*{ a : { c : 1 }, b : 1 }* +```json +{ "a" : { "c" : 1 }, "b" : 1 } +``` will match, but the document -*{ a : { c : 1, b : 1 } }* +```json +{ "a" : { "c" : 1, "b" : 1 } } +``` will not. However, if you use -*{ a.c : 1 }*, +```json +{ "a.c" : 1 } +``` then you will find all documents, which contain a sub-document in *a* -that has an attribute @LIT{c} of value *1*. Both the following documents +that has an attribute *c* of value *1*. Both the following documents -*{ a : { c : 1 }, b : 1 }*and +```json +{ "a" : { "c" : 1 }, "b" : 1 } -*{ a : { c : 1, b : 1 } }* +``` + +and + +```json +{ "a" : { "c" : 1, "b" : 1 } } +``` will match.