arangors lite

arangors_lite 是由 fMeow 的 arangors 衍生而来。

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

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

arangors 的哲学

arangors 针对的是 ArangoDB 的舒适、直观且类似 OOP 的 API，提供顶级和底层 API 供用户选择。

ArangoDB 的整体架构

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

实际上，arangors 的设计就是模仿这种架构，只是在顶级上，有一个数据库连接对象，包含一个带有身份验证信息的 HTTP 客户端。

arangors 的层次结构

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

功能

到目前为止，arangors 提供的功能有

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

概览

使用异步或同步代码

[dependencies]
## This one is async
arangors_lite = { version = "0.2" }
## This one is synchronous
arangors_lite = { version = "0.2", features = ["blocking"] }

由于 maybe_async，arangors 可以统一同步和异步 API，并通过特性门进行切换。Arangors 采用异步优先策略。

默认情况下，reqwest 使用 OpenSSL。要使用 rustls，您可能需要禁用默认特性并使用 rustls 特性。

[dependencies]
## This one uses openssl
arangors_lite = { version = "0.2" }
## This one rustls
arangors_lite = { version = "0.2", features = ["rustls"], default-features = false }

连接

建立连接有三种方式

• jwt
• 基本认证
• 无认证

arangors API 也是如此。

示例

• 带有认证

use arangors_lite::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();

• 无认证，仅在评估设置中使用

let conn = Connection::establish_without_auth("https://127.0.0.1:8529").await.unwrap();

数据库 && 集合

use arangors_lite::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::new("FOR u IN @@collection LIMIT 3 RETURN u")
    .bind_var("@collection", "test_collection")
    .batch_size(1)
    .count(true);

// 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_lite::{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_lite::{AqlQuery, Connection, Cursor, Database};
use serde_json::value::Value;


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

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

贡献

欢迎遵循 Github 工作流程进行贡献和反馈。

许可证

arangors 在 MIT 许可证下提供。请参阅 LICENSE。Rust 的一个符合人体工程学的 ArangoDB 客户端。