ArangoDB 学习笔记（二）AQL Java API | AQL语法 | 使用Java连接ArangoDB

参考资料

ArangoDB 官方网址

ArangoDB 驱动程序是编程语言和 ArangoDB 之间的接口，它使程序员能够从本地语言程序中连接和操作 ArangoDB 部署。

从语言的角度来看，文档和数据库结构可以与数据类型及其方法集成。

一、ArangoDB Java Driver 支持的不同类型

---

1.1 BaseDocument

根据之前的学习我们知道，ArangoDB数据库里存储的文档的属性和值是没有要求的，除了_id ，_key，_rev 系统属性以外，Edge集合里必须有 _from 和 _to 。
那么我们在使用Java操作ArangoDB时，如何解决检索到的集合列表，属性和值各不相同的问题呢？
官方提供的解决：查看文档
这些问题可以使用BaseDocument类来解决，该类实现代码如下：

public class BaseDocument{
   
    String id;			// _id , 文档ID
    String key;			// _key, 文档的关键词
    String revision;	// _rev, 版本号
    Map<String, Object> properties;	// 非系统的任意属性
}

在 properties中，映射可包含以下类型的值：

Map<String, Object>
List<Object>
Boolean
Number
String
null

注：Map 和 List 都包括上面列出的类型相同的对象，即支持嵌套。

官方案例： 从myCollection集合中获取文档myDocumentKey

ArangoDB.Builder arango = new ArangoDB.Builder().builder();

DocumentEntity<BaseDocument> myObject = 
    arango
        .db()
        .collection("myCollection")
        .getDocument("myDocumentKey", BaseDocument.class);

1.2 XML

从 3.1.0 版开始，arangodb-java-driver 支持写入、读取和查询包含 JSON 文档的原始字符串。

使用JsonML，您可以将 XML 字符串转换为 JSON 字符串并再次转换回 XML。

这里暂时没有用到，先不做扩展，可参考官方文档：官方文档

1.3 Graph

arangodb-java-driver支持对图形的每个顶点和边集合使用 批量导入函数来导入图形数据。
这里因为暂时没有用到，先不做扩展， 可参考官方文档：官方文档

二、AQL

---

参考文档：官方文档

ArangoDB 查询语言 (AQL) 可用于检索和修改存储在 ArangoDB 中的数据。
执行查询时候的步骤如下图：

AQL 主要是一种声明性语言，意味着查询表达了应该实现的结果，而不是应该如何实现。除此之外，它有两个设计目标：

• 客户端独立性，无论哪种客户端使用哪种编程语言，所有客户端的语言和语法都相同。
• 支持复杂的查询模式和 ArangoDB提供的不同数据模型

AQL 的特点：

• 类似于结构化查询语言（SQL）
• 支持读取和修改集合数据，但不支持数据定义操作，如创建和删除数据库、集合和索引
• 属于纯数据操作语言（DML），而不是数据定义语言（DDL）和数据控制语言（DCL）

2.1 AQL 语法

参考官方文档：官方文档

2.1.1 查询

AQL 查询必须返回结果（通过 RETURN关键字返回）或执行数据修改操作（通过关键字 INSERT、UPDATE、REPLACE或 REMOVE来指示 UPSERT。

AQL 只允许在单个查询字符中进行一个查询；因此，分号表示一个查询的结束和分隔多个查询是不允许的。

2.1.2 空白

AQL支持在查询文本中使用空格（空格、回车、换行和制表位）以提高其可读性。标记必须由任意数量的空格分隔。字符串或名称中的空格必须用引号括起来才能保留。

2.1.3 注释

AQL支持将注释嵌入查询中的任何位置。
单行注释：和Java一样，// 开头，并在行尾或查询字符串的结尾结束。

1) // 注释
2) RETURN 1 // 注释

多行注释：以 /* 开头，以 */结尾，不支持嵌套，但可以嵌入在任意位置

1) /* 注释 */ RETURN 1

2) /* 注释1 */ RETURN /* 注释2 */ 1 

3) /* 多行注释开始
    ...
   多行注释结束 */   
   

2.1.4 *AQL语法关键词

AQL所支持的语法以及描述如下表：

序号	关键词	描述
1	FOR	遍历数组
2	RETURN	返回结果
3	FILTER	过滤结果，用于条件查询
4	SEARCH	查询过滤后的结果
5	SORT	对结果进行排序
6	LIMITE	对结果进行切片，分割
7	LET	变量赋值
8	COLLECT	结果分组
9	WINDOW	相关行的聚合
10	INSERT	插入新的文档
11	UPDATE	更新现有文档
12	REPLACE	替换现有的文档
13	REMOVE	删除现有文档
14	UPSERT	插入新文档或更新现有文档
15	WITH	集合说明

上面每一个操作都支持在查询中嵌套，比如支持双重 FOR ，假如文档存储里的属性是一个嵌套列表，可轻松地实现遍历。还有其他的一些关键字可参考：官方文档

关键字的特点：

• 不区分大小写
• 支持被转义，这意味着变量里可以使用关键字表示

2.1.5 名称

通常，AQL查询中包含的名称标识由：

• 集合
• 属性
• 变量
• 函数

AQL中的名称区分大小写，collections 跟 view 的名称最大长度为 256 Byte，变量名长度可超过256Byte，但不推荐。
关键字不得用于名称，如果要用关键字就需要使用反引号或正括号括起来，如：

FOR doc IN `filter`
  RETURN doc.`sort`
  
FOR doc IN `filter`
  RETURN f["sort"]

若名称中包含连字符减号、括号等特殊字符，则也需要转义：

FOR doc IN `my-coll`
  RETURN doc

1. 集合名称

集合名称可以直接在AQL语句中使用，但如果集合名和关键字相同，那么必须用双引号括起来
注：AQL 限制在一个AQL查询中最多使用 256 个集合，这个限制适用于所有涉及文档和边集合的总和。

2. 属性名称

当引用集合中文档的属性时，必须使用完全限定的属性名称，防止在嵌套查询中出现歧义，如：

FOR u IN users
  FOR f IN friends
    FILTER u.active == true && f.active == true && u.id == f.userId
    RETURN u.name

其中 u 和 f 必须指明。

3. 变量名

AQL允许用户将值分配给其他的变量，变量名不允许在查询上下文中重复，且必须与查询中使用的任何集合名称都不同。
官方使用例子：

FOR u IN users
  LET friends = u.friends
  RETURN { "name" : u.name, "friends" : friends }

变量名中允许的字符：

• 字母 A~Z 和 a~z
• 数字 0 ~ 9
• 下划线 _ 、美元 $

变量名中的规则：

1. 变量名不能以数字开头：

• 反例：1name、5test
• 正例：name、test

2. 变量名若以下划线_开头，那么后面至少跟一个字母

• 反例：_1test、_2name
• 正例：_test、_name

3. 变量名中的美元符号 $ 只能用作变量名中的第一个字符，并且后面必须跟字母

• 反例：test$、$1test、te$st
• 正例：$test、$test1

2.2 数据类型

AQL 支持仅由一个值组成的原始数据类型和多个值组成的符合数据类型，可用类型有：

序号	数据类型	描述
1	null	空值，没有值
2	boolean	true / false
3	number	数字
4	string	UTF-8编码的文本
5	array / list	序列，通过位置下标引用
6	object / document	序列，通过对象的名称引用

更多请参考：https://www.arangodb.com/docs/stable/aql/fundamentals-data-types.html

2.3 绑定参数

AQL 支持使用绑定参数，因此允许将查询文本与查询中使用的文字值分开，可有效防止SQL注入攻击。
语法：

• @，单个@表示替换查询中的值
• @@，双个@通常表示对某个集合的绑定，第二个@则是集合参数的一部分

语法规则：

• 绑定参数名称必须以英文字母或数字开头，并且后面可以跟任何字母、数字或下划线。

例如：

// 错误的
FILTER u.name = "@name"
FOR doc IN