1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278
//! # arangors //! //! [](https://travis-ci.org/Guoli-Lyu/arangors) //! [](./LICENSE) //! [](https://crates.io/crates/arangors) //! [](https://docs.rs/arangors) //! //! `arangors` is an intuitive rust client for [arangoDB](https://www.arangodb.com/), //! inspired by [pyArango](https://github.com/tariqdaouda/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 //! //! ```rust //! 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 //! //! ``` rust, ignore //! use arangors::Connection; //! let conn = Connection::establish_without_auth("http://localhost:8529").unwrap(); //! ``` //! //! ### Database && Collection //! //! ```rust //! 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 //! //! ```rust //! 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 //! //! ```rust //! 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`: //! //! ```rust //! 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. //! //! ```rust //! 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. //! //! ```rust //! 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](./LICENSE). //! An ergonomic [arangoDB](https://www.arangodb.com/) client for rust. pub mod aql; pub mod collection; pub mod connection; pub mod database; pub mod document; mod query; pub mod response; 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;