From 94f19024b138ca89e72a8d4d13dceaebb7b158e9 Mon Sep 17 00:00:00 2001 From: fMeow Date: Thu, 6 Jun 2024 17:58:17 +0800 Subject: [PATCH] doc: update readme --- README.md | 117 ++++++++++++++++++++++++++--------------------------- src/lib.rs | 9 +++-- 2 files changed, 64 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index a0f72b8..83eb02c 100644 --- a/README.md +++ b/README.md @@ -31,23 +31,16 @@ HTTP headers. Hierarchy of arangors: > connection -> databases -> collections -> documents/edges -## Features - -By now, the available features of arangors are: - -- make connection to ArangoDB -- get list of databases and collections -- fetch database and collection info -- create and delete database or collections -- full featured AQL query -- support both `async` and sync - -## Abilities & TODO +## Features & TODO +- [X] make connection to ArangoDB +- [X] get list of databases and collections +- [X] fetch database and collection info +- [X] create and delete database or collections +- [X] full featured AQL query - [X] Synchronous connection based on `reqwest` and full featured AQL query. -- [X] Fill the unimplemented API in `Connection`, `Database`, `Collection` and -`Document`. -- [X] Implement both sync and async client. +- [X] Fill the unimplemented API in `Connection`, `Database`, `Collection` and `Document`. +- [X] support both `async` and sync client - [X] Offers a way to use custom HTTP client ecosystem. - [X] Index Management (since 0.4.3) - [X] Graph Management (since 0.4.5) @@ -61,6 +54,7 @@ You can switch to different HTTP ecosystem with a feature gate, or implement the Client yourself (see examples). Currently out-of-box supported ecosystem are: + - `reqwest_async` - `reqwest_blocking` - `surf_async` @@ -91,6 +85,7 @@ with a feature gate. Arangors adopts async first policy. ### Connection There is three way to establish connections: + - jwt - basic auth - no authentication @@ -106,22 +101,26 @@ use arangors::Connection; // (Recommended) Handy functions let conn = Connection::establish_jwt("http://localhost:8529", "username", "password") - .await - .unwrap(); +.await +.unwrap(); let conn = Connection::establish_basic_auth("http://localhost:8529", "username", "password") - .await - .unwrap(); +.await +.unwrap(); ``` -- Without authentication, only use in evaluation setting +- Without authentication + +**Only use in evaluation setting**. ``` rust, ignore -## use arangors::Connection; +use arangors::Connection; let conn = Connection::establish_without_auth("http://localhost:8529").await.unwrap(); -```rust +``` ## Database && Collection +To get info or operate on database or collections: + ```rust use arangors::Connection; @@ -131,7 +130,8 @@ let collection = db.collection("test_collection").await.unwrap(); ### AQL Query -All [AQL](https://www.arangodb.com/docs/stable/aql/index.html) query related functions are associated with database, as AQL query +All [AQL](https://www.arangodb.com/docs/stable/aql/index.html) 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 @@ -165,14 +165,14 @@ struct User { // Typed let resp: Vec = db - .aql_str("FOR u IN test_collection RETURN u") - .await - .unwrap(); +.aql_str("FOR u IN test_collection RETURN u") +.await +.unwrap(); // Not typed: Arbitrary JSON objects let resp: Vec = db - .aql_str("FOR u IN test_collection RETURN u") - .await - .unwrap(); +.aql_str("FOR u IN test_collection RETURN u") +.await +.unwrap(); ``` #### Batch query @@ -184,13 +184,12 @@ next batch and update cursor with the cursor. ```rust - let aql = AqlQuery::builder() - .query("FOR u IN @@collection LIMIT 3 RETURN u") - .bind_var("@collection", "test_collection") - .batch_size(1) - .count(true) - .build(); +.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(); @@ -199,15 +198,15 @@ println!("count: {:?}", cursor.count); println!("cached: {}", cursor.cached); let mut results: Vec = 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; - } +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); ``` @@ -235,9 +234,9 @@ struct User { } let result: Vec = db - .aql_str(r#"FOR i in test_collection FILTER i.username=="test2" return i"#) - .await - .unwrap(); +.aql_str(r#"FOR i in test_collection FILTER i.username=="test2" return i"#) +.await +.unwrap(); ``` ##### `aql_bind_vars` @@ -256,14 +255,14 @@ struct User { let mut vars = HashMap::new(); let user = User { - username: "test".to_string(), - password: "test_pwd".to_string(), +username: "test".to_string(), +password: "test_pwd".to_string(), }; -vars.insert("user", serde_json::value::to_value(&user).unwrap()); -let result: Vec> = db - .aql_bind_vars(r#"FOR i in test_collection FILTER i==@user return i"#, vars) - .await - .unwrap(); +vars.insert("user", serde_json::value::to_value( & user).unwrap()); +let result: Vec > = db +.aql_bind_vars(r#"FOR i in test_collection FILTER i==@user return i"#, vars) +.await +.unwrap(); ``` ##### `aql_query` @@ -280,11 +279,11 @@ 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(); +.query("FOR u IN @@collection LIMIT 3 RETURN u") +.bind_var("@collection", "test_collection") +.batch_size(1) +.count(true) +.build(); let resp: Vec = db.aql_query(aql).await.unwrap(); println!("{:?}", resp); diff --git a/src/lib.rs b/src/lib.rs index bc50365..fae493e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -107,15 +107,19 @@ //! # } //! ``` //! -//! - Without authentication, only use in evaluation setting +//! - Without authentication +//! +//! **Only use in evaluation setting**. //! //! ``` rust, ignore -//! # use arangors::Connection; +//! use arangors::Connection; //! let conn = Connection::establish_without_auth("http://localhost:8529").await.unwrap(); //! ``` //! //! ## Database && Collection //! +//! To get info or operate on database or collections: +//! //! ```rust //! use arangors::Connection; //! @@ -206,7 +210,6 @@ //! # .await //! # .unwrap(); //! # let db = conn.db("test_db").await.unwrap(); -//! //! let aql = AqlQuery::builder() //! .query("FOR u IN @@collection LIMIT 3 RETURN u") //! .bind_var("@collection", "test_collection")