arangors

arangors 是一个直观的 ArangoDB Rust 客户端，受 ArangoDB 启发，并借鉴了 pyArango。

arangors 允许您连接到 ArangoDB 服务器，访问数据库，执行 AQL 查询，并以简单直观的方式管理 ArangoDB，支持您所喜爱的任何 HTTP 生态系统中的异步和同步代码。

arangors 的哲学

arangors 致力于为 ArangoDB 提供舒适、直观且类似 OOP 的 API，提供顶级和低级 API 以供用户选择。

ArangoDB 的整体架构

数据库 -> 集合 -> 文档/边

实际上，arangors 的设计仅模仿了这种架构，略有不同的是在顶级，有一个数据库对象，其中包含带有身份验证信息的 HTTP 客户端。

arangors 的层次结构

连接 -> 数据库 -> 集合 -> 文档/边

功能

到目前为止，arangors 可用的功能包括

• 连接到 ArangoDB
• 获取数据库和集合列表
• 获取数据库和集合信息
• 创建和删除数据库或集合
• 功能齐全的 AQL 查询
• 支持异步和同步

待办事项

• (完成) 里程碑 0.1.x

  • 基于 reqwest 的同步连接和功能齐全的 AQL 查询。

• (X) 里程碑 0.2.x

  填充 Connection、Database、Collection 和 Document 中的未实现 API。

  • 在此阶段，应实现数据库、集合和文档的所有操作。

  好吧，我太懒了，不想填充所有 API，因为 AQL 语法在大多数情况下就足够了。也许在 0.4.x 中完成这个目标。

• (完成) 里程碑 0.3.x

  • 实现了同步和异步客户端。还提供了一种使用自定义 HTTP 客户端生态系统的方法。

• (完成) 里程碑 1.0.x

  提供以下 API 相关内容

  • 索引管理（自 0.4.3 起）
  • 图管理（自 0.4.5 起）
  • 用户管理（自 0.5.4 起）

  在此阶段，应实现数据库、集合和文档的所有操作。

概览

使用不同的HTTP生态系统，无论同步还是异步

您可以通过功能门切换到不同的HTTP生态系统，或者自己实现客户端（请参阅示例）。

目前支持的原生生态系统包括

• reqwest_async
• reqwest_blocking
• surf_async

默认情况下，arangors 使用 reqwest_async 作为连接到 ArangoDB 的底层 HTTP 客户端。您可以在功能门中切换到其他生态系统

[dependencies]
arangors = { version = "0.4", features = ["surf_async"], default-features = false }

或者如果您想坚持使用功能门中没有列出的其他生态系统，您可以使用没有任何 HTTP 客户端依赖的纯 arangors

[dependencies]
## This one is async
arangors = { version = "0.4", default-features = false }
## This one is synchronous
arangors = { version = "0.4", features = ["blocking"], default-features = false }

多亏了 maybe_async，arangors 可以统一同步和异步 API，并通过功能门切换。Arangors 采用了异步优先策略。

连接

建立连接有三种方式

• jwt
• 基本认证
• 无认证

因此，arangors API 也是如此。

示例

• 带有认证

use arangors::Connection;

// (Recommended) Handy functions
let conn = Connection::establish_jwt("https://127.0.0.1:8529", "username", "password")
    .await
    .unwrap();
let conn = Connection::establish_basic_auth("https://127.0.0.1:8529", "username", "password")
    .await
    .unwrap();

• 无认证，仅用于评估设置

## use arangors::Connection;
let conn = Connection::establish_without_auth("https://127.0.0.1:8529").await.unwrap();
```rust

## Database && Collection

```rust
use arangors::Connection;

let db = conn.db("test_db").await.unwrap();
let collection = db.collection("test_collection").await.unwrap();

AQL 查询

AQL 相关的所有函数都与数据库相关联，因为 AQL 查询是在数据库级别执行的。

执行 AQL 查询有多种方式，可以分为两大类

• 带有游标的批量查询

  • aql_query_batch
  • aql_next_batch

• 查询以获取所有结果

  • aql_str
  • aql_bind_vars
  • aql_query

这些后者提供方便的高级 API，而批量查询则提供更多控制。

有类型或无类型

请注意，从 ArangoDB 服务器获取的结果，例如获取的文档，可以给定可反序列化的结构体或任意 JSON 对象（使用 serde::Value）进行强类型处理。

#[derive(Deserialize, Debug)]
struct User {
    pub username: String,
    pub password: String,
}

// Typed
let resp: Vec<User> = db
    .aql_str("FOR u IN test_collection RETURN u")
    .await
    .unwrap();
// Not typed: Arbitrary JSON objects
let resp: Vec<serde_json::Value> = db
    .aql_str("FOR u IN test_collection RETURN u")
    .await
    .unwrap();

批量查询

arangors 提供了一种手动处理批量查询的方法。

使用 aql_query_batch 获取游标，然后使用 aql_next_batch 获取下一批结果并使用游标更新游标。

let aql = AqlQuery::builder()
    .query("FOR u IN @@collection LIMIT 3 RETURN u")
    .bind_var("@collection", "test_collection")
    .batch_size(1)
    .count(true)
    .build();

// fetch the first cursor
let mut cursor = db.aql_query_batch(aql).await.unwrap();
// see metadata in cursor
println!("count: {:?}", cursor.count);
println!("cached: {}", cursor.cached);
let mut results: Vec<serde_json::Value> = Vec::new();
loop {
    if cursor.more {
        let id = cursor.id.unwrap().clone();
        // save data
        results.extend(cursor.result.into_iter());
        // update cursor
        cursor = db.aql_next_batch(id.as_str()).await.unwrap();
    } else {
        break;
    }
}
println!("{:?}", results);

获取所有结果

AQL 查询有三个函数可以获取 ArangoDB 中的所有结果。这些函数内部依次获取批量结果，以获取所有结果。

以下是获取所有结果的函数

aql_str

此函数只接受 AQL 查询字符串。

以下是一个使用 aql_str 的强类型查询结果的示例

#[derive(Deserialize, Debug)]
struct User {
    pub username: String,
    pub password: String,
}

let result: Vec<User> = db
    .aql_str(r#"FOR i in test_collection FILTER i.username=="test2" return i"#)
    .await
    .unwrap();

aql_bind_vars

此函数可以用于使用绑定变量启动 AQL 查询。

use arangors::{Connection, Document};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    pub username: String,
    pub password: String,
}


let mut vars = HashMap::new();
let user = User {
    username: "test".to_string(),
    password: "test_pwd".to_string(),
};
vars.insert("user", serde_json::value::to_value(&user).unwrap());
let result: Vec<Document<User>> = db
    .aql_bind_vars(r#"FOR i in test_collection FILTER i==@user return i"#, vars)
    .await
    .unwrap();

aql_query

此函数提供了调整 AQL 查询的所有选项。用户必须首先构造一个 AqlQuery 对象。然后 AqlQuery 提供了调整 AQL 查询所需的所有选项。您可以设置批量大小、添加绑定变量、限制内存以及所有其他可用的选项。

use arangors::{AqlQuery, Connection, Cursor, Database};
use serde_json::value::Value;


let aql = AqlQuery::builder()
    .query("FOR u IN @@collection LIMIT 3 RETURN u")
    .bind_var("@collection", "test_collection")
    .batch_size(1)
    .count(true)
    .build();

let resp: Vec<Value> = db.aql_query(aql).await.unwrap();
println!("{:?}", resp);

贡献

欢迎按照 Github 工作流程提交贡献和反馈。

许可

arangors 在 MIT 许可下提供。请参阅 LICENSE。一个适用于 Rust 的舒适 ArangoDB 客户端。

许可：MIT