arangors
is an intuitive rust client for arangoDB,
inspired by pyArango.
arangors
enables you to connect with arangoDB server, access to database,
execute AQL query, manage arangoDB in an easy and intuitive way.
arangors
will stay synchronous until the async/await syntax are available in stable channel.
arangors
is targeted at ergonomic, intuitive and OOP-like API for ArangoDB,
both top level and low level API for users' choice.
Overall architecture of arangoDB:
databases -> collections -> documents/edges
In fact, the design of arangors
just mimic this architecture, with a
slight difference that in the top level, there is a connection object on top
of databases, containing a HTTP client with authentication information in
HTTP headers.
Hierarchy of arangors:
connection -> databases(cached) -> collections -> documents/edges
By now, the available features of arangors are:
- make connection to arangoDB
- get list of databases and collections
- full featured AQL query
- (Done) Milestone 0.1.x
Synchronous connection based on reqwest
and full featured AQL query.
- (WIP) Milestone 0.2.x
Fill the unimplemented API in Connection
, Database
, Collection
and Document
.
In this stage, all operations available for database, collection and document should be implemented.
- Milestone 0.3.x
Provides the API related to graph, index and user management.
- Milestone 0.4.x
Abandon reqwest
and implement asynchronous version using hyper
.
And the synchronous version is just a wrapper around async version just like the design of reqwest
.
There is three way to establish connections:
- jwt
- basic auth
- no authentication
So are the arangors
API.
When a connection is successfully established,
arangors
will automatically fetch the structure of arangoDB
by get the list of database, and then lists of collections per database.
Example:
use arangors::Connection;
// (Recommended) Handy functions
let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
let conn =
Connection::establish_basic_auth("http://localhost:8529", "username", "password").unwrap();
let conn = Connection::establish_without_auth("http://localhost:8529")
.unwrap();
use arangors::Connection;
fn main(){
let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
let db = conn.get_database("_system").unwrap();
let collection = db.get_collection("_apps").unwrap();
}
All aql query related functions are associated with database, as AQL query is performed at database level.
There are several way to execute AQL query, and can be categorized into two classes:
-
batch query
aql_query_batch
aql_next_batch
-
query to fetch all results
aql_str
aql_bind_vars
aql_query
This later category provides a convenient high level API, whereas batch query offers more control.
Note that results can be strong typed given deserializable struct, or
arbitrary JSON object with serde::Value
.
- Arbitrary JSON object
let resp: Vec<Value> = database
.aql_str("FOR u IN Collection LIMIT 3 RETURN u")
.unwrap();
- Strong typed result
use serde_derive::Deserialize;
#[derive(Deserialize, Debug)]
struct User {
pub username: String,
pub password: String,
}
let resp: Vec<User> = database.aql_str("FOR u IN users RETURN u").unwrap();
arangors
offers a way to manually handle batch query.
There are three functions for AQL query that fetch all results from ArangoDB. These functions internally fetch batch results one after another to get all results.
The functions for fetching all results are listed as bellow:
-
aql_str
This function only accept a AQL query string.
Here is an example of strong typed query result with
aql_str
:use serde_derive::Deserialize; #[derive(Deserialize, Debug)] struct User { pub username: String, pub password: String, } fn main() { let conn = Connection::establish_jwt(URL, "username", "password").unwrap(); let db = conn.get_database("test_db").unwrap(); let result: Vec<User> = db .aql_str(r#"FOR i in test_collection FILTER i.username=="test2" return i"#) .unwrap(); }
-
aql_bind_vars
This function can be used to start a AQL query with bind variables.
fn main(){ }
-
aql_query
This function offers all the options available to tweak a AQL query. Users have to construct a
AqlQuery
object first. AndAqlQuery
offer all the options needed to tweak AQL query. You can set batch size, add bind vars, limit memory, and all others options available.use arangors::{AqlQuery, Connection, Cursor, Database}; use serde_json::value::Value; fn main() { let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap(); let database = conn.get_database("database").unwrap(); let aql = AqlQuery::new("FOR u IN @@collection LIMIT 3 RETURN u").batch_size(1).count(true).bind_var("collection","test_collection"); let resp: Vec<Value> = database.aql_query(aql).unwrap(); println!("{:?}", resp); }
Contributions and feed back are welcome following Github workflow.
arangors
is provided under the MIT license. See LICENSE.