AQL Syntax AQL 语法
Query types, whitespace, comments, keywords, and names in the AQL language explained
AQL 语言中的查询类型、空格、注释、关键字和名称已说明
Query types 查询类型
An AQL query must either return a result (indicated by usage of the RETURN
keyword) or execute a data-modification operation (indicated by usage
of one of the keywords INSERT
, UPDATE
, REPLACE
, REMOVE
or UPSERT
). The AQL
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.
AQL 查询必须返回结果(通过 RETURN
使用关键字来指示)或执行数据修改操作(通过使用关键字 INSERT
、 UPDATE
、 REPLACE
REMOVE
或 UPSERT
来指示)。如果 AQL 分析器在同一查询中检测到多个数据修改操作,或者无法确定查询是数据检索还是修改操作,则 AQL 分析器将返回错误。
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.
AQL 只允许单个查询字符串中的一个查询;因此,不允许使用分号来指示一个查询的结束和分隔多个查询(如 SQL 中所示)。
Whitespace 空白
Whitespace (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 whitespace. Whitespace within strings or names must be enclosed
in quotes in order to be preserved.
可以在查询文本中使用空格(空格、回车符、换行符和制表位)以提高其可读性。标记必须由任意数量的空格分隔。字符串或名称中的空格必须用引号括起来才能保留。
Comments 评论
Comments can be embedded at any position in a query. The text contained in the
comment is ignored by the AQL parser.
注释可以嵌入到查询中的任何位置。AQL 分析器将忽略注释中包含的文本。
Multi-line comments cannot be nested, which means subsequent comment starts within
comments are ignored, comment ends will end the comment.
多行注释不能嵌套,这意味着注释中开始的后续注释将被忽略,注释结束将结束注释。
AQL supports two types of comments:
AQL 支持两种类型的注释:
- Single line comments: These start with a double forward slash and end at
the end of the line, or the end of the query string (whichever is first).
单行注释:它们以双正斜杠开头,以行尾或查询字符串末尾(以先到者为准)结束。 - Multi line comments: These start with a forward slash and asterisk, and
end with an asterisk and a following forward slash. They can span as many
lines as necessary.
多行注释:它们以正斜杠和星号开头,以星号和后面的正斜杠结尾。它们可以根据需要跨越任意数量的行。
/* this is a comment */ RETURN 1
/* these */ RETURN /* are */ 1 /* multiple */ + /* comments */ 1
/* this is
a multi line
comment */
// a single line comment
Keywords 关键字
On the top level, AQL offers the following
high-level operations:
在顶层,AQL 提供以下高级操作:
Operation 操作 | Description 描述 |
---|---|
FOR | Array iteration 数组迭代 |
RETURN | Results projection 成果预测 |
FILTER | Non-View results filtering 非查看结果筛选 |
SEARCH | View results filtering 查看结果筛选 |
SORT | Result sorting 结果排序 |
LIMIT | Result slicing 结果切片 |
LET | Variable assignment 变量赋值 |
COLLECT | Result grouping 结果分组 |
WINDOW | Aggregations over related rows 相关行的聚合 |
INSERT | Insertion of new documents 插入新文件 |
UPDATE | (Partial) update of existing documents (部分)更新现有文件 |
REPLACE | Replacement of existing documents 替换现有文件 |
REMOVE | Removal of existing documents 删除现有文档 |
UPSERT | Insertion of new or update of existing documents 插入新的文件或更新现有文件 |
WITH | Collection declaration 收款声明 |
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.
上述每个操作都可以使用同名关键字在查询中启动。AQL 查询可以(并且通常确实)包含上述多个操作。
An example AQL query may look like this:
示例 AQL 查询可能如下所示:
FOR u IN users
FILTER u.type == "newbie" && u.active == true
RETURN u.name
In this example query, the terms FOR
, FILTER
, and RETURN
initiate the
higher-level operation according to their name. These terms are also keywords,
meaning that they have a special meaning in the language.
在此示例中,查询术语 FOR
、 FILTER
和 RETURN
根据其名称启动更高级别的操作。这些术语也是关键字,这意味着它们在语言中具有特殊的含义。
For example, the query parser will use the keywords to find out which high-level
operations to execute. That also means keywords can only be used at certain
locations in a query. This also makes all keywords reserved words that must
not be used for other purposes than they are intended for.
例如,查询分析器将使用关键字来找出要执行的高级操作。这也意味着关键字只能在查询中的某些位置使用。这也使所有关键字成为保留词,不得用于预期目的以外的其他目的。
For example, it is not possible to use a keyword as literal unquoted string
(identifier) for a collection or attribute name. If a collection or attribute
needs to have the same name as a keyword, then the collection or attribute name
needs to be quoted in the query (also see Names).
例如,不能将关键字用作集合或属性名称的文本不带引号的字符串(标识符)。如果集合或属性需要与关键字同名,则需要在查询中引用集合或属性名称(另请参阅名称)。
Keywords are case-insensitive, meaning they can be specified in lower, upper, or
mixed case in queries. In this documentation, all keywords are written in upper
case to make them distinguishable from other query parts.
关键字不区分大小写,这意味着可以在查询中以小写、大写或混合大小写指定它们。在本文档中,所有关键字都以大写形式编写,以便与其他查询部分区分开来。
There are a few more keywords in addition to the higher-level operation keywords.
Additional keywords may be added in future versions of ArangoDB.
The complete list of keywords is currently:
除了更高级别的操作关键字之外,还有一些关键字。在ArangoDB的未来版本中可能会添加其他关键字。目前,关键字的完整列表如下:
AGGREGATE
ALL
ALL_SHORTEST_PATHS
AND
ANY
ASC
COLLECT
DESC
DISTINCT
FALSE
FILTER
FOR
GRAPH
IN
INBOUND
INSERT
INTO
K_PATHS
K_SHORTEST_PATHS
LET
LIKE
LIMIT
NONE
NOT
NULL
OR
OUTBOUND
REMOVE
REPLACE
RETURN
SHORTEST_PATH
SORT
TRUE
UPDATE
UPSERT
WINDOW
WITH
On top of that, there are a few words used in language constructs which are not
reserved keywords. You can use them as collection or attribute names
without having to quote them. The query parser can identify them as keyword-like
based on the context:
最重要的是,语言结构中使用了一些不是保留关键字的词。您可以将它们用作集合或属性名称,而无需引用它们。查询解析器可以根据上下文将它们标识为类似关键字:
KEEP
– COLLECT operation variant
KEEP
– COLLECT 操作变体COUNT
(WITH COUNT INTO
) – COLLECT operation variant
COUNT
(WITH COUNT INTO
) – COLLECT 操作变体OPTIONS
– FOR / Graph Traversal / SEARCH / COLLECT / INSERT / UPDATE / REPLACE / UPSERT / REMOVE operation
OPTIONS
– FOR / 图形遍历 / 搜索 / 收集 / 插入 / 更新 / 替换 / 更新 / 删除 操作PRUNE
– Graph Traversal, FOR operation variant
PRUNE
– 图形遍历,FOR 操作变体SEARCH
– SEARCH operation
SEARCH
– 搜索操作TO
– Shortest Path / All Shortest Paths / k Shortest Paths / k Paths graph traversal
TO
– 最短路径 / 所有最短路径 / 最短路径 / 绘制遍历路径
Last but not least, there are special variables which are available in certain
contexts. Unlike keywords, they are case-sensitive:
最后但并非最不重要的一点是,在某些情况下可以使用特殊变量。与关键字不同,它们区分大小写:
CURRENT
– available in array inline expressions
CURRENT
– 在数组内联表达式中可用NEW
– available after INSERT / UPDATE / REPLACE / UPSERT operation
NEW
– 在插入/更新/替换/UPSERT操作后可用OLD
– available after UPDATE / REPLACE / UPSERT / REMOVE operation
OLD
– 在更新/替换/更新插入/删除操作后可用
If you define a variable with the same name in the same scope, then its value
will be and remain at what you set it to. Hence you need to avoid these names
for your own variables if you want to access the special variable values.
如果在同一作用域中定义具有相同名称的变量,则其值将保持为设置的值。因此,如果要访问特殊变量值,则需要避免使用这些名称作为自己的变量。
Names 名字
In general, names are used to identify the following things in AQL queries:
通常,名称用于标识 AQL 查询中的以下内容:
- collections 收集
- attributes 属性
- variables 变量
- functions 功能
Names in AQL are always case-sensitive.
The maximum supported length for collection/View names is 256 bytes.
Variable names can be longer, but are discouraged.
AQL 中的名称始终区分大小写。集合/视图名称支持的最大长度为 256 字节。变量名称可以更长,但不建议使用。
Keywords should not be used as names. If you want to use a reserved keyword as
name anyway, the name must be enclosed in backticks or forward ticks. This is referred to as quoting.
关键字不应用作名称。如果无论如何都想使用保留关键字作为名称,则必须将名称括在反引号或正引号中。这称为引用。
FOR doc IN `filter`
RETURN doc.`sort`
Due to the backticks, filter
and sort
are interpreted as names and not as
keywords here.
由于反引号, filter
sort
在这里被解释为名称而不是关键字。
You can also use forward ticks:
您还可以使用正向刻度:
FOR f IN ´filter´
RETURN f.´sort´
Instead of ticks, you may use the bracket notation for the attribute access:
您可以使用括号表示法来代替刻度,以表示属性访问:
FOR f IN `filter`
RETURN f["sort"]
sort
is a string literal in quote marks in this alternative and does thus not
conflict with the reserved keyword.
sort
是此替代项中带引号的字符串文本,因此与保留关键字不冲突。
Quoting with ticks is also required if certain characters such as
hyphen minus (-
) are contained in a name, namely if they are used for
operators in AQL:
如果名称中包含某些字符(例如连字符减号 ( -
),则还需要用刻度引号,即如果它们用于 AQL 中的运算符:
LET `my-var` = 42
Collection names 集合名称
You can typically use collection names in queries as they are. If a collection
happens to have the same name as a keyword, the name must be enclosed in
backticks or forward ticks.
通常可以在查询中按原样使用集合名称。如果集合恰好与关键字同名,则必须将该名称括在反引号或正向勾号中。
Quoting with ticks is also required if special characters such as
hyphen minus (-
) are contained in a collection name:
如果集合名称中包含连字符减号 ( -
) 等特殊字符,则还需要用勾号引号:
FOR doc IN `my-coll`
RETURN doc
The collection my-coll
has a dash in its name, but -
is an arithmetic
operator for subtraction in AQL. The backticks quote the collection name to
refer to the collection correctly.
该集合 my-coll
的名称中有一个破折号,但它 -
是 AQL 中用于减法的算术运算符。反引号引用集合名称以正确引用集合。
If you use extended collection and View names
(--database.extended-names
startup option),
they may contain spaces, or non-ASCII characters such as Japanese or Arabic
letters, emojis, letters with accentuation, and other UTF-8 characters.
Quoting is required in these cases, too:
如果使用扩展集合和视图名称( --database.extended-names
启动选项),它们可能包含空格或非 ASCII 字符,例如日语或阿拉伯语字母、表情符号、带重音的字母和其他 UTF-8 字符。在以下情况下也需要引用:
FOR doc IN ´🥑~колекція =)´
RETURN doc
The collection name contains characters that are allowed using the extended
naming constraints and is quoted with forward ticks.
集合名称包含允许使用扩展命名约束的字符,并用正向刻度符引出引号。
Note that quoting the name with "
or '
is not possible for collections as
they cannot be string literals in quote marks.
请注意,对于集合,不能用 "
或 '
来引用名称,因为它们不能是带引号的字符串文本。
For information about the naming constraints for collections, see
Collection names.
有关集合的命名约束的信息,请参阅集合名称。
Attribute names 属性名称
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 may be used in a query. To avoid any ambiguity, it is not
allowed to refer to an unqualified attribute name.
引用集合中文档的属性时,必须使用完全限定的属性名称。这是因为在查询中可能会使用具有不明确属性名称的多个集合。为避免任何歧义,不允许引用非限定属性名称。
Also see the naming restrictions for
Attribute names.
另请参阅属性名称的命名限制。
FOR u IN users
FOR f IN friends
FILTER u.active == true && f.active == true && u.id == f.userId
RETURN u.name
In the above example, the attribute names active
, name
, id
, and userId
are qualified using the collection names they belong to (u
and f
respectively).
在上面的示例中,属性名称 active
、 name
id
和 userId
分别使用它们所属的集合名称 ( u
和 f
)进行限定。
Variable names 变量名称
AQL allows you to assign values to additional variables in a query.
All variables that are assigned a value must have a name that is unique within
the context of the query.
AQL 允许您为查询中的其他变量赋值。分配了值的所有变量都必须具有在查询上下文中唯一的名称。
FOR u IN users
LET friends = u.friends
RETURN { "name" : u.name, "friends" : friends }
In the above query, users
is a collection name, and both u
and friends
are
variable names. This is because the FOR
and LET
operations need target
variables to store their intermediate results.
在上面的查询中, users
是一个集合名称,并且两个 u
和 friends
都是变量名称。这是因为 FOR
和 LET
操作需要目标变量来存储其中间结果。
Variable names should be different from the names of any collection name used in
the same query to avoid shadowing, which can render a collection with the same
name inaccessible in the query after the variable assignment:
变量名称应与同一查询中使用的任何集合名称的名称不同,以避免阴影,这可能导致变量赋值后查询中无法访问具有相同名称的集合:
LET users = []
FOR u IN users // iterates over the "users" variable, not the "users" collection
RETURN u
Allowed characters in variable names are the letters a
to z
(both in lower
and upper case), the numbers 0
to 9
, the underscore (_
) symbol and the
dollar ($
) sign. A variable name must not start with a number. If a variable
name starts with one or multiple underscore characters, the underscore(s) must
be followed by least one letter (a-z or A-Z). The dollar sign can only be used
as the very first character in a variable name and must be followed by a letter.
变量名称中允许的字符是字母 a
to z
(小写和大写)、数字 0
、 9
下划线 ( _
) 符号和美元 ( $
) 符号。变量名称不得以数字开头。如果变量名称以一个或多个下划线字符开头,则下划线后必须至少跟一个字母(a-z 或 A-Z)。美元符号只能用作变量名称中的第一个字符,并且后面必须跟一个字母。