[][src]Crate arangors

arangors

Build Status MIT licensed Crates.io arangors

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.

NOTICE

arangors will stay synchronous until the async/await syntax are available in stable channel.

Philosophy of arangors

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

Features

By now, the available features of arangors are:

  • make connection to arangoDB
  • get list of databases and collections
  • full featured AQL query

TODO

  • (Done) Milestone 0.1.x

Synchronous connection based on reqwest and full featured AQL query.

  • (WIP) Milestone 0.2.x

Remove cache behaviour and fix severe bugs in 0.2 that only root user can have access to arangoDB, which impose breaking API changes.

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

Implement both sync and async client.

Glance

Connection

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:

  • With authentication
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();
  • Without authentication, only use in evaluation setting
This example is not tested
use arangors::Connection;
let conn = Connection::establish_without_auth("http://localhost:8529").unwrap();

Database && Collection

use arangors::Connection;

fn main(){
    let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
    let db = conn.db("test_db").unwrap();
    let collection = db.collection("test_collection").unwrap();
}

AQL Query

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.

Typed or Not Typed

Note that results can be strong typed given deserializable struct, or arbitrary JSON object with serde::Value.

  • Arbitrary JSON object
use serde_json::Value;
use arangors::Connection;

let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
let db = conn.db("test_db").unwrap();
let resp: Vec<Value> = db.aql_str("FOR u IN test_collection LIMIT 3 RETURN u").unwrap();
  • Strong typed result
use serde::Deserialize;
use arangors::Connection;

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

let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
let db = conn.db("test_db").unwrap();
let resp: Vec<User> = db.aql_str("FOR u IN test_collection RETURN u").unwrap();

Batch query

arangors offers a way to manually handle batch query.

Fetch All Results

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::Deserialize;
use arangors::Connection;

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

fn main() {
    let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
    let db = conn.db("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.

use arangors::{Connection, Document};
use std::collections::HashMap;
use serde::{Serialize, Deserialize};

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

let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
let db = conn.db("test_db").unwrap();

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).unwrap();
  • aql_query

This function offers all the options available to tweak a AQL query. Users have to construct a AqlQuery object first. And AqlQuery 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;

let conn = Connection::establish_jwt("http://localhost:8529", "username", "password").unwrap();
let database = conn.db("test_db").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);

Contributing

Contributions and feed back are welcome following Github workflow.

License

arangors is provided under the MIT license. See LICENSE. An ergonomic arangoDB client for rust.

Re-exports

pub use crate::collection::Collection;
pub use crate::connection::Connection;
pub use crate::database::Database;
pub use crate::document::Document;
pub use crate::response::Cursor;
pub use crate::response::Error;
pub use crate::response::Response;
pub use crate::response::Success;
pub use crate::aql::AqlOption;
pub use crate::aql::AqlQuery;

Modules

aql
collection
connection

Top level connection object that hold a http client (either synchronous or asynchronous), arango URL, and buffered accessible databases object.

database

database contains all struct and enum pertain to arangoDB "database" level.

document
response