diff --git a/Documentation/Books/Users/Aql/Advanced.mdpp b/Documentation/Books/Users/Aql/Advanced.mdpp index 1a6fa92954..9447066861 100644 --- a/Documentation/Books/Users/Aql/Advanced.mdpp +++ b/Documentation/Books/Users/Aql/Advanced.mdpp @@ -27,7 +27,7 @@ explicitly mark their start and end points: RETURN r.user.rating ) } -Subqueries might also include other subqueries themselves. +Subqueries may also include other subqueries themselves. !SUBSECTION Variable expansion diff --git a/Documentation/Books/Users/Aql/Basics.mdpp b/Documentation/Books/Users/Aql/Basics.mdpp index 8c236adb4f..de8b76e91e 100644 --- a/Documentation/Books/Users/Aql/Basics.mdpp +++ b/Documentation/Books/Users/Aql/Basics.mdpp @@ -9,24 +9,23 @@ parser will return an error if it detects more than one data-modification operation in the same query or if it cannot figure out if the query is meant to be a data retrieval or a modification operation. -In SQL, the semicolon can be used to indicate the end of a query and to separate -multiple queries. This is not supported in AQL. Using a semicolon to terminate -a query string is not allowed in AQL. Specifying more than one AQL query in -a single query string is disallowed, too. +AQL only allows *one* query in a single query string; Thus semicolons to +indicate the end of one query and separate multiple queries (as seen in SQL) are +not allowed. !SUBSECTION Whitespace -Whitespace can be used in the query text to increase its readability. However, -for the parser any whitespace (spaces, carriage returns, line feeds, and tab -stops) does not have any special meaning except that it separates individual -tokens in the query. Whitespace within strings or names must be enclosed in -quotes in order to be preserved. +Whitespaces (blanks, carriage returns, line feeds, and tab stops) can be used +in the query text to increase its readability. Tokens have to be separated by +any number of whitespaces. Whitespace within strings or names must be enclosed +in quotes in order to be preserved. !SUBSECTION Comments Comments can be embedded at any position in a query. The text contained in the -comment is ignored by the AQL parser. Comments cannot be nested, meaning -the comment text may not contain another comment. +comment is ignored by the AQL parser. +Multi-line Comments cannot be nested. -> Subsequent comment starts within +comments are ignored, ends will end the comment. AQL supports two types of comments: - Single line comments: These start with a double forward slash and end at @@ -62,7 +61,7 @@ Each of the above operations can be initiated in a query by using a keyword of the same name. An AQL query can (and typically does) consist of multiple of the above operations. -An example AQL query might look like this: +An example AQL query may look like this: FOR u IN users FILTER u.type == "newbie" && u.active == true @@ -108,7 +107,7 @@ The current list of keywords is: - TRUE - FALSE -Additional keywords might be added in future versions of ArangoDB. +Additional keywords may be added in future versions of ArangoDB. !SUBSECTION Names @@ -140,7 +139,7 @@ conventions. When referring to attributes of documents from a collection, the fully qualified attribute name must be used. This is because multiple collections with ambiguous -attribute names might be used in a query. To avoid any ambiguity, it is not +attribute names may be used in a query. To avoid any ambiguity, it is not allowed to refer to an unqualified attribute name. Please refer to the [Naming Conventions in ArangoDB](../NamingConventions/AttributeNames.md) for more information about the @@ -313,7 +312,7 @@ AQL supports the usage of bind parameters, thus allowing to separate the query text from literal values used in the query. It is good practice to separate the query text from the literal values because this will prevent (malicious) injection of keywords and other collection names into an existing query. This -injection would be dangerous because it might change the meaning of an existing +injection would be dangerous because it may change the meaning of an existing query. Using bind parameters, the meaning of an existing query cannot be changed. Bind @@ -491,7 +490,7 @@ from *users* that do not have the *name* attribute at all: RETURN u Furthermore, *null* is less than any other value (excluding *null* itself). That -means documents with non-existing attributes might be included in the result +means documents with non-existing attributes may be included in the result when comparing attribute values with the less than or less equal operators. For example, the following query will return all documents from the collection diff --git a/Documentation/Books/Users/Aql/DataModification.mdpp b/Documentation/Books/Users/Aql/DataModification.mdpp index cc991f369b..600d56655f 100644 --- a/Documentation/Books/Users/Aql/DataModification.mdpp +++ b/Documentation/Books/Users/Aql/DataModification.mdpp @@ -1,7 +1,6 @@ !CHAPTER Data modification queries -Up to including version 2.1, AQL supported data retrieval operations only. -Starting with ArangoDB version 2.2, AQL also supports the following +As of ArangoDB version 2.2, AQL supports the following data-modification operations: - INSERT: insert new documents into a collection @@ -18,8 +17,8 @@ iterate over a given list of documents. They can optionally be combined with UPDATE u WITH { status: 'inactive' } IN users Though there is no need to combine a data-modification query with other -AQL operations such a *FOR* and *FILTER*. For example, the following -stripped-down update query will work, too. It will update one document +AQL operations such as *FOR* and *FILTER*. For example, the following +stripped-down *update* query will work, too. It will *update* one document (with key *foo*) in collection *users*: UPDATE "foo" WITH { status: 'inactive' } IN users @@ -29,20 +28,20 @@ collection per query. That means a data-modification query cannot modify data in multiple collections with a single query, though it is possible to read from one collection and modify data in another with one query. -For example, to copy the contents of collection "users" into collection +For example, to copy the contents of the collection "users" into the collection "backup": FOR u IN users INSERT u IN backup -To remove documents in collection "backup" that have the same key as some +To remove documents in the collection "backup" that have the same key as some matching documents in collection "users": FOR u IN users FILTER u.status == 'inactive' REMOVE u._key IN backup -The name of the modified collection ("backup" in th above cases) must be +The name of the modified collection ("backup" in the above cases) must be known to the AQL executor at query-compile time and cannot change at runtime. Using a bind parameter to specify the collection name is allowed. @@ -51,7 +50,7 @@ If a data-modification operation fails, it will be rolled back automatically as if it never happened. In a cluster, AQL data-modification queries are not executed transactionally. -Additionally, update, replace and remove AQL queries currently require the +Additionally, *update*, *replace* and *remove* AQL queries currently require the *_key* attribute to be specified for all documents that should be modified or -removed, even if a shard key attribute other than *_key* was chosen for the -collection. This restriction might be lifted in a future release of ArangoDB. +removed, even if a shared key attribute other than *_key* was chosen for the +collection. This restriction may be overcome in a future release of ArangoDB. diff --git a/Documentation/Books/Users/Aql/Functions.mdpp b/Documentation/Books/Users/Aql/Functions.mdpp index a72465aa32..615175a7c3 100644 --- a/Documentation/Books/Users/Aql/Functions.mdpp +++ b/Documentation/Books/Users/Aql/Functions.mdpp @@ -417,7 +417,7 @@ AQL supports the following functions to operate on list values: - *UNIQUE(list)*: Returns all unique elements in *list*. To determine uniqueness, the function will use the comparison order. - Calling this function might return the unique elements in any order. + Calling this function may return the unique elements in any order. - *UNION(list1, list2, ...)*: Returns the union of all lists specified. The function expects at least two list values as its arguments. The result is a list @@ -714,7 +714,7 @@ Please use [Graph operations](../Aql/GraphOperations.md) instead. The result of the function is a list of paths. Paths of length 0 will also be returned. Each path is a document consisting of the following attributes: - *vertices*: list of vertices visited along the path - - *edges*: list of edges visited along the path (might be empty) + - *edges*: list of edges visited along the path (may be empty) - *source*: start vertex of path - *destination*: destination vertex of path @@ -892,8 +892,8 @@ Please use [Graph operations](../Aql/GraphOperations.md) instead. When using one of AQL's graph functions please make sure that the graph does not contain cycles, or that you at least specify some maximum depth or uniqueness criteria for a traversal. -If no bounds are set, a traversal might run into an endless loop in a cyclic graph or sub-graph, -and even in a non-cyclic graph, traversing far into the graph might consume a lot of processing +If no bounds are set, a traversal may run into an endless loop in a cyclic graph or sub-graph, +and even in a non-cyclic graph, traversing far into the graph may consume a lot of processing time and memory for the result set. **Warning Deprecated** diff --git a/Documentation/Books/Users/Aql/GraphOperations.mdpp b/Documentation/Books/Users/Aql/GraphOperations.mdpp index ebca8db510..3678934fe4 100644 --- a/Documentation/Books/Users/Aql/GraphOperations.mdpp +++ b/Documentation/Books/Users/Aql/GraphOperations.mdpp @@ -20,7 +20,7 @@ Hence the complexity of these functions depends of the chosen algorithm for this with *n* being the amount of vertices in the graph. For [Dijkstra](http://en.wikipedia.org/wiki/Dijkstra's_algorithm) it would be **O(x\*y\*n^2)** with *n* being the amount of vertices in the graph, *x* the amount of start vertices and *y* the amount of -target vertices. Hence a suggestion might be to use Dijkstra when x\*y < n and the functions supports choosing your algorithm. +target vertices. Hence a suggestion may be to use Dijkstra when x\*y < n and the functions supports choosing your algorithm. !SUBSECTION Edges and Vertices related functions diff --git a/Documentation/Books/Users/Aql/Invoke.mdpp b/Documentation/Books/Users/Aql/Invoke.mdpp index b89bf6ebb8..6ef1a7b895 100644 --- a/Documentation/Books/Users/Aql/Invoke.mdpp +++ b/Documentation/Books/Users/Aql/Invoke.mdpp @@ -123,6 +123,6 @@ number of results and allow the server to apply optimizations. Please note that at the moment the server will always create the full result set for each query so specifying or omitting the *count* attribute currently does not have any impact on query execution. -This might change in the future. Future versions of ArangoDB might create result sets incrementally -on the server-side and might be able to apply optimizations if a result set is not fully fetched by +This may change in the future. Future versions of ArangoDB may create result sets incrementally +on the server-side and may be able to apply optimizations if a result set is not fully fetched by a client. diff --git a/Documentation/Books/Users/Aql/Operations.mdpp b/Documentation/Books/Users/Aql/Operations.mdpp index 27c41ac576..acbd4ebce5 100644 --- a/Documentation/Books/Users/Aql/Operations.mdpp +++ b/Documentation/Books/Users/Aql/Operations.mdpp @@ -106,8 +106,8 @@ FOR u IN users In the above example, all list elements from *users* will be included that have an attribute *active* with value *true* and that have an attribute *age* with a -value less than *39*. All other elements from *users* will be skipped and not be -included the result produced by *RETURN*. +value less than *39* (including *null* ones). All other elements from *users* +will be skipped and not be included the result produced by *RETURN*. It is allowed to specify multiple *FILTER* statements in a query, and even in the same block. If multiple *FILTER* statements are used, their results will be @@ -305,7 +305,7 @@ FOR u IN users REMOVE { _key: u._key } IN backup ``` -*options* can be used to suppress query errors that might occur when trying to +*options* can be used to suppress query errors that may occur when trying to remove non-existing documents. For example, the following query will fail if one of the to-be-deleted documents does not exist: @@ -322,7 +322,7 @@ FOR i IN 1..1000 REMOVE { _key: CONCAT('test', TO_STRING(i)) } IN users OPTIONS { ignoreErrors: true } ``` -To make sure data are durable when a query returns, there is the *waitForSync* +To make sure data has been written to disk when a query returns, there is the *waitForSync* query option: ``` @@ -394,7 +394,7 @@ FOR u IN users UPDATE u WITH { status: 'inactive' } IN backup ``` -*options* can be used to suppress query errors that might occur when trying to +*options* can be used to suppress query errors that may occur when trying to update non-existing documents or violating unique key constraints: ``` @@ -497,7 +497,7 @@ FOR u IN users REPLACE u WITH { status: 'inactive', name: u.name } IN backup ``` -*options* can be used to suppress query errors that might occur when trying to +*options* can be used to suppress query errors that may occur when trying to replace non-existing documents or when violating unique key constraints: ``` @@ -552,7 +552,7 @@ FOR u IN users INSERT { _from: u._id, _to: p._id } IN recommendations ``` -*options* can be used to suppress query errors that might occur when violating unique +*options* can be used to suppress query errors that may occur when violating unique key constraints: ``` diff --git a/Documentation/Books/Users/Aql/Operators.mdpp b/Documentation/Books/Users/Aql/Operators.mdpp index 87e799fe3e..00f37c62e5 100644 --- a/Documentation/Books/Users/Aql/Operators.mdpp +++ b/Documentation/Books/Users/Aql/Operators.mdpp @@ -125,7 +125,7 @@ will produce the following result: !SUBSUBSECTION Operator precedence -The operator precedence in AQL is as follows (lowest precedence first): +The operator precedence in AQL is similar as in other familliar languages (lowest precedence first): - *? :* ternary operator - *||* logical or diff --git a/Documentation/Books/Users/Aql/QueryResults.mdpp b/Documentation/Books/Users/Aql/QueryResults.mdpp index d8f9e292cf..306c834a4a 100644 --- a/Documentation/Books/Users/Aql/QueryResults.mdpp +++ b/Documentation/Books/Users/Aql/QueryResults.mdpp @@ -54,9 +54,9 @@ will be opened. If any of the referenced collections is not present, query execution will again be aborted and an appropriate error message will be returned. -Under some circumstances, executing a query might also produce run-time errors +Under some circumstances, executing a query may also produce run-time errors that cannot be predicted from inspecting the query text alone. This is because -queries might use data from collections that might also be inhomogeneous. Some +queries may use data from collections that may also be inhomogeneous. Some examples that will cause run-time errors are: - Division by zero: Will be triggered when an attempt is made to use the value diff --git a/Documentation/Books/Users/Aql/README.mdpp b/Documentation/Books/Users/Aql/README.mdpp index 0d944e6246..5f9c5ce63f 100644 --- a/Documentation/Books/Users/Aql/README.mdpp +++ b/Documentation/Books/Users/Aql/README.mdpp @@ -14,7 +14,7 @@ AQL is mainly a declarative language, meaning that in a query it is expressed what result should be achieved and not how. AQL aims to be human- readable and therefore uses keywords from the English language. Another design goal of AQL was client independency, meaning that the language and syntax are the same for -all clients, no matter what programming language the clients might use. Further +all clients, no matter what programming language the clients may use. Further design goals of AQL were the support of complex query patterns and the different data models ArangoDB offers. diff --git a/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp b/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp index 84aee2ea2d..7e957fba86 100644 --- a/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp +++ b/Documentation/Books/Users/AqlExamples/DataModificationQueries.mdpp @@ -62,9 +62,10 @@ FOR u IN users ``` To completely replace existing documents, use the *REPLACE* operation. -The following query replaces all documents in collection backup with the documents -found in collection users. Only those documents will be replaced that are present -in both collections. Documents are compared using their *_key* attributes: +The following query replaces all documents in the collection backup with +the documents found in collection users. Documents common to both +collections will be replaced. All other documents will remain unchanged. +Documents are compared using their *_key* attributes: ```js FOR u IN users @@ -82,8 +83,7 @@ FOR u IN users ``` !SUBSECTION Removing documents - -Removing documents can be achieved with the *REMOVE* operation. +Deleting documents can be achieved with the *REMOVE* operation. To remove all users within a certain age range, we can use the following query: ```js diff --git a/Documentation/Books/Users/AqlExtending/Conventions.mdpp b/Documentation/Books/Users/AqlExtending/Conventions.mdpp index e4e4beae8c..e5b8135625 100644 --- a/Documentation/Books/Users/AqlExtending/Conventions.mdpp +++ b/Documentation/Books/Users/AqlExtending/Conventions.mdpp @@ -24,8 +24,8 @@ User functions can take any number of input arguments and should provide one result. They should be kept purely functional and thus free of side effects and state. -Especially it is unsupported to modify any global variables, or to change -data of a collection from inside an AQL user function. +Modification of global variables is unsupported, as is changing +the data of a collection from inside an AQL user function. User function code is late-bound, and may thus not rely on any variables that existed at the time of declaration. If user function code requires diff --git a/Documentation/Books/Users/AqlExtending/README.mdpp b/Documentation/Books/Users/AqlExtending/README.mdpp index 986f54103b..0f79a9db1b 100644 --- a/Documentation/Books/Users/AqlExtending/README.mdpp +++ b/Documentation/Books/Users/AqlExtending/README.mdpp @@ -1,7 +1,7 @@ !CHAPTER Extending AQL with User Functions AQL comes with a built-in set of functions, but it is no -full-feature programming language. +full-featured programming language. To add missing functionality or to simplify queries, users may add own functions to AQL. These functions can be written diff --git a/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp b/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp index 5d335d3785..f46a9bb467 100644 --- a/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp +++ b/Documentation/Books/Users/NamingConventions/AttributeNames.mdpp @@ -4,10 +4,15 @@ Users can pick attribute names for document attributes as desired, provided the following attribute naming constraints are not violated: - Attribute names starting with an underscore are considered to be system attributes for ArangoDB's internal use. Such attribute names are already used - by ArangoDB for special purposes, e.g. *_id* is used to contain a document's - handle, *_key* is used to contain a document's user-defined key, and *_rev* is - used to contain the document's revision number. In edge collections, the - *_from* and *_to* attributes are used to reference other documents. + by ArangoDB for special purposes: + - *_id* is used to contain a document's handle + - *_key* is used to contain a document's user-defined key + - *_rev* is used to contain the document's revision number + - In edge collections, the + - *_from* + - *_to* + + attributes are used to reference other documents. More system attributes may be added in the future without further notice so end users should not use attribute names starting with an underscore for their @@ -39,7 +44,7 @@ following attribute naming constraints are not violated: are removed from the document when saving it. When the document is later requested, it will be returned without these - attributes. For example, if this document is saved + attributes. For example, if this document is saved: { "a" : 1, "" : 2, "_test" : 3, "b": 4 }