+ 
@@ -46,7 +47,7 @@
## 
Agnesoft Graph Database
@@ -46,7 +47,7 @@
## Agnesoft Graph Database
-Why not SQL? | DECISION TREE | Troubleshooting +Why not SQL? | DECISION TREE | Queries
The Agnesoft Graph Database (aka _agdb_) is persistent, optionally memory mapped graph database with native object 'no-text' queries. It can be used as a main persistent storage, data analytics platform as well as fast in-memory cache. Its typed schema-less data store allows for flexible and seamless data updates with no downtime or costly migrations. All queries are constructed via a builder pattern or directly as objects with no special language or text parsing. @@ -167,35 +168,36 @@ For database concepts and primitive data types see [concepts](docs/concepts.md). ## Decision Tree
```mermaid
-graph TD;
+flowchart TD;
A[Embedded or server?] --> Embedded
A --> B[Client or hosting?]
- Embedded --> Queries[Queries]
Embedded --> Studio[Studio]
+ Embedded --> Queries[Queries]
B --> Client
B --> Hosting
Client --> API[API]
Client --> Studio
+ Client --> Queries
Hosting --> Server[Server]
Hosting --> Cloud[Cloud]
```
## Roadmap
-The following are planned features in no particular order:
-
-| Feature | Description |
-| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Data replication & RAFT protocol | Allow replication by connecting several database nodes together with a RAFT protocol. |
-| #\[no_std] | The `agdb` does not require any dependencies and thus should be (in theory) `no_std` friendly but it will likely require some development & testing. |
-| Agdb Studio | Graphical interface to `agdb` |
-| Python Client | Convenience client using bindings genereated from OpenAPI. |
-| Java Client | Convenience client using bindings genereated from OpenAPI. |
-| C# Client | Convenience client using bindings genereated from OpenAPI. |
-| C Client | Convenience client using bindings genereated from OpenAPI. |
-| C++ Client | Convenience client using bindings genereated from OpenAPI. |
-| Agdb Playground | Free public cloud-based playground to tinker with `agdb`. |
-| Public Cloud Offering | Commercial & supported `agdb` instance hosted in a public cloud. |
+The following are planned features with target versions:
+
+| Feature | Description | Version |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
+| Agdb Studio | Graphical interface to `agdb` | 0.7.0 |
+| Python Client | Convenience client using bindings genereated from OpenAPI. | 0.7.0 |
+| Java Client | Convenience client using bindings genereated from OpenAPI. | 0.8.0 |
+| C# Client | Convenience client using bindings genereated from OpenAPI. | 0.8.0 |
+| C Client | Convenience client using bindings genereated from OpenAPI. | 0.8.0 |
+| C++ Client | Convenience client using bindings genereated from OpenAPI. | 0.8.0 |
+| Data replication & consensus protocol | Allow replication by connecting several database nodes together with a RAFT protocol. | 0.9.0 |
+| Agdb Playground | Free public cloud-based playground to tinker with `agdb`. | 0.9.0 |
+| #\[no_std] | The `agdb` does not require any dependencies and thus should be (in theory) `no_std` friendly but it will likely require some development & testing. | 1.0.0 |
+| Public Cloud Offering | Commercial & supported `agdb` instance hosted in a public cloud. | 1.0.0 |
## Reference
diff --git a/agdb/src/query_builder.rs b/agdb/src/query_builder.rs
index 15cf6e295..3752d765c 100644
--- a/agdb/src/query_builder.rs
+++ b/agdb/src/query_builder.rs
@@ -82,7 +82,7 @@ impl QueryBuilder {
Remove {}
}
- /// Search teh database by traversing the graph
+ /// Search the database by traversing the graph
/// and returns element ids using breadth first,
/// depth first or A* algorithm:
///
diff --git a/agdb_server/Cargo.toml b/agdb_server/Cargo.toml
index 8853ac4f5..1b17f76e4 100644
--- a/agdb_server/Cargo.toml
+++ b/agdb_server/Cargo.toml
@@ -26,7 +26,7 @@ tower = "0.4"
tracing = "0.1"
tracing-subscriber = "0.3"
utoipa = "4"
-utoipa-rapidoc = { version = "2", features = ["axum"] }
+utoipa-rapidoc = { version = "3", features = ["axum"] }
uuid = { version = "1", features = ["v4"] }
[dev-dependencies]
diff --git a/agdb_server/src/db_pool.rs b/agdb_server/src/db_pool.rs
index f3160b8b4..a74d1698d 100644
--- a/agdb_server/src/db_pool.rs
+++ b/agdb_server/src/db_pool.rs
@@ -38,6 +38,7 @@ use std::sync::RwLockReadGuard;
use std::sync::RwLockWriteGuard;
use std::time::SystemTime;
use std::time::UNIX_EPOCH;
+use uuid::Uuid;
const SERVER_DB_NAME: &str = "mapped:agdb_server.agdb";
@@ -842,9 +843,9 @@ impl DbPool {
Ok(())
}
- pub(crate) fn save_token(&self, user: DbId, token: String) -> ServerResult| Struct | Result |
|
```Rust
-pub struct InsertNodesQuery {
- pub count: u64,
- pub values: QueryValues,
+pub struct InsertAliasesQuery {
+ pub ids: QueryIds,
pub aliases: Vec |
```Rust
-QueryBuilder::insert().nodes().count(2).query();
-QueryBuilder::insert().nodes().count(2).values_uniform(vec![("k", "v").into(), (1, 10).into()]).query();
-QueryBuilder::insert().nodes().aliases(vec!["a", "b"]).query();
-QueryBuilder::insert().nodes().aliases(vec!["a", "b"]).values(vec![vec![("k", 1).into()], vec![("k", 2).into()]]).query();
-QueryBuilder::insert().nodes().aliases(vec!["a", "b"]).values_uniform(vec![("k", "v").into(), (1, 10).into()]).query();
-QueryBuilder::insert().nodes().values(vec![vec![("k", 1).into()], vec![("k", 2).into()]]).query();
+pub struct QueryResult {
+ pub result: i64, // number of inserted/updated aliases
+ pub elements: Vec |
| Builder | |
| + +```Rust +QueryBuilder::insert().aliases("a").ids(1).query(); +QueryBuilder::insert().aliases("a").ids("b").query(); // alias "b" is replaced with "a" +QueryBuilder::insert().aliases(vec!["a", "b"]).ids(vec![1, 2]).query(); +``` -The result will contain: + | |
| Struct | Result |
| + ```Rust pub struct InsertEdgesQuery { pub from: QueryIds, @@ -294,7 +382,16 @@ pub struct InsertEdgesQuery { } ``` -Builder pattern: + |
+
+```Rust
+pub struct QueryResult {
+ pub result: i64, // number of inserted edges
+ pub elements: Vec |
| Builder | |
| ```Rust QueryBuilder::insert().edges().from(1).to(2).query(); @@ -309,60 +406,80 @@ QueryBuilder::insert().edges().from(QueryBuilder::search().from("a").where_().no QueryBuilder::insert().edges().from(QueryBuilder::search().from("a").where_().node().query()).to(QueryBuilder::search().from("b").where_().node().query()).values_uniform(vec![("k", "v").into(), (1, 10).into()]).query(); ``` + | |
| Struct | Result |
| -### Insert aliases +```Rust +pub struct InsertIndexQuery(pub DbValue); +``` + + |
```Rust
-pub struct InsertAliasesQuery {
- pub ids: QueryIds,
- pub aliases: Vec |
| Builder | |
| ```Rust -QueryBuilder::insert().aliases("a").ids(1).query(); -QueryBuilder::insert().aliases("a").ids("b").query(); // alias "b" is replaced with "a" -QueryBuilder::insert().aliases(vec!["a", "b"]).ids(vec![1, 2]).query(); +QueryBuilder::insert().index("key").query(); ``` -Inserts or updates aliases of existing nodes (and only nodes, edges cannot have aliases) through this query. It takes `ids` [`QueryIds`](#queryids--queryid) and list of `aliases` as arguments. The number of aliases must match the `ids` (even if they are a search query). Empty alias (`""`) are not allowed. - -Note that this query is used also for updating existing aliases. Byt inserting a different alias of an id that already has one the alias will be overwritten with the new one. + | |
| Struct | Result |
|
```Rust
-pub struct InsertIndexQuery(pub DbValue);
+pub struct InsertNodesQuery {
+ pub count: u64,
+ pub values: QueryValues,
+ pub aliases: Vec |
```Rust
-QueryBuilder::insert().index("key").query();
+pub struct QueryResult {
+ pub result: i64, // number of inserted nodes
+ pub elements: Vec |
| Builder | |
| + +```Rust +QueryBuilder::insert().nodes().count(2).query(); +QueryBuilder::insert().nodes().count(2).values_uniform(vec![("k", "v").into(), (1, 10).into()]).query(); +QueryBuilder::insert().nodes().aliases(vec!["a", "b"]).query(); +QueryBuilder::insert().nodes().aliases(vec!["a", "b"]).values(vec![vec![("k", 1).into()], vec![("k", 2).into()]]).query(); +QueryBuilder::insert().nodes().aliases(vec!["a", "b"]).values_uniform(vec![("k", "v").into(), (1, 10).into()]).query(); +QueryBuilder::insert().nodes().values(vec![vec![("k", 1).into()], vec![("k", 2).into()]]).query(); +``` -The result will contain: + | |
| Struct | Result |
| + ```Rust pub struct InsertValuesQuery { pub ids: QueryIds, @@ -370,7 +487,16 @@ pub struct InsertValuesQuery { } ``` -Builder pattern: + |
+
+```Rust
+pub struct QueryResult {
+ pub result: i64, // number of inserted key-value pairs
+ pub elements: Vec |
| Builder | |
|
```Rust
QueryBuilder::insert().element(&T { ... }).query(); //Where T: DbUserValue (i.e. #derive(UserValue))
@@ -381,106 +507,144 @@ QueryBuilder::insert().values_uniform(vec![("k", "v").into(), (1, 10).into()]).i
QueryBuilder::insert().values_uniform(vec![("k", "v").into(), (1, 10).into()]).ids(QueryBuilder::search().from("a").query()).query();
```
-Inserts or updates key-value pairs (properties) of existing elements. You need to specify the `ids` [`QueryIds`](#queryids--queryid) and the list of `values`. The `values` can be either [`QueryValues::Single`](#queryvalues) that will insert the single set of properties to all elements identified by `ids` or [`QueryValues::Multi`](#queryvalues) that will insert to each `id` its own set of properties but their number must match the number of `ids`. If the user defined type contains `db_id` field of type `Option | |
| Struct | Result |
|
```Rust
-pub struct RemoveQuery(pub QueryIds);
+pub struct RemoveAliasesQuery(pub Vec |
```Rust
-QueryBuilder::remove().ids(1).query();
-QueryBuilder::remove().ids("a").query();
-QueryBuilder::remove().ids(vec![1, 2]).query();
-QueryBuilder::remove().ids(vec!["a", "b"]).query();
-QueryBuilder::remove().ids(QueryBuilder::search().from("a").query()).query();
+pub struct QueryResult {
+ pub result: i64, // negative number of removed aliases
+ pub elements: Vec |
| Builder | |
| + +```Rust +QueryBuilder::remove().aliases("a").query(); +QueryBuilder::remove().aliases(vec!["a", "b"]).query(); +``` -The result will contain: + | |
| Struct | Result |
|
```Rust
-pub struct RemoveAliasesQuery(pub Vec |
```Rust
-QueryBuilder::remove().aliases("a").query();
-QueryBuilder::remove().aliases(vec!["a", "b"]).query();
+pub struct QueryResult {
+ pub result: i64, // negative number of removed ids
+ // (does not include removed edges
+ // unless listed in query ids)
+ pub elements: Vec |
| Builder | |
| -The result will contain: +```Rust +QueryBuilder::remove().ids(1).query(); +QueryBuilder::remove().ids("a").query(); +QueryBuilder::remove().ids(vec![1, 2]).query(); +QueryBuilder::remove().ids(vec!["a", "b"]).query(); +QueryBuilder::remove().ids(QueryBuilder::search().from("a").query()).query(); +``` -- negative number of aliases removed -- empty list of elements + | |
| Struct | Result |
| + ```Rust pub struct RemoveIndexQuery(pub DbValue); ``` -Builder pattern: + |
```Rust
-QueryBuilder::remove().index("key").query()
+pub struct QueryResult {
+ pub result: i64, // negative number of values removed
+ // from the index
+ pub elements: Vec |
| Builder | |
| -The result will contain: +```Rust +QueryBuilder::remove().index("key").query() +``` + + | |
| Struct | Result |
| + ```Rust pub struct RemoveValuesQuery(pub SelectValuesQuery); ``` -NOTE: See [`SelectValuesQuery`](#select-values) for more details. + |
-Builder pattern:
+```Rust
+pub struct QueryResult {
+ pub result: i64, // negative number of actually removed
+ // key-value pairs
+ pub elements: Vec |
| Builder | |
| ```Rust QueryBuilder::remove().values(vec!["k1".into(), "k2".into()]).ids(vec![1, 2]).query(); QueryBuilder::remove().values(vec!["k1".into(), "k2".into()]).ids(QueryBuilder::search().from("a").query()).query(); ``` -The properties (key-value pairs) identified by `keys` and associated with `ids` [`QueryIds`](#queryids--queryid) will be removed from the database if they exist. It is a data error if any of the `ids` do not exist in the database but it is NOT an error if any of the keys does not exist or is not associated as property to any of the `ids`. + | |
| Struct | Result |
| ```Rust -pub struct SelectQuery(pub QueryIds); +pub struct SelectAliasesQuery(pub QueryIds); ``` -Builder pattern: + |
```Rust
-QueryBuilder::select().ids("a").query();
-QueryBuilder::select().ids(vec![1, 2]).query();
-QueryBuilder::select().ids(QueryBuilder::search().from(1).query()).query();
+pub struct QueryResult {
+ pub result: i64, // number of returned elements
+ pub elements: Vec |
| Builder | |
| -The result will contain: +```Rust +QueryBuilder::select().aliases().ids(vec![1, 2]).query(); +QueryBuilder::select().aliases().ids(QueryBuilder::search().from(1).query()).query(); +``` -- number of returned elements -- list of elements with all properties + | |
| Struct | Result |
|
```Rust
-pub struct SelectValuesQuery {
- pub keys: Vec |
+
+```Rust
+pub struct QueryResult {
+ pub result: i64, // number of elements with aliases
+ pub elements: Vec |
| Builder | |
| ```Rust -QueryBuilder::select().values(vec!["k".into(), "k2".into()]).ids("a").query(); -QueryBuilder::select().values(vec!["k".into(), "k2".into()]).ids(vec![1, 2]).query(); -QueryBuilder::select().values(vec!["k".into(), "k2".into()]).ids(QueryBuilder::search().from(1).query()).query(); +QueryBuilder::select().aliases().query() ``` -Selects elements identified by `ids` [`QueryIds`](#queryids--queryid) or search query with only selected properties (identified by the list of keys). If any of the ids does not exist in the database or does not have all the keys associated with it then running the query will return an error. While the search query is most commonly used to find, filter or otherwise limit what elements to select, using this particular query can limit what properties will be returned. If you plan to convert the result into your user defined type(s) you should use `T::db_keys()` provided through the `DbUserValue` trait (`#derive(UserValue)`) as argument to `values()`. + | |
| Struct | Result |
| ```Rust -pub struct SelectKeysQuery(pub QueryIds); +pub struct SelectQuery(pub QueryIds); ``` -Builder pattern: + |
```Rust
-QueryBuilder::select().keys().ids("a").query();
-QueryBuilder::select().keys().ids(vec![1, 2]).query();
-QueryBuilder::select().keys().ids(QueryBuilder::search().from(1).query()).query();
+pub struct QueryResult {
+ pub result: i64, // number of returned elements
+ pub elements: Vec |
| Builder | |
| -The result will contain: +```Rust +QueryBuilder::select().ids("a").query(); +QueryBuilder::select().ids(vec![1, 2]).query(); +QueryBuilder::select().ids(QueryBuilder::search().from(1).query()).query(); +``` -- number of returned elements -- list of elements with only keys and default (empty `I64(0)` values) + | |
| Struct | Result |
| ```Rust -pub struct SelectKeyCountQuery(pub QueryIds); +pub struct SelectIndexesQuery {}; ``` -Builder pattern: + |
```Rust
-QueryBuilder::select().key_count().ids("a").query();
-QueryBuilder::select().key_count().ids(vec![1, 2]).query();
-QueryBuilder::select().key_count().ids(QueryBuilder::search().from(1).query()).query();
+pub struct QueryResult {
+ pub result: i64, // number of indexes in the database
+ pub elements: Vec |
| Builder | |
| + +```Rust +QueryBuilder::select().indexes().query(); +``` + + | |
| Struct | Result |
| ```Rust -pub struct SelectIndexesQuery {}; +pub struct SelectKeysQuery(pub QueryIds); ``` -Builder pattern: + |
```Rust
-QueryBuilder::select().indexes().query();
+pub struct QueryResult {
+ pub result: i64, // number of returned elements
+ pub elements: Vec |
| Builder | |
| -The result will contain: +```Rust +QueryBuilder::select().keys().ids("a").query(); +QueryBuilder::select().keys().ids(vec![1, 2]).query(); +QueryBuilder::select().keys().ids(QueryBuilder::search().from(1).query()).query(); +``` -- number of indexes -- single element with id 0 and list of properties representing each index (`DbValue`: `u64`) where the key is the indexed key and the value is number of indexed values in the index. + | |
| Struct | Result |
| ```Rust -pub struct SelectAliasesQuery(pub QueryIds); +pub struct SelectKeyCountQuery(pub QueryIds); ``` -Builder pattern: + |
```Rust
-QueryBuilder::select().aliases().ids(vec![1, 2]).query();
-QueryBuilder::select().aliases().ids(QueryBuilder::search().from(1).query()).query();
+pub struct QueryResult {
+ pub result: i64, // number of returned elements
+ pub elements: Vec |
| Builder | |
| + +```Rust +QueryBuilder::select().key_count().ids("a").query(); +QueryBuilder::select().key_count().ids(vec![1, 2]).query(); +QueryBuilder::select().key_count().ids(QueryBuilder::search().from(1).query()).query(); +``` + + | |
| Struct | Result |
|
```Rust
-pub struct SelectAllAliases {}
+pub struct SelectValuesQuery {
+ pub keys: Vec |
```Rust
-QueryBuilder::select().aliases().query()
+pub struct QueryResult {
+ pub result: i64, // number of returned elements
+ pub elements: Vec |
| Builder | |
| -The result will contain: +```Rust +QueryBuilder::select().values(vec!["k".into(), "k2".into()]).ids("a").query(); +QueryBuilder::select().values(vec!["k".into(), "k2".into()]).ids(vec![1, 2]).query(); +QueryBuilder::select().values(vec!["k".into(), "k2".into()]).ids(QueryBuilder::search().from(1).query()).query(); +``` -- number of elements with aliases -- list of elements with an alias each with a single property (`String("alias"): String`) + | |
| Struct | Result |
|
```Rust
pub struct SearchQuery {
@@ -661,7 +903,20 @@ pub struct SearchQuery {
pub order_by: Vec |
+```Rust
+pub struct QueryResult {
+ pub result: i64, // number of elements found
+ pub elements: Vec |
| + +```Rust pub enum SearchQueryAlgorithm { BreadthFirst, DepthFirst, @@ -674,18 +929,15 @@ pub enum DbKeyOrder { } ``` -Builder pattern: + | |
| Builder | |
| ```Rust QueryBuilder::search().from("a").query(); QueryBuilder::search().to(1).query(); //reverse search -QueryBuilder::search().from("a").to("b").query(); //path search, A* - -QueryBuilder::search().breadth_first().from("a").query(); //breadth first is the default and can be omitted however +QueryBuilder::search().from("a").to("b").query(); //path search using A* algorithm +QueryBuilder::search().breadth_first().from("a").query(); //breadth first is the default and can be omitted QueryBuilder::search().depth_first().from("a").query(); - -QueryBuilder::search().index("age").value(20).query(); - +QueryBuilder::search().index("age").value(20).query(); //index search //limit, offset and order_by can be applied similarly to all the search variants QueryBuilder::search().from(1).order_by(vec![DbKeyOrder::Desc("age".into()), DbKeyOrder::Asc("name".into())]).query() QueryBuilder::search().from(1).offset(10).query(); @@ -696,6 +948,10 @@ QueryBuilder::search().from(1).order_by(vec![DbKeyOrder::Desc("k".into())]).offs QueryBuilder::search().from(1).offset(10).limit(5).query(); ``` + | |
| Struct |
| ```Rust pub struct QueryCondition { @@ -783,7 +1017,7 @@ pub enum Comparison { } ``` -Builder pattern: + |
| Builder |
| ```Rust //the where_() can be applied to any of the basic search queries after order_by/offset/limit @@ -808,6 +1042,33 @@ QueryBuilder::search().from(1).where_().node().or().where_().edge().and().key("k QueryBuilder::search().from(1).where_().node().or().where_().edge().and().key("k").value(Comparison::Contains(vec![1, 2].into())).end_where().query(); ``` + |