From e25c45dbe26e70d0eb85855e891dff229ae8d10d Mon Sep 17 00:00:00 2001 From: Simran Brucherseifer Date: Wed, 22 Jun 2016 15:08:24 +0200 Subject: [PATCH] Use camelCase for variable-names in AQL --- Documentation/Books/AQL/DataQueries.mdpp | 13 +++--- .../Books/AQL/Operations/Collect.mdpp | 40 ++++++++++--------- Documentation/Books/AQL/Operations/For.mdpp | 13 +++--- Documentation/Books/AQL/Operations/Let.mdpp | 9 ++--- .../Books/AQL/Operations/README.mdpp | 2 +- .../Books/AQL/Operations/Remove.mdpp | 6 +-- .../Books/AQL/Operations/Replace.mdpp | 8 ++-- .../Books/AQL/Operations/Return.mdpp | 6 +-- .../Books/AQL/Operations/Update.mdpp | 8 ++-- .../Books/AQL/Operations/Upsert.mdpp | 20 +++++----- Documentation/Books/AQL/Operators.mdpp | 2 +- .../Manual/ReleaseNotes/NewFeatures28.mdpp | 4 +- 12 files changed, 66 insertions(+), 65 deletions(-) diff --git a/Documentation/Books/AQL/DataQueries.mdpp b/Documentation/Books/AQL/DataQueries.mdpp index a903ad25f0..ef9141aea3 100644 --- a/Documentation/Books/AQL/DataQueries.mdpp +++ b/Documentation/Books/AQL/DataQueries.mdpp @@ -37,12 +37,12 @@ FOR doc IN users ``` For every user document, an object with two attributes is returned. The value -of *user* is set to the content of the user document, and *newAttribute* is a -static attribute with the boolean value *true*. +of the attribute *user* is set to the content of the user document, and +*newAttribute* is a static attribute with the boolean value *true*. -Operations like **FILTER**, **SORT** and **LIMIT** can be added to loop bodies +Operations like **FILTER**, **SORT** and **LIMIT** can be added to the loop body to narrow and order the result. Instead of above shown call to `DOCUMENT()`, -one can also retrieve the document of user *phil* like so: +one can also retrieve the document that describes user *phil* like so: ```js FOR doc IN users @@ -67,7 +67,8 @@ Note that operations do not have to occur in a fixed order and that their order can influence the result significantly. Limiting the number of documents before a filter is usually not what you want, because it easily misses a lot of documents that would fulfill the filter criterion, but are ignored because -of a premature *LIMIT* clause. +of a premature *LIMIT* clause. Because of the aforementioned reasons, *LIMIT* +is usually put at the very end, after *FILTER*, *SORT* and other operations. See the [High Level Operations](Operations/README.md) chapter for more details. @@ -271,7 +272,7 @@ the operation type: UPSERT { name: "test" } INSERT { name: "test" } UPDATE { } IN users -LET opType = IS_NULL(old) ? "insert" : "update" +LET opType = IS_NULL(OLD) ? "insert" : "update" RETURN { _key: NEW._key, type: opType } ``` diff --git a/Documentation/Books/AQL/Operations/Collect.mdpp b/Documentation/Books/AQL/Operations/Collect.mdpp index 3359a7ea83..ff47461948 100644 --- a/Documentation/Books/AQL/Operations/Collect.mdpp +++ b/Documentation/Books/AQL/Operations/Collect.mdpp @@ -10,21 +10,23 @@ available. The general syntaxes for *COLLECT* are: ``` -COLLECT variable-name = expression options -COLLECT variable-name = expression INTO groups-variable options -COLLECT variable-name = expression INTO groups-variable = projection-expression options -COLLECT variable-name = expression INTO groups-variable KEEP keep-variable options -COLLECT variable-name = expression WITH COUNT INTO count-variable options -COLLECT variable-name = expression AGGREGATE variable-name = aggregate-expression options -COLLECT AGGREGATE variable-name = aggregate-expression options -COLLECT WITH COUNT INTO count-variable options +COLLECT variableName = expression options +COLLECT variableName = expression INTO groupsVariable options +COLLECT variableName = expression INTO groupsVariable = projectionExpression options +COLLECT variableName = expression INTO groupsVariable KEEP keepVariable options +COLLECT variableName = expression WITH COUNT INTO countVariable options +COLLECT variableName = expression AGGREGATE variableName = aggregateExpression options +COLLECT AGGREGATE variableName = aggregateExpression options +COLLECT WITH COUNT INTO countVariable options ``` +`options` is optional in all variants. + !SUBSECTION Grouping syntaxes The first syntax form of *COLLECT* only groups the result by the defined group criteria specified in *expression*. In order to further process the results -produced by *COLLECT*, a new variable (specified by *variable-name*) is introduced. +produced by *COLLECT*, a new variable (specified by *variableName*) is introduced. This variable contains the group value. Here's an example query that find the distinct values in *u.city* and makes @@ -39,8 +41,8 @@ FOR u IN users ``` The second form does the same as the first form, but additionally introduces a -variable (specified by *groups-variable*) that contains all elements that fell into the -group. This works as follows: The *groups-variable* variable is an array containing +variable (specified by *groupsVariable*) that contains all elements that fell into the +group. This works as follows: The *groupsVariable* variable is an array containing as many elements as there are in the group. Each member of that array is a JSON object in which the value of every variable that is defined in the AQL query is bound to the corresponding attribute. Note that this considers @@ -84,8 +86,8 @@ will be returned. !SUBSECTION Discarding obsolete variables -The third form of *COLLECT* allows rewriting the contents of the *groups-variable* -using an arbitrary *projection-expression*: +The third form of *COLLECT* allows rewriting the contents of the *groupsVariable* +using an arbitrary *projectionExpression*: ``` FOR u IN users @@ -97,10 +99,10 @@ FOR u IN users } ``` -In the above example, only the *projection-expression* is *u.name*. Therefore, -only this attribute is copied into the *groups-variable* for each document. +In the above example, only the *projectionExpression* is *u.name*. Therefore, +only this attribute is copied into the *groupsVariable* for each document. This is probably much more efficient than copying all variables from the scope into -the *groups-variable* as it would happen without a *projection-expression*. +the *groupsVariable* as it would happen without a *projectionExpression*. The expression following *INTO* can also be used for arbitrary computations: @@ -120,13 +122,13 @@ FOR u IN users *COLLECT* also provides an optional *KEEP* clause that can be used to control which variables will be copied into the variable created by `INTO`. If no *KEEP* clause is specified, all variables from the scope will be copied as -sub-attributes into the *groups-variable*. +sub-attributes into the *groupsVariable*. This is safe but can have a negative impact on performance if there are many variables in scope or the variables contain massive amounts of data. -The following example limits the variables that are copied into the *groups-variable* +The following example limits the variables that are copied into the *groupsVariable* to just *name*. The variables *u* and *someCalculation* also present in the scope -will not be copied into *groups-variable* because they are not listed in the *KEEP* clause: +will not be copied into *groupsVariable* because they are not listed in the *KEEP* clause: ``` FOR u IN users diff --git a/Documentation/Books/AQL/Operations/For.mdpp b/Documentation/Books/AQL/Operations/For.mdpp index 98ed732458..a5f7eb40d4 100644 --- a/Documentation/Books/AQL/Operations/For.mdpp +++ b/Documentation/Books/AQL/Operations/For.mdpp @@ -4,14 +4,14 @@ The *FOR* keyword can be to iterate over all elements of an array. The general syntax is: -``` -FOR variable-name IN expression +```js +FOR variableName IN expression ``` -There also is a special case for graph traversals: +There is also a special variant for graph traversals: -``` -FOR vertex-variable-name, edge-variable-name, path-variable-name IN traversal-expression +```js +FOR vertexVariableName, edgeVariableName, pathVariableName IN traversalExpression ``` For this special case see [the graph traversals chapter](../Graphs/Traversals.md). @@ -20,7 +20,7 @@ For all other cases read on: Each array element returned by *expression* is visited exactly once. It is required that *expression* returns an array in all cases. The empty array is allowed, too. The current array element is made available for further processing -in the variable specified by *variable-name*. +in the variable specified by *variableName*. ``` FOR u IN users @@ -61,4 +61,3 @@ In this example, there are two array iterations: an outer iteration over the arr traversed as many times as there are elements in the outer array. For each iteration, the current values of *users* and *locations* are made available for further processing in the variable *u* and *l*. - diff --git a/Documentation/Books/AQL/Operations/Let.mdpp b/Documentation/Books/AQL/Operations/Let.mdpp index 2a88a969df..a6a3d96e08 100644 --- a/Documentation/Books/AQL/Operations/Let.mdpp +++ b/Documentation/Books/AQL/Operations/Let.mdpp @@ -1,11 +1,11 @@ !CHAPTER LET -The *LET* statement can be used to assign an arbitrary value to a variable. The -variable is then introduced in the scope the *LET* statement is placed in. The -general syntax is: +The *LET* statement can be used to assign an arbitrary value to a variable. +The variable is then introduced in the scope the *LET* statement is placed in. +The general syntax is: ``` -LET variable-name = expression +LET variableName = expression ``` *LET* statements are mostly used to declare complex computations and to avoid @@ -47,4 +47,3 @@ FOR u IN users "memberShips" : memberships } ``` - diff --git a/Documentation/Books/AQL/Operations/README.mdpp b/Documentation/Books/AQL/Operations/README.mdpp index de210e3fff..d89c663e82 100644 --- a/Documentation/Books/AQL/Operations/README.mdpp +++ b/Documentation/Books/AQL/Operations/README.mdpp @@ -6,7 +6,7 @@ The following high-level operations are described here after: * [RETURN](Return.md): Produce the result of a query. * [FILTER](Filter.md): Restrict the results to elements that match arbitrary logical conditions. * [SORT](Sort.md): Force a sort of the array of already produced intermediate results. -* [LIMIT](Limit.md): Reduce the number of elements in the result to at most the specified number, optionally skip elements. +* [LIMIT](Limit.md): Reduce the number of elements in the result to at most the specified number, optionally skip elements (pagination). * [LET](Let.md): Assign an arbitrary value to a variable. * [COLLECT](Collect.md): Group an array by one or multiple group criteria. Can also count and aggregate. * [REMOVE](Remove.md): Remove documents from a collection. diff --git a/Documentation/Books/AQL/Operations/Remove.mdpp b/Documentation/Books/AQL/Operations/Remove.mdpp index 996de6c6fd..e86ae0a02a 100644 --- a/Documentation/Books/AQL/Operations/Remove.mdpp +++ b/Documentation/Books/AQL/Operations/Remove.mdpp @@ -15,11 +15,11 @@ traversal operations, or AQL functions that can read documents. The syntax for a remove operation is: ``` -REMOVE key-expression IN collection options +REMOVE keyExpression IN collection options ``` *collection* must contain the name of the collection to remove the documents -from. *key-expression* must be an expression that contains the document identification. +from. *keyExpression* must be an expression that contains the document identification. This can either be a string (which must then contain the [document key](../../Manual/Appendix/Glossary.html#document-key)) or a document, which must contain a *_key* attribute. @@ -84,7 +84,7 @@ are allowed, too).`REMOVE` introduces the pseudo-value `OLD` to refer to the rem documents: ``` -REMOVE key-expression IN collection options RETURN OLD +REMOVE keyExpression IN collection options RETURN OLD ``` Following is an example using a variable named `removed` for capturing the removed diff --git a/Documentation/Books/AQL/Operations/Replace.mdpp b/Documentation/Books/AQL/Operations/Replace.mdpp index eb9ca32e07..3f8ba776f6 100644 --- a/Documentation/Books/AQL/Operations/Replace.mdpp +++ b/Documentation/Books/AQL/Operations/Replace.mdpp @@ -15,7 +15,7 @@ The two syntaxes for a replace operation are: ``` REPLACE document IN collection options -REPLACE key-expression WITH document IN collection options +REPLACE keyExpression WITH document IN collection options ``` *collection* must contain the name of the collection in which the documents should @@ -35,7 +35,7 @@ FOR u IN users REPLACE { name: CONCAT(u.firstName, u.lastName, status: u.status) } IN users ``` -When using the second syntax, *key-expression* provides the document identification. +When using the second syntax, *keyExpression* provides the document identification. This can either be a string (which must then contain the document key) or a document, which must contain a *_key* attribute. @@ -103,8 +103,8 @@ in the replace expression. ``` REPLACE document IN collection options RETURN OLD REPLACE document IN collection options RETURN NEW -REPLACE key-expression WITH document IN collection options RETURN OLD -REPLACE key-expression WITH document IN collection options RETURN NEW +REPLACE keyExpression WITH document IN collection options RETURN OLD +REPLACE keyExpression WITH document IN collection options RETURN NEW ``` Following is an example using a variable named `previous` to return the original diff --git a/Documentation/Books/AQL/Operations/Return.mdpp b/Documentation/Books/AQL/Operations/Return.mdpp index 0f4891e6d0..3398f53eda 100644 --- a/Documentation/Books/AQL/Operations/Return.mdpp +++ b/Documentation/Books/AQL/Operations/Return.mdpp @@ -18,8 +18,8 @@ the currently iterated array without modification, the following simple form can be used: ``` -FOR variable-name IN expression - RETURN variable-name +FOR variableName IN expression + RETURN variableName ``` As *RETURN* allows specifying an expression, arbitrary computations can be @@ -36,7 +36,7 @@ The *DISTINCT* keyword will ensure uniqueness of the values returned by the *RETURN* statement: ``` -FOR variable-name IN expression +FOR variableName IN expression RETURN DISTINCT expression ``` diff --git a/Documentation/Books/AQL/Operations/Update.mdpp b/Documentation/Books/AQL/Operations/Update.mdpp index 0451132af8..3dbdce78e4 100644 --- a/Documentation/Books/AQL/Operations/Update.mdpp +++ b/Documentation/Books/AQL/Operations/Update.mdpp @@ -15,7 +15,7 @@ The two syntaxes for an update operation are: ``` UPDATE document IN collection options -UPDATE key-expression WITH document IN collection options +UPDATE keyExpression WITH document IN collection options ``` *collection* must contain the name of the collection in which the documents should @@ -36,7 +36,7 @@ FOR u IN users UPDATE { name: CONCAT(u.firstName, u.lastName) } IN users ``` -When using the second syntax, *key-expression* provides the document identification. +When using the second syntax, *keyExpression* provides the document identification. This can either be a string (which must then contain the document key) or a document, which must contain a *_key* attribute. @@ -142,8 +142,8 @@ in the update expression. ``` UPDATE document IN collection options RETURN OLD UPDATE document IN collection options RETURN NEW -UPDATE key-expression WITH document IN collection options RETURN OLD -UPDATE key-expression WITH document IN collection options RETURN NEW +UPDATE keyExpression WITH document IN collection options RETURN OLD +UPDATE keyExpression WITH document IN collection options RETURN NEW ``` Following is an example using a variable named `previous` to capture the original diff --git a/Documentation/Books/AQL/Operations/Upsert.mdpp b/Documentation/Books/AQL/Operations/Upsert.mdpp index 7b9315f7d6..4fda759891 100644 --- a/Documentation/Books/AQL/Operations/Upsert.mdpp +++ b/Documentation/Books/AQL/Operations/Upsert.mdpp @@ -14,28 +14,28 @@ traversal operations, or AQL functions that can read documents. The syntax for an upsert operation is: ``` -UPSERT search-expression INSERT insert-expression UPDATE update-expression IN collection options -UPSERT search-expression INSERT insert-expression REPLACE update-expression IN collection options +UPSERT searchExpression INSERT insertExpression UPDATE updateExpression IN collection options +UPSERT searchExpression INSERT insertExpression REPLACE updateExpression IN collection options ``` When using the *UPDATE* variant of the upsert operation, the found document will be -partially updated, meaning only the attributes specified in *update-expression* will be +partially updated, meaning only the attributes specified in *updateExpression* will be updated or added. When using the *REPLACE* variant of upsert, existing documents will -be replaced with the contexts of *update-expression*. +be replaced with the contexts of *updateExpression*. Updating a document will modify the document's revision number with a server-generated value. The system attributes *_id*, *_key* and *_rev* cannot be updated, *_from* and *_to* can. -The *search-expression* contains the document to be looked for. It must be an object +The *searchExpression* contains the document to be looked for. It must be an object literal without dynamic attribute names. In case no such document can be found in *collection*, a new document will be inserted into the collection as specified in the -*insert-expression*. +*insertExpression*. -In case at least one document in *collection* matches the *search-expression*, it will -be updated using the *update-expression*. When more than one document in the collection -matches the *search-expression*, it is undefined which of the matching documents will +In case at least one document in *collection* matches the *searchExpression*, it will +be updated using the *updateExpression*. When more than one document in the collection +matches the *searchExpression*, it is undefined which of the matching documents will be updated. It is therefore often sensible to make sure by other means (such as unique -indexes, application logic etc.) that at most one document matches *search-expression*. +indexes, application logic etc.) that at most one document matches *searchExpression*. The following query will look in the *users* collection for a document with a specific *name* attribute value. If the document exists, its *logins* attribute will be increased diff --git a/Documentation/Books/AQL/Operators.mdpp b/Documentation/Books/AQL/Operators.mdpp index 2c05c5760a..1da7838bb0 100644 --- a/Documentation/Books/AQL/Operators.mdpp +++ b/Documentation/Books/AQL/Operators.mdpp @@ -144,7 +144,7 @@ Some examples for logical operations in AQL: ! u.isInvalid 1 || ! 0 -Passing non-boolean values to a logical operator is allowed. Any-non boolean operands +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. The *conversion to a boolean value* works as follows: diff --git a/Documentation/Books/Manual/ReleaseNotes/NewFeatures28.mdpp b/Documentation/Books/Manual/ReleaseNotes/NewFeatures28.mdpp index 86470336ed..e1f370edf7 100644 --- a/Documentation/Books/Manual/ReleaseNotes/NewFeatures28.mdpp +++ b/Documentation/Books/Manual/ReleaseNotes/NewFeatures28.mdpp @@ -11,7 +11,7 @@ here. For a list of bugfixes, please consult the AQL offers a new feature to traverse over a graph without writing JavaScript functions but with all the other features you know from AQL. For this purpose, a special version of -`FOR variable-name IN expression` has been introduced. +`FOR variableName IN expression` has been introduced. This special version has the following format: `FOR vertex-variable, edge-variable, path-variable IN traversal-expression`, where `traversal-expression` has the following format: @@ -31,7 +31,7 @@ The three output variables have the following semantics: * edge-variable: The last visited edge (optional). * path-variable: The complete path from start-vertex to vertex-variable (optional). -The traversal statement can be used in the same way as the original `FOR variable-name IN expression`, +The traversal statement can be used in the same way as the original `FOR variableName IN expression`, and can be combined with filters and other AQL constructs. As an example one can now find the friends of a friend for a certain user with this AQL statement: