{"id":13636903,"url":"https://github.com/fMeow/arangors","last_synced_at":"2025-04-19T08:33:30.956Z","repository":{"id":43253885,"uuid":"147610256","full_name":"fMeow/arangors","owner":"fMeow","description":"Easy to use rust driver for arangoDB","archived":false,"fork":false,"pushed_at":"2024-08-21T10:38:03.000Z","size":759,"stargazers_count":128,"open_issues_count":13,"forks_count":28,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-11-09T06:38:55.592Z","etag":null,"topics":["arangodb","arangodb-client","nosql","rust","rust-library"],"latest_commit_sha":null,"homepage":"https://docs.rs/arangors","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fMeow.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-09-06T03:05:57.000Z","updated_at":"2024-11-03T15:01:50.000Z","dependencies_parsed_at":"2022-09-02T00:22:03.510Z","dependency_job_id":"fc3a1496-a69b-4cf3-8c14-b1cbbd848abd","html_url":"https://github.com/fMeow/arangors","commit_stats":{"total_commits":489,"total_committers":15,"mean_commits":32.6,"dds":"0.34355828220858897","last_synced_commit":"420dcb114716cc0ceccac2960a8c3eabdc3c6e99"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fMeow%2Farangors","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fMeow%2Farangors/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fMeow%2Farangors/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fMeow%2Farangors/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fMeow","download_url":"https://codeload.github.com/fMeow/arangors/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249650484,"owners_count":21306017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["arangodb","arangodb-client","nosql","rust","rust-library"],"created_at":"2024-08-02T00:01:07.172Z","updated_at":"2025-04-19T08:33:30.685Z","avatar_url":"https://github.com/fMeow.png","language":"Rust","funding_links":[],"categories":["Libraries","库 Libraries","Rust"],"sub_categories":["Database","数据库 Database"],"readme":"![Maintenance](https://img.shields.io/badge/maintenance-activly--developed-brightgreen.svg)\n\n# arangors\n\n[![Build Status](https://github.com/fMeow/arangors/workflows/CI%20%28Linux%29/badge.svg?branch=main)](https://github.com/fMeow/arangors/actions)\n[![MIT licensed](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)\n[![Crates.io](https://img.shields.io/crates/v/arangors.svg)](https://crates.io/crates/arangors)\n[![arangors](https://docs.rs/arangors/badge.svg)](https://docs.rs/arangors)\n\n`arangors` is an intuitive rust client for [ArangoDB](https://www.arangodb.com/),\ninspired by [pyArango](https://github.com/tariqdaouda/pyArango).\n\n`arangors` enables you to connect with ArangoDB server, access to database,\nexecute AQL query, manage ArangoDB in an easy and intuitive way,\nboth `async` and plain synchronous code with any HTTP ecosystem you love.\n\n## Philosophy of arangors\n\n`arangors` is targeted at ergonomic, intuitive and OOP-like API for\nArangoDB, both top level and low level API for users' choice.\n\nOverall architecture of ArangoDB:\n\n\u003e databases -\u003e collections -\u003e documents/edges\n\nIn fact, the design of `arangors` just mimic this architecture, with a\nslight difference that in the top level, there is a connection object on top\nof databases, containing a HTTP client with authentication information in\nHTTP headers.\n\nHierarchy of arangors:\n\u003e connection -\u003e databases -\u003e collections -\u003e documents/edges\n\n## Features \u0026 TODO\n\n- [X] make connection to ArangoDB\n- [X] get list of databases and collections\n- [X] fetch database and collection info\n- [X] create and delete database or collections\n- [X] full featured AQL query\n- [X] Synchronous connection based on `reqwest` and full featured AQL query.\n- [X] Fill the unimplemented API in `Connection`, `Database`, `Collection` and `Document`.\n- [X] support both `async` and sync client\n- [X] Offers a way to use custom HTTP client ecosystem.\n- [X] Index Management (since 0.4.3)\n- [X] Graph Management (since 0.4.5)\n- [X] User Management (since 0.5.4)\n\n## Glance\n\n### Use Different HTTP Ecosystem, Regardless of Async or Sync\n\nYou can switch to different HTTP ecosystem with a feature gate, or implement\nthe Client yourself (see examples).\n\nCurrently out-of-box supported ecosystem are:\n- `reqwest_async`\n- `reqwest_blocking`\n- `surf_async`\n\nBy default, `arangors` use `reqwest_async` as underling HTTP Client to\nconnect with ArangoDB. You can switch other ecosystem in feature gate:\n\n```toml\n[dependencies]\narangors = { version = \"0.6\", features = [\"surf_async\"], default-features = false }\n```\n\nOr if you want to stick with other ecosystem that are not listed in the\nfeature gate, you can get vanilla `arangors` without any HTTP client\ndependency:\n\n```toml\n[dependencies]\n## This one is async\narangors = { version = \"0.6\", default-features = false }\n## This one is synchronous\narangors = { version = \"0.6\", features = [\"blocking\"], default-features = false }\n```\n\nThanks to `maybe_async`, `arangors` can unify sync and async API and toggle\nwith a feature gate. Arangors adopts async first policy.\n\n### Connection\n\nThere is three way to establish connections:\n- jwt\n- basic auth\n- no authentication\n\nSo are the `arangors` API.\n\nExample:\n\n- With authentication\n\n```rust\nuse arangors::Connection;\n\n// (Recommended) Handy functions\nlet conn = Connection::establish_jwt(\"http://localhost:8529\", \"username\", \"password\")\n    .await\n    .unwrap();\nlet conn = Connection::establish_basic_auth(\"http://localhost:8529\", \"username\", \"password\")\n    .await\n    .unwrap();\n```\n\n- Without authentication\n\n**Only use in evaluation setting**.\n\n``` rust\nuse arangors::Connection;\nlet conn = Connection::establish_without_auth(\"http://localhost:8529\").await.unwrap();\n```\n\n## Database \u0026\u0026 Collection\n\nTo get info or operate on database or collections:\n\n```rust\nuse arangors::Connection;\n\nlet db = conn.db(\"test_db\").await.unwrap();\nlet collection = db.collection(\"test_collection\").await.unwrap();\n```\n\n### AQL Query\n\nAll [AQL](https://www.arangodb.com/docs/stable/aql/index.html) query related functions are associated with database, as AQL query\nis performed at database level.\n\nThere are several way to execute AQL query, and can be categorized into two\nclasses:\n\n- batch query with cursor\n    - `aql_query_batch`\n    - `aql_next_batch`\n\n- query to fetch all results\n    - `aql_str`\n    - `aql_bind_vars`\n    - `aql_query`\n\nThis later ones provide a convenient high level API, whereas batch\nqueries offer more control.\n\n#### Typed or Not Typed\n\nNote that results from ArangoDB server, e.x. fetched documents, can be\nstrong typed given deserializable struct, or arbitrary JSON object with\n`serde::Value`.\n\n```rust\n\n#[derive(Deserialize, Debug)]\nstruct User {\n    pub username: String,\n    pub password: String,\n}\n\n// Typed\nlet resp: Vec\u003cUser\u003e = db\n    .aql_str(\"FOR u IN test_collection RETURN u\")\n    .await\n    .unwrap();\n// Not typed: Arbitrary JSON objects\nlet resp: Vec\u003cserde_json::Value\u003e = db\n    .aql_str(\"FOR u IN test_collection RETURN u\")\n    .await\n    .unwrap();\n```\n\n#### Batch query\n\n`arangors` offers a way to manually handle batch query.\n\nUse `aql_query_batch` to get a cursor, and use `aql_next_batch` to fetch\nnext batch and update cursor with the cursor.\n\n```rust\n\nlet aql = AqlQuery::builder()\n    .query(\"FOR u IN @@collection LIMIT 3 RETURN u\")\n    .bind_var(\"@collection\", \"test_collection\")\n    .batch_size(1)\n    .count(true)\n    .build();\n\n// fetch the first cursor\nlet mut cursor = db.aql_query_batch(aql).await.unwrap();\n// see metadata in cursor\nprintln!(\"count: {:?}\", cursor.count);\nprintln!(\"cached: {}\", cursor.cached);\nlet mut results: Vec\u003cserde_json::Value\u003e = Vec::new();\nloop {\n    if cursor.more {\n        let id = cursor.id.unwrap().clone();\n        // save data\n        results.extend(cursor.result.into_iter());\n        // update cursor\n        cursor = db.aql_next_batch(id.as_str()).await.unwrap();\n    } else {\n        break;\n    }\n}\nprintln!(\"{:?}\", results);\n```\n\n#### Fetch All Results\n\nThere are three functions for AQL query that fetch all results from\nArangoDB. These functions internally fetch batch results one after another\nto get all results.\n\nThe functions for fetching all results are listed as bellow:\n\n##### `aql_str`\n\nThis function only accept a AQL query string.\n\nHere is an example of strong typed query result with `aql_str`:\n\n```rust\n\n#[derive(Deserialize, Debug)]\nstruct User {\n    pub username: String,\n    pub password: String,\n}\n\nlet result: Vec\u003cUser\u003e = db\n    .aql_str(r#\"FOR i in test_collection FILTER i.username==\"test2\" return i\"#)\n    .await\n    .unwrap();\n```\n\n##### `aql_bind_vars`\n\nThis function can be used to start a AQL query with bind variables.\n\n```rust\nuse arangors::{Connection, Document};\n\n#[derive(Serialize, Deserialize, Debug)]\nstruct User {\n    pub username: String,\n    pub password: String,\n}\n\n\nlet mut vars = HashMap::new();\nlet user = User {\n    username: \"test\".to_string(),\n    password: \"test_pwd\".to_string(),\n};\nvars.insert(\"user\", serde_json::value::to_value(\u0026user).unwrap());\nlet result: Vec\u003cDocument\u003cUser\u003e\u003e = db\n    .aql_bind_vars(r#\"FOR i in test_collection FILTER i==@user return i\"#, vars)\n    .await\n    .unwrap();\n```\n\n##### `aql_query`\n\nThis function offers all the options available to tweak a AQL query.\nUsers have to construct a `AqlQuery` object first. And `AqlQuery` offer all\nthe options needed to tweak AQL query. You can set batch size, add bind\nvars, limit memory, and all others\noptions available.\n\n```rust\nuse arangors::{AqlQuery, Connection, Cursor, Database};\nuse serde_json::value::Value;\n\n\nlet aql = AqlQuery::builder()\n    .query(\"FOR u IN @@collection LIMIT 3 RETURN u\")\n    .bind_var(\"@collection\", \"test_collection\")\n    .batch_size(1)\n    .count(true)\n    .build();\n\nlet resp: Vec\u003cValue\u003e = db.aql_query(aql).await.unwrap();\nprintln!(\"{:?}\", resp);\n```\n\n### Contributing\n\nContributions and feed back are welcome following Github workflow.\n\n### License\n\n`arangors` is provided under the MIT license. See [LICENSE](./LICENSE).\nAn ergonomic [ArangoDB](https://www.arangodb.com/) client for rust.\n\nLicense: MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FfMeow%2Farangors","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FfMeow%2Farangors","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FfMeow%2Farangors/lists"}