graphersal 0.1.1

In-memory graph traversal engine modelled on Apache TinkerPop Gremlin, with a Rhai DSL, optimizer and GraphSON/GraphML I/O
Documentation 
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

# graphersal

An in-memory graph database and traversal engine in Rust, queried with Gremlin, the query language
of Apache TinkerPop.

**[Playground](https://play.graphersal.dev)** · **[Book](https://graphersal.dev)** ·
**[Step reference](https://graphersal.dev/traversal/step_reference.html)** ·
**[Repository](https://github.com/graphersal/graphersal)**

![The web playground: a recursive traversal over a directory tree, its results and the graph](https://graphersal.dev/images/getting_started/playground-tree.png)

```toml
[dependencies]
graphersal = { version = "0.1", features = ["script", "io", "display"] }
```

```rust
use std::sync::Arc;

use graphersal::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // The TinkerPop "modern" sample graph: 4 people, 2 pieces of software, 6 edges.
    let graph = GraphSource::tinkerpop_modern();

    // The Rust API: a read lock gives a traversal source, a terminal runs the traversal.
    let friends = graph
        .read()
        .traversal()
        .v(None)
        .has("name", "marko")
        .out("knows")
        .values("name")
        .to_list()?;
    println!("{friends:?}"); // ["josh", "vadas"]

    // The same query as Gremlin text (feature `script`), in snake_case or camelCase.
    let names = graphersal::script::eval_value(
        Arc::new(graph),
        r#"g.V().has("name", "marko").out("knows").values("name").toList()"#,
    )?;
    println!("{names}"); // ["josh", "vadas"]
    Ok(())
}
```

## What is in it

- A property graph in memory: vertices with a set of labels, edges, properties of logical types
  (`int64`, `float64`, `string`, `uuid`, arrays, objects), indexes and graph statistics.
- The Gremlin steps as a Rust API and as text, the Gremlin DSL (on [Rhai](https://rhai.rs)), with
  a rule-based optimizer, bulk traversers and `profile()` / `execute()` showing the optimized plan
  with timings, counts and memory per step.
- Every traversal is atomic: it commits completely or is rolled back. Explicit transactions, dry
  runs and change capture with commit hooks for everything around it.
- Schemas in a subset of JSON Schema 2020-12, enforced on write in `open` or `closed` mode,
  inferred from data, patched, validated and diffed.
- Running queries you did not write: resource limits, timeouts, cancellation, a memory budget and
  permissions (an `Authorizer`, for example the ready-made `AccessPolicy::read_only()`).
- Saved queries: named, parameterized queries stored in the graph.
- Persistence: lossless snapshots, a write-ahead journal, and the Store (one directory or one file
  = one graph) with point-in-time views, fork, rollback, verified backups and repair; the format is
  a [public specification](https://graphersal.dev/persistence/format.html).
- Your own storage: the whole engine is generic over the `GraphStorage` trait (EXPERIMENTAL in
  0.1.x), with the conformance suite `graphersal-storage-tests`.

## Features

All off by default and strictly additive:

| Feature | What it adds |
|---|---|
| `script` | the Gremlin DSL as text, with safe default limits |
| `io` | GraphSON 3.0 and GraphML import and export |
| `display` | results rendered as tables |
| `serde` | serialization of change sets and schemas, the JSON visualizer |
| `persist` | snapshots, the journal and the Store; `persist-zstd` and `persist-zip` add zstd chunks and ZIP backups |
| `alloc-tracking` | exact per-step memory figures in `profile()` (the binary installs the allocator) |

## Learn more

- [Rust Quick Start](https://graphersal.dev/library/rust.html) and the
  [API documentation](https://docs.rs/graphersal).
- The command line tool, REPL, dev server and MCP endpoint: the
  [`graphersal-cli`](https://crates.io/crates/graphersal-cli) crate (binary `graphersal`).
- Apache TinkerPop's own test suite runs on every test run: more than 95 % of the scenarios in scope
  pass, and no implemented step gives a wrong result
  ([compliance](https://graphersal.dev/for_developers/tinkerpop_compliance.html),
  [deviations](https://graphersal.dev/for_developers/tinkerpop_deviations.html)).

Graphersal is compatible with, and inspired by, Apache TinkerPop Gremlin. It is an independent
project: it is not part of Apache TinkerPop and is not endorsed by the Apache Software Foundation.

Licensed under the Apache License, Version 2.0 (see `LICENSE-APACHE` and `NOTICE`).