|
|
|
|
@ -31,7 +31,7 @@
|
|
|
|
|
/// @section AqlPurpose Purpose
|
|
|
|
|
///
|
|
|
|
|
/// The ArangoDB query language (AQL) can be used to retrieve data that is
|
|
|
|
|
/// stored in ArangoDB. The general workflow is as follows:
|
|
|
|
|
/// stored in ArangoDB. The general workflow when executing a query is as follows:
|
|
|
|
|
/// - a client application ships an AQL query to the ArangoDB server. The query
|
|
|
|
|
/// text contains everything ArangoDB needs to compile the result set.
|
|
|
|
|
/// - ArangoDB will parse the query, execute it and compile the results. If
|
|
|
|
|
@ -42,12 +42,17 @@
|
|
|
|
|
///
|
|
|
|
|
/// 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.
|
|
|
|
|
/// 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 design goals of AQL were to support complex query patterns, and
|
|
|
|
|
/// to support the different data models ArangoDB offers.
|
|
|
|
|
///
|
|
|
|
|
/// In its purpose, AQL is similar to the Structured Query Language (SQL),
|
|
|
|
|
/// but the languages have major syntactic differences. Furthermore, to avoid
|
|
|
|
|
/// any confusion between the two languages, the keywords in AQL have been
|
|
|
|
|
/// chosen to be different from the keywords used in SQL.
|
|
|
|
|
/// but the two languages have major syntactic differences. Furthermore, to
|
|
|
|
|
/// avoid any confusion between the two languages, the keywords in AQL have
|
|
|
|
|
/// been chosen to be different from the keywords used in SQL.
|
|
|
|
|
///
|
|
|
|
|
/// @section AqlBasics Language basics
|
|
|
|
|
///
|
|
|
|
|
@ -178,13 +183,16 @@
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlTypes Data types
|
|
|
|
|
///
|
|
|
|
|
/// The following data types exist in AQL:
|
|
|
|
|
/// - null: an empty value, also: the absence of a value
|
|
|
|
|
/// - bool: boolean truth value with possible values @LIT{false} and @LIT{true}
|
|
|
|
|
/// - number: signed (real) number
|
|
|
|
|
/// - string: UTF-8 encoded text value
|
|
|
|
|
/// - list: sequence of values, referred to by their positions
|
|
|
|
|
/// - document: sequence of values, referred to by their names
|
|
|
|
|
/// AQL supports both primitive and compound data types. The following types are
|
|
|
|
|
/// available:
|
|
|
|
|
/// - primitive types: consisting of exactly one value
|
|
|
|
|
/// - null: an empty value, also: the absence of a value
|
|
|
|
|
/// - bool: boolean truth value with possible values @LIT{false} and @LIT{true}
|
|
|
|
|
/// - number: signed (real) number
|
|
|
|
|
/// - string: UTF-8 encoded text value
|
|
|
|
|
/// - compound types: consisting of multiple values
|
|
|
|
|
/// - list: sequence of values, referred to by their positions
|
|
|
|
|
/// - document: sequence of values, referred to by their names
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlLiteralsNumber Numeric literals
|
|
|
|
|
///
|
|
|
|
|
@ -204,7 +212,7 @@
|
|
|
|
|
/// escaped using the backslash (@LIT{\\}) symbol.
|
|
|
|
|
/// Backslash literals themselves also be escaped using a backslash.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude strings
|
|
|
|
|
/// @verbinclude aqlstrings
|
|
|
|
|
///
|
|
|
|
|
/// All string literals must be UTF-8 encoded. It is currently not possible to use
|
|
|
|
|
/// arbitrary binary data if it is not UTF-8 encoded. A workaround to use
|
|
|
|
|
@ -279,32 +287,12 @@
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlbind
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperators Operators
|
|
|
|
|
/// @subsection AqlTypeOrder Type and value order
|
|
|
|
|
///
|
|
|
|
|
/// AQL supports a number of operators that can be used in expressions.
|
|
|
|
|
/// There are comparison, logical, and arithmetic operators.
|
|
|
|
|
/// When checking for equality or inequality or when determining the sort order of
|
|
|
|
|
/// values, AQL uses a deterministic algorithm that takes both the data types and
|
|
|
|
|
/// the actual values into account.
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlOperatorsComp Comparison operators
|
|
|
|
|
///
|
|
|
|
|
/// The following comparison operators are supported:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{==} equality
|
|
|
|
|
/// - @LIT{!=} inequality
|
|
|
|
|
/// - @LIT{<} less than
|
|
|
|
|
/// - @LIT{<=} less or equal
|
|
|
|
|
/// - @LIT{>} greater than
|
|
|
|
|
/// - @LIT{>=} greater or equal
|
|
|
|
|
/// - @LIT{in} test if a value is contained in a list
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{in} operator expects the second operand to be of type list. All
|
|
|
|
|
/// other operators accept any data types for the first and second operands.
|
|
|
|
|
///
|
|
|
|
|
/// Each of the comparison operators returns a boolean value if the comparison
|
|
|
|
|
/// can be evaluated and returns @LIT{true} if the comparison evaluates to true,
|
|
|
|
|
/// and @LIT{false} otherwise.
|
|
|
|
|
///
|
|
|
|
|
/// When comparing two operands using one of the above operators, both values and
|
|
|
|
|
/// data types are taken into account.
|
|
|
|
|
/// The compared operands are first compared by their data types, and only by their
|
|
|
|
|
/// data values if the operands have the same data types.
|
|
|
|
|
///
|
|
|
|
|
@ -312,7 +300,7 @@
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqltypeorder
|
|
|
|
|
///
|
|
|
|
|
/// This means @LIT{null} is the smallest type, and @LIT{document} is the type
|
|
|
|
|
/// This means @LIT{null} is the smallest type in AQL, and @LIT{document} is the type
|
|
|
|
|
/// with the highest order. If the compared operands have a different type, then the
|
|
|
|
|
/// comparison result is determined and the comparison is finished.
|
|
|
|
|
///
|
|
|
|
|
@ -325,8 +313,17 @@
|
|
|
|
|
///
|
|
|
|
|
/// If the two compared operands have the same data types, then the operands values
|
|
|
|
|
/// are compared. For the primitive types (null, boolean, number, and string), the
|
|
|
|
|
/// value comparison is simple. For compound, types the following special rules are
|
|
|
|
|
/// applied:
|
|
|
|
|
/// result is defined as follows:
|
|
|
|
|
///
|
|
|
|
|
/// - null: @LIT{null} is equal to @LIT{null}
|
|
|
|
|
/// - boolean:@LIT{false} is less than @LIT{true}
|
|
|
|
|
/// - number: numeric values are ordered by their cardinal value
|
|
|
|
|
/// - string: string values are ordered using a byte-wise comparison
|
|
|
|
|
///
|
|
|
|
|
/// Note: unlike in SQL, @LIT{null} can be compared to any value, including @LIT{null}
|
|
|
|
|
/// itself, without the result being converted into @LIT{null} automatically.
|
|
|
|
|
///
|
|
|
|
|
/// For compound, types the following special rules are applied:
|
|
|
|
|
///
|
|
|
|
|
/// Two list values are compared by comparing their individual elements position by
|
|
|
|
|
/// position, starting at the first element. For each position, the element types are
|
|
|
|
|
@ -358,8 +355,79 @@
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlcompareexamples2
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlData Accessing data from collections
|
|
|
|
|
///
|
|
|
|
|
/// Collection data can be accessed by specifying a collection name in a query.
|
|
|
|
|
/// A collection can be understood as a list of documents, and that is how they
|
|
|
|
|
/// are treated in AQL. Documents from collections are normally accessing using
|
|
|
|
|
/// the @LIT{FOR} keyword. Note that when iterating over documents from a collection,
|
|
|
|
|
/// the order of documents is undefined. To traverse documents in an explicit and
|
|
|
|
|
/// deterministic order, the @LIT{SORT} keyword should be used in addition.
|
|
|
|
|
///
|
|
|
|
|
/// Data in collections is stored in documents, with each document potentially
|
|
|
|
|
/// having different attributes than other documents. This is true even for documents
|
|
|
|
|
/// of the same collection.
|
|
|
|
|
///
|
|
|
|
|
/// It is therefore quite normal to encounter documents that do not have some or
|
|
|
|
|
/// all of the attributes that are queried in an AQL query. In this case, the
|
|
|
|
|
/// non-existing attributes in the document will be treated as if they would exist
|
|
|
|
|
/// with a value of @LIT{null}.
|
|
|
|
|
/// That means that comparing a document attribute to @LIT{null} will return true
|
|
|
|
|
/// if the document has the particular attribute and the attribute has a value of
|
|
|
|
|
/// @LIT{null}, or that the document does not have the particular attribute at all.
|
|
|
|
|
///
|
|
|
|
|
/// For example, the following query will return all documents from the collection
|
|
|
|
|
/// @LIT{users} that have a value of @LIT{null} in the attribute @LIT{name}, plus
|
|
|
|
|
/// all documents from @LIT{users} that do not have the @LIT{name} attribute at all:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlnull
|
|
|
|
|
///
|
|
|
|
|
/// Furthermore, @LIT{null} is less than any other value (excluding @LIT{null}
|
|
|
|
|
/// itself). That means documents with non-existing attributes might be included
|
|
|
|
|
/// in the result when comparing attribute values with the less than or less equal
|
|
|
|
|
/// operators.
|
|
|
|
|
///
|
|
|
|
|
/// For example, the following query with return all documents from the collection
|
|
|
|
|
/// @LIT{users} that have an attribute @LIT{age} with a value less than @LIT{39}, but
|
|
|
|
|
/// also all documents from the collection that do not have the attribute @LIT{age}
|
|
|
|
|
/// at all.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlnull2
|
|
|
|
|
///
|
|
|
|
|
/// This behavior should always be taken into account when writing queries.
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperators Operators
|
|
|
|
|
///
|
|
|
|
|
/// AQL supports a number of operators that can be used in expressions.
|
|
|
|
|
/// There are comparison, logical, arithmetic, and the ternary operator.
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlOperatorsComparison Comparison operators
|
|
|
|
|
///
|
|
|
|
|
/// Comparison (or relational) operators compare two operands. They can be used
|
|
|
|
|
/// with any input data types, and will return a boolean result value.
|
|
|
|
|
///
|
|
|
|
|
/// The following comparison operators are supported:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{==} equality
|
|
|
|
|
/// - @LIT{!=} inequality
|
|
|
|
|
/// - @LIT{<} less than
|
|
|
|
|
/// - @LIT{<=} less or equal
|
|
|
|
|
/// - @LIT{>} greater than
|
|
|
|
|
/// - @LIT{>=} greater or equal
|
|
|
|
|
/// - @LIT{in} test if a value is contained in a list
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{in} operator expects the second operand to be of type list. All
|
|
|
|
|
/// other operators accept any data types for the first and second operands.
|
|
|
|
|
///
|
|
|
|
|
/// Each of the comparison operators returns a boolean value if the comparison
|
|
|
|
|
/// can be evaluated and returns @LIT{true} if the comparison evaluates to true,
|
|
|
|
|
/// and @LIT{false} otherwise.
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlOperatorsLogical Logical operators
|
|
|
|
|
///
|
|
|
|
|
/// Logical operators combine two boolean operands in a logical operation and
|
|
|
|
|
/// return a boolean result value.
|
|
|
|
|
///
|
|
|
|
|
/// The following logical operators are supported:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{&&} logical and operator
|
|
|
|
|
@ -379,6 +447,10 @@
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlOperatorsArithmetic Arithmetic operators
|
|
|
|
|
///
|
|
|
|
|
/// 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:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{+} addition
|
|
|
|
|
@ -418,7 +490,7 @@
|
|
|
|
|
/// - @LIT{&&} logical and
|
|
|
|
|
/// - @LIT{==}, @LIT{!=} equality and inequality
|
|
|
|
|
/// - @LIT{in} in operator
|
|
|
|
|
/// - @LIT{<}, @LIT{<=}, @LIT{>=}, @LIT{>} less than, less equal,
|
|
|
|
|
/// - @LIT{<}, @LIT{<=}, @LIT{>=}, @LIT{>} less than, less equal,
|
|
|
|
|
/// greater equal, greater than
|
|
|
|
|
/// - @LIT{+}, @LIT{-} addition, subtraction
|
|
|
|
|
/// - @LIT{*}, @LIT{/}, @LIT{%} multiplication, division, modulus
|
|
|
|
|
@ -433,28 +505,306 @@
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlFunctions Functions
|
|
|
|
|
///
|
|
|
|
|
/// TODO
|
|
|
|
|
/// AQL supports functions to allow more complex computations. Functions can be
|
|
|
|
|
/// called at any query position where an expression is allowed. The general function
|
|
|
|
|
/// call syntax is:
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlTypeCasting Type casting
|
|
|
|
|
/// @verbinclude aqlfunctionsyntax
|
|
|
|
|
///
|
|
|
|
|
/// TODO
|
|
|
|
|
/// @LIT{FUNCTIONNAME} is the name of the function to be called, and @LIT{arguments}
|
|
|
|
|
/// is a comma-separated list of function arguments. If a function does not need any
|
|
|
|
|
/// arguments, the argument list can be left empty. However, even if the argument list
|
|
|
|
|
/// is empty the parentheses around it are still mandatory to make function calls
|
|
|
|
|
/// distinguishable from variable names. Function names are case-sensitive.
|
|
|
|
|
/// Currently, all functions in AQL have upper-cased names.
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlFunctionsCasting Type cast functions
|
|
|
|
|
///
|
|
|
|
|
/// As mentioned before, some of the operators expect their operands to have a
|
|
|
|
|
/// certain data type. For example, the logical operators expect their operands to
|
|
|
|
|
/// be boolean values, and the arithmetic operators expect their operands to be
|
|
|
|
|
/// numeric values.
|
|
|
|
|
/// If an operation is performed with operands of an unexpect type, the operation
|
|
|
|
|
/// will fail with an error. To avoid such failures, value types can be converted
|
|
|
|
|
/// explicitly in a query. This is called type casting.
|
|
|
|
|
///
|
|
|
|
|
/// In an AQL query, type casts are performed only upon request and not implicitly.
|
|
|
|
|
/// This helps avoiding unexpected results. All type casts have to be performed
|
|
|
|
|
/// by invoking a type cast function. The following type cast functions are
|
|
|
|
|
/// available:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{TONULL}: takes an input operand of any type and returns a @LIT{null} value
|
|
|
|
|
/// - @LIT{TOBOOL}: takes an input operand of any type and converts it into the appropriate
|
|
|
|
|
/// boolean value
|
|
|
|
|
/// - @LIT{TONUMBER}: takes an input operand of any type and converts it into
|
|
|
|
|
/// a numeric value
|
|
|
|
|
/// - @LIT{TOSTRING}: takes an input operand of any type and converts it into a string
|
|
|
|
|
/// value
|
|
|
|
|
///
|
|
|
|
|
/// Each of the above functions takes an operand of any data type and returns a result
|
|
|
|
|
/// value of the requested type.
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlFunctionsChecking Type check functions
|
|
|
|
|
///
|
|
|
|
|
/// AQL also offers functions to check the data type of a value at runtime. The
|
|
|
|
|
/// following type check functions are available:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{ISNULL}: checks whether the argument is a @LIT{null} value
|
|
|
|
|
/// - @LIT{ISBOOL}: checks whether the argument is a boolean value
|
|
|
|
|
/// - @LIT{ISNUMBER}: checks whether the argument is a numeric value
|
|
|
|
|
/// - @LIT{ISSTRING}: checks whether the argument is a string value
|
|
|
|
|
/// - @LIT{ISLIST}: checks whether the argument is a list value
|
|
|
|
|
/// - @LIT{ISDOCUMENT}: checks whether the argument is a document value
|
|
|
|
|
///
|
|
|
|
|
/// Each of the above functions accepts an operand of any type and returns a boolean
|
|
|
|
|
/// result value.
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlFunctionsNumeric Numeric functions
|
|
|
|
|
///
|
|
|
|
|
/// AQL offers some numeric functions for calculations. The following functions are
|
|
|
|
|
/// supported:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{FLOOR}: returns the integer closest but not greater to the specified value
|
|
|
|
|
/// - @LIT{CEIL}: returns the integer closest but not less than the specified value
|
|
|
|
|
/// - @LIT{ROUND}: returns the integer closest to the specified value
|
|
|
|
|
/// - @LIT{ABS}: returns the absolute value
|
|
|
|
|
/// - @LIT{RAND}: returns a random number between 0 and 1
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlFunctionsString String functions
|
|
|
|
|
///
|
|
|
|
|
/// AQL offers the following string-related functions:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{CONCAT}: concatenate the strings passed as arguments and return the result
|
|
|
|
|
/// string
|
|
|
|
|
///
|
|
|
|
|
/// @subsubsection AqlFunctionsList List functions
|
|
|
|
|
///
|
|
|
|
|
/// AQL supports the following functions to operate on list values:
|
|
|
|
|
///
|
|
|
|
|
/// - @LIT{LENGTH}: returns the length (number of elements) of a list
|
|
|
|
|
/// - @LIT{MIN}: returns the smallest element of a list
|
|
|
|
|
/// - @LIT{MAX}: returns the greatest element of a list
|
|
|
|
|
///
|
|
|
|
|
/// Apart from these functions, AQL also offers several language constructs (e.g.
|
|
|
|
|
/// @LIT{FOR}, @LIT{SORT}, @LIT{LIMT}, @LIT{COLLECT}) to operate on lists.
|
|
|
|
|
///
|
|
|
|
|
/// @section AqlOperations High-level operations
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationFor For
|
|
|
|
|
/// @subsection AqlOperationFor FOR
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationReturn Return
|
|
|
|
|
/// The @LIT{FOR} keyword can be to iterate over all elements of a list.
|
|
|
|
|
/// The general syntax is:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlforsyntax
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationFilter Filter
|
|
|
|
|
/// Each list element returned by @LIT{expression} is visited exactly once. It is
|
|
|
|
|
/// required that @LIT{expression} returns a list in all cases. The empty list is
|
|
|
|
|
/// allowed, too. The current list element is made available for further processing
|
|
|
|
|
/// in the variable specified by @LIT{variable-name}.
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationSort Sort
|
|
|
|
|
/// @verbinclude aqlfor
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationLimit Limit
|
|
|
|
|
/// This will iterate over all elements from the list @LIT{users} (note: this list
|
|
|
|
|
/// consists of all documents from the collection named "users" in this case) and
|
|
|
|
|
/// make the current list element available in variable @LIT{u}. @LIT{u} is not modified
|
|
|
|
|
/// in this example but simply pushed into the result using the @LIT{RETURN} keyword.
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationLet Let
|
|
|
|
|
/// Note: when iterating over collection-based lists as shown here, the order of
|
|
|
|
|
/// documents is undefined unless an explicit sort order is defined using a @LIT{SORT}
|
|
|
|
|
/// statement.
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationCollect Collect
|
|
|
|
|
/// The variable introduced by @LIT{FOR} is available until the scope the @LIT{FOR} is
|
|
|
|
|
/// placed in is closed.
|
|
|
|
|
///
|
|
|
|
|
/// Another example that uses a statically declared list of values to iterate over:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlforstatic
|
|
|
|
|
///
|
|
|
|
|
/// Nesting of multiple @LIT{FOR} statements is allowed, too. When @LIT{FOR} statements
|
|
|
|
|
/// are nested, a cross product of the list elements returned by the individual @LIT{FOR}
|
|
|
|
|
/// statements will be created.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlfornested
|
|
|
|
|
///
|
|
|
|
|
/// In this example, there are two list iterations: an outer iteration
|
|
|
|
|
/// over the list @LIT{users} plus an inner iteration over the list @LIT{locations}.
|
|
|
|
|
/// The inner list is traversed as many times as there are elements in the outer
|
|
|
|
|
/// list.
|
|
|
|
|
/// For each iteration, the current values of @LIT{users} and @LIT{locations} are
|
|
|
|
|
/// made available for further processing in the variable @LIT{u} and @LIT{l}.
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationReturn RETURN
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{RETURN} statement can (and must) be used to produce the result of a query.
|
|
|
|
|
/// It is mandatory to specify a @LIT{RETURN} statement at the end of each block in a query,
|
|
|
|
|
/// otherwise the query result would be undefined.
|
|
|
|
|
///
|
|
|
|
|
/// The general syntax for @LIT{return} is:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlreturnsyntax
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{expression} returned by @LIT{RETURN} is produced for each iteration the @LIT{RETURN}
|
|
|
|
|
/// statement is placed in. That means the result of a @LIT{RETURN} statement is always a list
|
|
|
|
|
/// (this includes the empty list).
|
|
|
|
|
/// To return all elements from the currently iterated list without modification, the following
|
|
|
|
|
/// simple form can be used:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlreturn
|
|
|
|
|
///
|
|
|
|
|
/// As @LIT{RETURN} allows specifying an expression, arbitrary computations can be performed to
|
|
|
|
|
/// calculate the result elements. Any of the variables valid in the scope the @LIT{RETURN} is
|
|
|
|
|
/// placed in can be used for the computations.
|
|
|
|
|
///
|
|
|
|
|
/// Note: return will close the current scope and eliminate all local variables in it.
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationFilter FILTER
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{FILTER} statement can be used to restrict the results to elements that match an
|
|
|
|
|
/// arbitrary logical condition.
|
|
|
|
|
/// The general syntax is:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlfiltersyntax
|
|
|
|
|
///
|
|
|
|
|
/// @LIT{condition} must be a condition that evaluates to either @LIT{false} or @LIT{true}. If
|
|
|
|
|
/// the condition result is false, the current element is skipped, so it will not be processed
|
|
|
|
|
/// further and not be part of the result. If the condition is true, the current element is
|
|
|
|
|
/// not skipped and can be further processed.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlfilter
|
|
|
|
|
///
|
|
|
|
|
/// In the above example, all list elements from @LIT{users} will be included that have an
|
|
|
|
|
/// attribute @LIT{active} with value @LIT{true} and that have an attribute @LIT{age} with a
|
|
|
|
|
/// value less than @LIT{39}. All other elements from @LIT{users} will be skipped and not
|
|
|
|
|
/// be included the result produced by @LIT{RETURN}.
|
|
|
|
|
///
|
|
|
|
|
/// It is allowed to specifiy multiple @LIT{FILTER} statements in a query, and even in the
|
|
|
|
|
/// same block. If multiple @LIT{FILTER} statements are used, their results will be combined
|
|
|
|
|
/// with a logical and, meaning all filter conditions must be true to include an element.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlfiltermultiple
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationSort SORT
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{SORT} statement will force a sort of the list of already produced intermediate
|
|
|
|
|
/// results in the current block. @LIT{SORT} allows specifying one or multiple sort criteria and
|
|
|
|
|
/// directions.
|
|
|
|
|
/// The general syntax is:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlsortsyntax
|
|
|
|
|
///
|
|
|
|
|
/// Specifiyng the @LIT{direction} is optional. The default (implict) direction for
|
|
|
|
|
/// a sort is the ascending order. To explicitly specify the sort direction, the keywords
|
|
|
|
|
/// @LIT{ASC} (ascending) and @LIT{DESC} can be used. Multiple sort criteria can be
|
|
|
|
|
/// separated using commas.
|
|
|
|
|
///
|
|
|
|
|
/// Note: when iterating over collection-based lists, the order of documents is always
|
|
|
|
|
/// undefined unless an explicit sort order is defined using @LIT{SORT}.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlsort
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationLimit LIMIT
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{LIMIT} statement allows slicing the list of result documents 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 @LIT{LIMIT} are followed:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqllimitsyntax
|
|
|
|
|
///
|
|
|
|
|
/// The first form allows specifying only the @LIT{count} value whereas the second form
|
|
|
|
|
/// allows specifying both @LIT{offset} and @LIT{count}. The first form is identical using
|
|
|
|
|
/// the second form with an @LIT{offset} value of @LIT{0}.
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{offset} value specifies how many elements from the result shall be discarded.
|
|
|
|
|
/// It must be 0 or greater. The @LIT{count} value specifies how many elements should be
|
|
|
|
|
/// at most included in the result.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqllimit
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationLet LET
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{LET} statement can be used to assign an arbitrary value to a variable.
|
|
|
|
|
/// The variable is then introduced in the scope the @LIT{LET} statement is placed in.
|
|
|
|
|
/// The general syntax is:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlletsyntax
|
|
|
|
|
///
|
|
|
|
|
/// @LIT{LET} statements are mostly used to declare complex computations and to avoid
|
|
|
|
|
/// repeated computations of the same value at multiple parts of a query.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqllet
|
|
|
|
|
///
|
|
|
|
|
/// In the above example, the computation of the number of recommendations is factored
|
|
|
|
|
/// out using a @LIT{LET} statement, thus avoiding computing the value twice in the
|
|
|
|
|
/// @LIT{RETURN} statement.
|
|
|
|
|
///
|
|
|
|
|
/// Another use case for @LIT{LET} is to declare a complex computation in a subquery,
|
|
|
|
|
/// making the whole query more readable.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqllet2
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlOperationCollect COLLECT
|
|
|
|
|
///
|
|
|
|
|
/// The @LIT{COLLECT} keyword can be used to group a list by one or multiple
|
|
|
|
|
/// group criteria.
|
|
|
|
|
/// The two general syntaxes for @LIT{COLLECT} are:
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlcollectsyntax
|
|
|
|
|
///
|
|
|
|
|
/// The first form only groups the result by the defined group criteria defined
|
|
|
|
|
/// by @LIT{expression}. In order to further process the results produced by
|
|
|
|
|
/// @LIT{COLLECT}, a new variable (specified by @LIT{variable-name} is introduced.
|
|
|
|
|
/// This variable contains the group value.
|
|
|
|
|
///
|
|
|
|
|
/// The second form does the same as the first form, but additionally introduces
|
|
|
|
|
/// a variable (specified by @LIT{groups}) that contains all elements that fell into
|
|
|
|
|
/// the group. Specifying the @LIT{INTO} clause is optional-
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlcollect
|
|
|
|
|
///
|
|
|
|
|
/// In the above example, the list of @LIT{users} will be grouped by the attribute
|
|
|
|
|
/// @LIT{city}. The result is a new list of documents, with one element per distinct
|
|
|
|
|
/// @LIT{city} value. The elements from the original list (here: @LIT{users}) per city
|
|
|
|
|
/// are made available in the variable @LIT{g}. This is due to the @LIT{INTO} clause.
|
|
|
|
|
///
|
|
|
|
|
/// @LIT{COLLECT} also allows specifying multiple group criteria. Individual group
|
|
|
|
|
/// criteria can be separated by commas.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlcollect2
|
|
|
|
|
///
|
|
|
|
|
/// In the above example, the list of @LIT{users} is grouped by first names and ages
|
|
|
|
|
/// first, and for each distinct combination of first name and age, the number of
|
|
|
|
|
/// users found is returned.
|
|
|
|
|
///
|
|
|
|
|
/// Note: the @LIT{COLLECT} statement eliminates all local variables in the current
|
|
|
|
|
/// scope. After @LIT{COLLECT} only the variables introduced by @LIT{COLLECT} itself
|
|
|
|
|
/// are available.
|
|
|
|
|
///
|
|
|
|
|
/// @section AqlAdvanced Advanced features
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlSubqueries Subqueries
|
|
|
|
|
///
|
|
|
|
|
/// Whereever an expression is allowed in AQL, a subquery can be placed. A subquery
|
|
|
|
|
/// is a query part that can introduce its own local variables without affecting
|
|
|
|
|
/// variables and values in its outer scope(s).
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlsubquery
|
|
|
|
|
///
|
|
|
|
|
/// @subsection AqlExpansion Variable expansion
|
|
|
|
|
///
|
|
|
|
|
/// In order to access a named attribute from all elements in a list easily,
|
|
|
|
|
/// AQL offers the shortcut operator @LIT{[*]} for variable expansion.
|
|
|
|
|
///
|
|
|
|
|
/// Using the @LIT{[*]} operator with a variable will iterate over all elements
|
|
|
|
|
/// in the variable thus allowing to access a particular attribute of each element.
|
|
|
|
|
/// It is required that the expanded variable is a list.
|
|
|
|
|
/// The result of the @LIT{[*]} operator is again a list.
|
|
|
|
|
///
|
|
|
|
|
/// @verbinclude aqlexpansion
|
|
|
|
|
///
|
|
|
|
|
/// In the above example, the attribute @LIT{name} is accessed for each element
|
|
|
|
|
/// in the list @LIT{u.friends}. The result is a flat list of friend names, made
|
|
|
|
|
/// available as the attribute @LIT{friendNames}.
|
|
|
|
|
////////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
|
|
// Local Variables:
|
|
|
|
|
|
Jan Steemann