Introduction

Graphersal is an in-memory graph database and traversal engine written in Rust. You ask it questions in Gremlin, the query language of Apache TinkerPop™: start somewhere in a graph, walk along its edges, filter, group and count.

// who created software together with marko?
g.v().has("name", "marko").as("me")
  .out("created").in("created")
  .where(P.neq("me"))
  .path().by("name")

What you get

• Gremlin, two ways. Build traversals in Rust (g.v(None).has_label("person").out("knows")) or write them as text in the Gremlin DSL, in snake_case or in Gremlin's own camelCase (hasLabel, outE). The text runs the same everywhere: in the browser, in the command line, from Python and through an AI agent.
• A playground in the browser. The real engine, compiled to WebAssembly: write a query, see a table, the graph drawing, the schema and the optimized plan. Nothing to install.
• A command line tool. One-shot queries for shell scripts, an interactive REPL with completion and help, and a local server that brings the playground UI to a graph on your disk.
• AI agents on your graph. The server speaks the Model Context Protocol (MCP), so Claude Code or another MCP client can query the graph you are looking at. The playground has its own AI Chat tab as well (experimental).
• Safe by construction. Every traversal is atomic: it commits completely or leaves nothing behind. Schemas (a subset of JSON Schema) are enforced on write. Limits, timeouts and permissions make it safe to run queries you did not write.
• Durable when you need it. A graph lives in memory, and the Store keeps it on disk: every commit is in a write-ahead log, you can go back to any point in time, fork, roll back, back up and repair. The file format is a public specification.
• Fast and observable. A rule-based optimizer rewrites each query; profile() shows the optimized plan with timings, traverser counts and memory per step.
• Open for integration. Rust and Python APIs, saved (named, parameterized) queries stored in the graph, change capture with commit hooks, GraphSON and GraphML files, and a storage trait to run the whole engine on a storage of your own.

Where to go next

Graphersal is not a complete copy of TinkerPop. It follows the TinkerPop specification for every step it implements and checks that with TinkerPop's own test suite, but some steps are not implemented yet and a few behave differently on purpose. Each difference is documented where the feature is described and collected in TinkerPop Deviations; see Graphersal and TinkerPop.

Try It in the Browser

The playground is the quickest way to see what Graphersal does. It is a web page that runs the real engine, compiled to WebAssembly, inside your browser: no server, no account, and your data never leaves the machine.

Start it

rustup target add wasm32-unknown-unknown                      # one-time
cargo install --locked wasm-bindgen-cli --version 0.2.129     # one-time
playground/build.sh                                           # builds playground/pkg/
python3 playground/serve.py 8000                              # open http://localhost:8000/

The start page offers sample graphs, or a GraphSON or GraphML file of your own:

Pick Modern (TinkerPop): four people, two pieces of software, and who knows and created what. Most examples in this book run on it.

Run a query

Type a traversal into the Query panel and press Ctrl/⌘+Enter. The results appear as a table (also as JSON and as the raw text the command line prints), and the Graph panel draws the graph. Typing . offers every step with its description and a runnable example.

A few queries to start with; Run in the playground under each one opens it there:

g.v().has_label("person").values("name")                       // all people

g.v().has("name", "marko").out("knows").values("name")         // whom marko knows

g.v().has_label("person").has("age", P.gt(30)).values("name")  // people older than 30

g.v().has_label("person").group().by("name").by(__.out("created").count())   // software per person

The Examples menu holds about thirty more, grouped by graph and topic.

See how it ran

With Profile on, every run also shows the plan the optimizer made of your query: each step with its calls, traversers in and out and its time, plus the optimizer rules that changed the plan. Here has_label("person") was folded into the start step (v(labels: ["person"])):

Look at the schema

The Schema panel infers the structure of the data: the labels, their properties and types, and which edges connect which labels. You can edit it, and Freeze as open or Freeze as closed turns it into a schema the engine enforces on every write.

Walk a bigger graph

The File tree sample is a small directory tree: good for recursive traversals with repeat().

What else is in there

• several query tabs side by side, a history and saved scripts;
• a graph editor (add, change and delete vertices and edges by clicking);
• a fast WebGL drawing for large graphs, label graphs and neighbourhood views;
• saved queries and compression rules in the Catalog menu;
• a Store in memory with commits, marks, point-in-time views, forks and rollback (the Store menu);
• downloads of the graph (GraphSON, GraphML, snapshot), the schema and the catalog.

Every feature is described in Web Playground. The same UI also runs against a graph on your disk, served by the command line tool: Dev Server, MCP and AI Chat.

The Command Line

The graphersal binary runs Gremlin queries from a terminal. It has three modes: a one-shot query runner for shell scripts, an interactive REPL, and a local server (next chapter).

cargo build -p graphersal-cli --release      # target/release/graphersal

One-shot queries

Pass a query with -e; the result goes to stdout and nothing else does:

$ graphersal -e 'g.v().has("name", "marko").out("knows").values("name")'
╭───────╮
│ value │
├───────┤
│ josh  │
│ vadas │
╰───────╯

Without --graph it runs on the TinkerPop "modern" sample. --graph also takes empty, large (about 110,000 elements), tree, a GraphSON or GraphML file, a snapshot or a Store directory:

graphersal --graph people.json -e 'g.v().count()'
echo 'g.v().values("age").max().next()' | graphersal --graph modern     # the query from stdin
graphersal -e 'g.v().has_label("person").values("name")' --format json  # also markdown, mermaid, ...

A query that fails prints its diagnostic on stderr and exits with 1, so a shell script or a CI job can check a graph:

# fails (exit 1) when a server has no owner
graphersal --graph export.json -e 'g.v().has_label("server").has_not("owner").fail("a server without an owner")'

The REPL

Without a query, graphersal starts an interactive shell with history, Tab completion of steps and tokens, and the documentation of every function:

$ graphersal
graphersal> g.v().has_label("person").values("name").limit(2);
╭───────╮
│ value │
├───────┤
│ marko │
│ vadas │
╰───────╯
graphersal> let n = g.v().count().next();
graphersal> n * 10;
60
graphersal> /help values
values  (step, terminal or source method of a traversal)
  values()
  values(arg1: any)
  ...
Yields the values of the given (or all) properties; a jpath() key reads a nested value.

Example: `g.v(1).values("name", "age").to_list()` returns `["marko", 29]`

Variables live across lines: a script is ordinary Rhai code around Gremlin traversals, so loops, functions and maps work as well.

See the plan

profile() prints the plan the optimizer made, with timings and traverser counts:

$ graphersal -e 'g.v().has_label("person").out("created").count().profile()'
Traversal Metrics
Step                                                         Call      In     Out       Time    % Dur
=====================================================================================================
v(labels: ["person"])                                           1       0       4    5.667µs     8.66
out("created")                                                  1       4       4    5.125µs     7.83
count()                                                         1       4       1      125ns     0.19
                                                      TOTAL:             execute:   65.417µs    16.69
=====================================================================================================
Optimizer rules applied: source_filter_pushdown

Keep a graph on disk

graphersal store creates and manages a Store, a graph on disk with a write-ahead log, and every mode opens one with --graph <dir>:

graphersal store create data --from people.json    # a new store from a graph file
graphersal --graph data -e 'g.add_v("person").property("name", "ann").iterate()'   # durable
graphersal store info data

More: The graphersal store Command. Every option of the tool is in graphersal --help and on the Command Cheat Sheet.

Dev Server, MCP and AI Chat

graphersal --server brings the playground UI to a graph on your disk. The browser talks to the native engine in this process instead of WebAssembly, and the same process can open the graph to AI agents.

DEV mode. The server is for local work: it listens on the loopback interface only, has no user accounts, and its HTTP API changes without notice.

The playground over your own graph

graphersal --graph people.json --server --port 8080      # open http://127.0.0.1:8080/

--graph takes everything the command line takes: a sample, a GraphSON or GraphML file (Save to file writes it back), a snapshot, or a Store directory, whose commits are durable and whose history (marks, points in time, forks, rollback, backups) is in the Store menu.

An AI agent on the same graph (MCP)

With --mcp the server also offers a Model Context Protocol endpoint. An agent such as Claude Code then works with the same graph you see in the browser: it runs queries, adds data and evolves the schema through MCP tools, and the page reloads by itself when the agent changed something.

graphersal --graph modern --server --port 9000 --mcp
claude mcp add --transport http graphersal http://127.0.0.1:9000/mcp   # then start a new `claude`

Ask the agent, for example:

• "Use the graphersal tools: who does marko know?"
• "Add a person ada, 36 years old, who knows marko." (the browser shows the new commit)
• "Infer the schema, store it in mode open and add an optional string property email to person."

The agent gets the tools query, the schema tools (get_schema, infer_schema, set_schema, patch_schema, validate_schema, diff_schema, ...), statistics, graph_info, the saved queries and the compression rules, plus the DSL reference as a resource. --mcp-read-only lets it only read, --mcp-token requires a bearer token, and --mcp-query-tools offers every saved query as a tool of its own.

AI Chat in the playground

EXPERIMENTAL. The configuration and the tab change without notice.

With --ai FILE the agent loop runs inside the server itself: the Query panel's + opens an AI Chat tab where you ask questions in plain language. The server sends them to the LLM you configured (Anthropic, OpenAI or an OpenAI-compatible endpoint such as Ollama), runs the tool calls the model asks for on your graph and shows each step: the queries the agent ran, their results, and its answer with tables and runnable queries.

export ANTHROPIC_API_KEY=...                  # the key stays in the server process
graphersal --graph modern --server --ai crates/graphersal-cli/examples/ai-anthropic.json

What the agent queries is sent to the provider you chose; the key never reaches the browser.

Every option, the configuration keys, the safety notes and what data leaves the machine are in Dev Server and MCP.

Installation

Library

Graphersal is primarily provided as a library and can be easily incorporated into your Rust project by adding it as a dependency.

To include Graphersal as a dependency in your Rust project's Cargo.toml file, refer to the following example:

[dependencies]
graphersal = "0.1"

Supported Features

Graphersal comes with the several key features.

CLI Application

The command-line tool graphersal (crate graphersal-cli: the REPL, a one-shot query runner, the dev server and the graphersal store commands) is built from the repository:

cargo build -p graphersal-cli --release      # target/release/graphersal
target/release/graphersal --help

Every command of the tool is on the Command Cheat Sheet.

WEB Playground

Graphersal also runs in the browser: the web playground is a static page with the engine compiled to WebAssembly, so there is nothing to install on a server. Build it from the repository with playground/build.sh and serve the playground/ directory, as described in the WEB Playground chapter.

Command Cheat Sheet

Every command you need to build, run and operate Graphersal, ready to copy, each with one line of explanation. Run them from the root of a checkout of the repository. Every command on this page was run against the built binary; when the binary says something else, the binary is right and this page is wrong.

The examples write graphersal for the binary. After a debug build it is target/debug/graphersal, after a release build target/release/graphersal; put one of them on your PATH or type the path.

Build

cargo build -p graphersal-cli                 # debug build: target/debug/graphersal
cargo build -p graphersal-cli --release       # optimized build: target/release/graphersal
target/debug/graphersal --version             # check what you built
playground/build.sh                           # the WebAssembly playground into playground/pkg/

playground/build.sh needs two one-time installs: rustup target add wasm32-unknown-unknown and cargo install --locked wasm-bindgen-cli --version 0.2.129 (it must equal the wasm-bindgen crate version). wasm-opt (binaryen) is optional and makes the module smaller.

The web playground (WebAssembly, in the browser)

python3 playground/serve.py 8000              # open http://localhost:8000/

serve.py is a static file server that sends Cache-Control: no-store. Plain python3 -m http.server sends no cache headers, so after a rebuild the browser keeps running the old JavaScript modules and the old engine worker. If the page hangs after a reload, open http://localhost:8000/reset/ (it clears the playground's saved state). See WEB Playground.

One-shot queries and the REPL

graphersal                                                       # the REPL on the modern graph
graphersal --graph empty                                         # the REPL on an empty graph
graphersal -e 'g.v().has_label("person").values("name").to_list()'   # run, print, exit
graphersal -e 'let xs = g.v().to_list()' -e 'xs.len()'           # -e repeats and shares one scope
echo 'g.v().values("age").max().next()' | graphersal --in --graph modern   # the script from stdin
printf '/help has_label\n' | graphersal --repl                   # the REPL on a piped stdin (scripted sessions)

In the REPL a script runs when its input ends with ;. Commands start with / (an input starting with : gets a pointer to its / form); Tab completes steps, token values (P., Order., T., ...), commands and their arguments, in the session spelling. Completion and help read the same catalogue as the playground's query editor: the engine's own function docs.

--graph takes:

graphersal -e 'g.export_snapshot("m.gsnap")'                    # save the graph as a packed snapshot
graphersal --graph m.gsnap -e 'g.v().count().next()'             # and load it
graphersal -e 'g.export_graphson("m.json")'                      # GraphSON (TinkerPop's g.io() format)

A graph file carries no schema; --schema brings one (the schema format):

graphersal --graph g.graphml --schema schema.json -e 'g.v().count().next()'   # schema first, then the file imported against it
graphersal --graph g.json --schema schema.json --schema-mode closed           # --schema-mode overrides the file's "mode"
graphersal --graph modern --schema schema.json                                # a sample graph: the schema is applied (validated)

The schema is set on the new empty graph first and the file is imported as one unit, so declared logical types (uuid, array, object) come back and an open/closed mode is enforced. Data that violates the schema stops the start with exit code 1 and the violation report; an unreadable or invalid schema file, an unknown --schema-mode, and --schema with a Store or a .gsnap (both carry their own schema) are exit code 2.

Saved queries (stored in the database, called by name, read-only; see Saved Queries):

graphersal -e 'g.define_query(#{name: "people", body: "fn people() { g.v().has_label(\"person\") }"})' \
           -e 'g.query("people").values("name").to_list()'    # define, then call and continue
graphersal -e 'g.queries()'                                       # list (also g.queries("folder"), g.get_query(name))

Display (a result without a data terminal is rendered; to_list()/next() are never cut; iterate() runs for the side effects and shows nothing):

graphersal -e 'g.v().has_label("person").values("name")' --format json   # auto, table, markdown, json, jsonschema, mermaid, plantuml, tree
graphersal -e 'g.v()' --max-rows 2            # at most 2 rows (default 100); --max-items N for nested items
graphersal -e 'g.v().values("name")' --no-limit
graphersal --spelling camel -e 'g.v().has_label("person").count().profile()'   # Gremlin spelling in profiles and errors

Limits (scripts run without limits by default; see Resource Limits):

graphersal --graph large --timeout 50 -e 'g.v().out().out().out().out().count().next()'  # 50 ms per traversal and script
graphersal --memory-limit auto -e 'g.v().count().next()'         # memory budget: the cgroup limit minus a headroom
graphersal --memory-limit 2000000000 -e 'g.v().count().next()'  # an explicit budget in bytes
graphersal --safe-limits -e 'g.v().count().next()'               # the library's SAFE script limits
graphersal --max-operations 1000 -e 'let n = 0; loop { n += 1; }' # stops with "Resource limit 'script.max_operations'"
graphersal --max-traversers 1000000 --max-value-depth 64 -e 'g.v().count().next()'  # also --max-string-size, --max-array-size, --max-map-size

Exit codes: 0 ok, 1 the script failed (diagnostic on stderr), the --graph data violates the --schema, or a --graph <store> cannot be opened (in use by another writer, ...), 2 invalid invocation (unknown option, a graph or schema file that cannot be loaded), 141 stdout was closed before every result was written (graphersal -e '..' | head -1: the run stops quietly; a failing script keeps its own code; the same for graphersal store). A closed stdout or stderr is never a crash: the dev server keeps serving when its log reader goes away. graphersal --help lists every option.

The dev server

DEV mode, unstable, local only (127.0.0.1, no authentication). It serves the playground UI with this process as the engine. Details: Dev Server and MCP.

graphersal --graph modern --server                       # http://127.0.0.1:8080/
graphersal --graph ./mygraph.json --server --port 9000   # any --graph source; "Save to file" writes it back
graphersal --graph large --server --port 0               # 0 picks a free port (the address is printed on stdout)
graphersal --graph data/ --server                        # a Store: every commit is durable, the Store menu appears
graphersal --graph new/ --create-store --server          # create the store when it does not exist
graphersal --graph g.graphml --schema schema.json --server   # a graph file loaded against its schema
graphersal --graph large --server --timeout 5000 --memory-limit auto   # limits apply to every query
graphersal --graph modern --server --ui-dir ~/src/graphersal/playground # its files win over the embedded UI

Stop it with Ctrl+C: a running query is cancelled and an open store is closed cleanly. A second Ctrl+C exits at once. The display options (--format, --max-rows, ...) and -e/--in are refused with --server (exit 2).

MCP: an AI agent on the same graph

graphersal --graph modern --server --port 9000 --mcp                    # MCP endpoint http://127.0.0.1:9000/mcp
graphersal --graph modern --server --port 9000 --mcp --mcp-read-only    # the agent may only read
graphersal --graph modern --server --port 9000 --mcp --mcp-token my-secret-token   # the agent must send the token
graphersal --graph data/ --server --port 9000 --mcp --mcp-query-tools  # also every saved query as a tool of its own

Connect Claude Code (the server must be running; then start a NEW claude session):

claude mcp add --transport http graphersal http://127.0.0.1:9000/mcp
claude mcp add --transport http graphersal http://127.0.0.1:9000/mcp --header "Authorization: Bearer my-secret-token"
claude mcp list                    # graphersal: http://127.0.0.1:9000/mcp (HTTP) - Connected
claude mcp remove graphersal       # when you are done, or before adding it again on another port

AI Chat in the playground (EXPERIMENTAL)

export ANTHROPIC_API_KEY=...                                   # the variable the file names; the key stays in the server
graphersal --graph modern --server --ai ai.json                # "+" in the Query panel -> AI Chat
graphersal --graph modern --server --ai crates/graphersal-cli/examples/ai-ollama.json   # a local model: no data leaves the machine
GEMINI_API_KEY=... graphersal --graph modern --server --ai crates/graphersal-cli/examples/ai-google.json   # Google Gemini (OpenAI-compatible endpoint)

ai.json: {"provider": "anthropic"|"openai", "model": "<id>", "api_key_env": "<VARIABLE>", "base_url": null, "read_only": false, "max_tool_calls_per_turn": 20, "max_tokens": 4096}. Details: AI Chat.

The Store

A Store is one directory (or one .gstore file) that keeps one graph durable. Reference: The graphersal store Command. TARGET below is one of --at-commit N, --at-time 2026-10-08T02:43:00Z (RFC 3339 with a zone, or microseconds since the epoch) or --at-mark NAME.

graphersal store create data/ --from modern          # a new store (or: --from empty|large|tree|FILE|FILE.gsnap)
graphersal store create graph.gstore --from modern   # a single-file store (or: --single-file)
graphersal store create data/ --on-damage continue   # keep committing when damage is found while open (fixed at creation)
graphersal --graph data/ -e 'g.add_v("person").property("name", "zoe").to_list()'   # a durable commit
graphersal --graph data/                             # the REPL on the store (--server: the dev server)
graphersal store mark data/ before-import            # name the current position
graphersal --graph data/ -e 'g.add_v("person").property("name", "ada").to_list()'
graphersal store info data/                          # identity, position, snapshots, marks, WAL size
graphersal store list data/                          # the snapshots
graphersal store marks data/                         # the marks
graphersal store checkpoint data/ --name nightly     # write a snapshot now
graphersal store verify data/                        # scrub every checksum (exit 1 on damage)
graphersal store fork data/ branch/ --at-mark before-import          # a past state as a new store
graphersal store fork data/ branch2/ --at-time 2026-10-08T02:43:00Z  # or --at-commit N
graphersal store backup data/ /mnt/backup/data       # full the first time, incremental afterwards
graphersal store backup data/ weekly/ --full         # always full (the directory must be empty)
graphersal store backup data/ data.zip --zip         # a full backup as one ZIP archive
# every backup checks every checksum in the store and in the copy; damage stops it (repair the STORE)
# a damaged store open in the dev server: Store menu > Back up from memory (POST /api/store/backup {"from_memory": true})
graphersal store export data/ data.gsnap             # the latest snapshot as a .gsnap (--commit N: another)
graphersal store rollback data/ --at-mark before-import   # back IN PLACE; the rest goes to the attic
graphersal store attic data/                         # the attic entries (rolled-back history), with their <ID>
graphersal store attic data/ changes <ID>            # the commits of an entry
graphersal store attic data/ fork <ID> rolled-back/  # keep the rolled-back history as a new store
graphersal store attic data/ restore <ID>            # undo the rollback
graphersal store attic data/ remove <ID>             # or: delete an entry for good
graphersal store rollback data/ --at-commit 0 --delete    # back in place, deleting the rest (no undo)
graphersal store restore /mnt/backup/data            # make a backup the live store (same graph id)
graphersal store restore data.zip restored/          # unpack a ZIP backup as the live store
graphersal store prune data/ --up-to 1200            # remove history only needed before commit 1200
graphersal store compact-advice data/                # is compact worth it now? (cheap)
graphersal store compact data/                       # prune to now; a single file gives its free space back
graphersal store compact data/ --drop-marks          # ... also when marks become unreachable (refused without)
graphersal store convert data/ data.gstore           # a closed store into one file (or back)
graphersal store repair damaged/ --to repaired/      # a damaged store, repaired into a new directory
graphersal store rollback --help                     # the usage of one command (or: store help rollback)

Migrate a store from an older format

A store written by an older Graphersal with an older store format version is refused with The store ... has the older format version N (nothing is changed). Move its current state through a packed snapshot: export it with the OLD binary (the store closed), create a new store from the file with the new one:

old/graphersal --graph old_store/ -e 'g.export_snapshot("graph.gsnap")'   # the OLD binary: the current state
graphersal store create new_store/ --from graph.gsnap                     # this binary (or new.gstore: one file)
graphersal store verify new_store/                                        # then back it up

The new store has the graph, its schema and its catalog (saved queries, compression rules), with the same element ids and commit position, but it is a new store: the marks, the attic (rolled-back history) and the backups of the old store are not carried. old/graphersal store export old_store/ graph.gsnap exports the latest stored SNAPSHOT only (run old/graphersal store checkpoint old_store/ first to include the WAL). Keep the old store until the new one is verified and backed up.

Python

import graphersal
graph = graphersal.Graph.tinkerpop_modern()
graph.save("g.gsnap")                                   # a packed snapshot
graph = graphersal.Graph.load("g.gsnap")
with graphersal.Store.create("data") as store:          # or Store.open("data"); "g.gstore": one file
    store.graph.execute('g.addV("person").property("name", "ann").next()')   # durable
    store.mark("after-ann"); store.checkpoint("nightly"); store.backup("bk")

More: Python and bindings/py-graphersal/README.md.

Tests and checks (contributors)

The full list of build, test, lint, coverage, fuzzing and wasm commands, with the acceptance feature set, is in CLAUDE.md (section "Commands") at the root of the repository; the Python binding's in bindings/py-graphersal/README.md, the playground's in playground/README.md.

Why a Graph?

Many questions are about connections: who knows whom, what depends on what, which path leads from here to there. A graph stores the connections themselves, so such a question is answered by walking along them instead of reconstructing them.

Questions a graph answers well

• Networks of people and things. Friends of friends, colleagues who worked on the same project, customers who bought what similar customers bought.
• Dependencies and impact. Which services break when this database goes down? Which packages pull in this library, directly or through ten others? Which documents cite this one?
• Infrastructure and inventory. Servers, networks, accounts and owners, and how they are wired together: "which public endpoints can reach this host?".
• Hierarchies and trees. Directories, organisational charts, bills of materials: every part below this one, at any depth.
• Paths. The shortest or every route between two things; cycles that should not exist.
• Knowledge. Facts as connected entities, the context an AI agent retrieves before answering (the graph behind "GraphRAG").

Connections as data

Take a small social graph: people are friends with people and like movies.

Which people have a friend of a friend who likes "Terminator"? In Gremlin the question reads like a walk through the picture:

g.v().has_label("person").as("person")   // start at every person, remember it
  .repeat(__.out("friends")).times(2)    // follow "friends" twice
  .out("likes").has("title", "Terminator")
  .select("person")                      // back to the person we started from
  .dedup()
  .values("name")

In a relational database the same question needs a self-join of the friendship table for every hop, and the number of hops is fixed in the SQL text:

SELECT DISTINCT p.name
FROM person p
JOIN friends f1 ON f1.from_id = p.id
JOIN friends f2 ON f2.from_id = f1.to_id
JOIN likes   l  ON l.person_id = f2.to_id
JOIN movie   m  ON m.id = l.movie_id
WHERE m.title = 'Terminator';

"Up to five hops" or "any depth" makes the SQL much harder (recursive common table expressions), while the traversal only changes times(2) into times(5) or into an until(...) condition.

Why it is fast

A graph engine keeps, with every vertex, the list of its edges. Following an edge is a direct step to the neighbour, not a lookup in an index of the whole table, so the cost of a traversal grows with the part of the graph it actually touches, not with the size of the data set. That is why deep or recursive questions stay cheap on a graph and become expensive as joins.

The reverse holds too: a graph is not the best tool for everything. Aggregations over millions of rows of the same shape ("total revenue per month") are what relational and columnar databases are built for. Graphersal is an in-memory engine, so a graph has to fit into memory; see Current Limitations.

Next

The Property Graph Model introduces vertices, edges, labels and properties, and Gremlin in Ten Minutes the steps of a traversal.

The Property Graph Model

Graphersal stores a property graph, the model of Apache TinkerPop and most graph databases.

This is the "modern" sample graph that ships with TinkerPop and with Graphersal (--graph modern, GraphSource::tinkerpop_modern()). It has the four building blocks of the model:

• Vertices are the things: here four people and two pieces of software. Every vertex has an id ("1" is marko).
• Edges are the connections. An edge has a direction, from its out vertex to its in vertex: marko knows josh, josh created ripple. An edge has an id too.
• Labels say what kind of thing a vertex or an edge is: person, software, knows, created. Queries usually start by label.
• Properties are key-value pairs on vertices and on edges: a person has a name and an age, a piece of software a name and a lang, an edge a weight.

$ graphersal -e 'g.v("1").element_map()'
╭─────┬────┬────────┬───────╮
│ age │ id │ label  │ name  │
├─────┼────┼────────┼───────┤
│ 29  │ 1  │ person │ marko │
╰─────┴────┴────────┴───────╯

Values

A property value is a string, a 64-bit integer, a 64-bit float, a boolean, null, a UUID, an array or an object (a nested map). Arrays and objects can be nested, and steps reach inside them with path keys such as jpath("address.city") (Path Keys). Values keep their type: a string that looks like a number or a date stays a string unless a schema declares otherwise. Dates and times come in a later release.

Graphersal additions

• A vertex can carry several labels (person and employee); the first one is its primary label, which label() returns as TinkerPop does (Multi-Label Vertices).
• A graph can have a schema: the labels, their properties and types, and which edges may connect which labels, enforced on every write (Schemas).
• A graph keeps a catalog of named definitions next to the data, such as saved queries (Saved Queries).

No database server

A Graphersal graph lives in the memory of the process that uses it: your Rust program, the Python interpreter, the browser tab or the graphersal command line tool. There is no separate database server to run. When the graph must survive the process, the Store keeps it on disk (Persistence Overview).

Gremlin in Ten Minutes

Gremlin describes a query as a traversal: a chain of steps that traversers flow through. Each traverser sits on a vertex, an edge or a value; a step moves it, filters it out, turns it into something else or combines many of them. All examples run on the "modern" graph (The Property Graph Model): Run in the playground under a block opens it in the playground, or pass it to graphersal -e.

Start, filter, walk

g is the graph. v() starts one traverser on every vertex, has_label and has keep the ones that match, values turns each into a property value:

g.v().has_label("person").values("name")          // marko, vadas, josh, peter

g.v().has_label("person").has("age", P.gt(30)).values("name")   // josh, peter

out(label) walks along outgoing edges, in(label) along incoming ones, both(label) along either:

g.v().has("name", "marko").out("knows").values("name")                  // josh, vadas

g.v().has("name", "marko").out("knows").out("created").values("name")   // ripple, lop

Edges are elements too: out_e steps onto the edges, in_v to their far end, and an edge can be filtered by its properties on the way:

g.v().has_label("person").out_e("created").has("weight", P.gte(0.5)).in_v().values("name")   // ripple

Remember and come back

as("x") names a position of the walk; select, where and path read it later:

// who created software together with marko?
g.v().has("name", "marko").as("me")
  .out("created").in("created")
  .where(P.neq("me"))
  .values("name")                                  // peter, josh

g.v().has("name", "marko").out("created").in("created").path().by("name")
// [marko, lop, peter], [marko, lop, josh], [marko, lop, marko]

Group, count, order

Some steps need the whole stream before they answer: count, group, order, dedup. by(...) modulates the step before it, and __. starts an anonymous traversal that runs for each element:

g.v().count()                                                           // 6

g.v().has_label("person").order().by("age", Order.desc).values("name")  // peter, josh, marko, vadas

g.v().has_label("person").group().by("name").by(__.out("created").count())
// {josh: 2, marko: 1, peter: 1, vadas: 0}

Loops

repeat runs a traversal again and again, times(n) or until(condition) stops it, and emit() also yields the steps in between:

// a path from peter to vadas, in either direction along the edges
g.v().has("name", "peter")
  .repeat(__.both().simple_path()).until(__.has("name", "vadas"))
  .path().by("name").limit(1)                      // [peter, lop, marko, vadas]

Results

A traversal without a final step is displayed (a table in the command line and the playground). In code, a terminal step returns the data: to_list() all results, next() the first one, iterate() runs it for its side effects only.

let names = g.v().has_label("person").values("name").to_list();   // a list
let marko = g.v().has("name", "marko").next();                     // one vertex
names.len()                                                        // 4

Changing the graph

add_v, add_e, property and drop write. Every traversal is one unit: when any step fails, nothing it wrote stays.

g.add_v("person").property("name", "ann").property("age", 41).as("a")
  .v().has("name", "marko").add_e("knows").to("a")
  .iterate();
g.v().has("name", "marko").out("knows").values("name")   // ann, josh, vadas

Two spellings

Every step has a snake_case name and its Gremlin camelCase twin, so a query copied from TinkerPop documentation runs as it is (with double quotes for strings):

g.V().hasLabel("person").outE("created").has("weight", P.gte(0.5)).inV().values("name")

Next

• Graphersal and TinkerPop: what is the same and what is not;
• Writing Queries: the DSL in detail, by topic;
• Step Reference: the steps one by one.

Graphersal and TinkerPop

Apache TinkerPop™ defines the property graph model and the Gremlin language that many graph databases implement. Graphersal is an independent implementation in Rust: it does not use TinkerPop's Java code, and it is not a Gremlin Server, so a TinkerPop driver does not connect to it. What it shares with TinkerPop is the language and its meaning.

Same meaning, checked by TinkerPop's own tests

The rule is simple: a step that Graphersal implements behaves as the TinkerPop specification says, unless a difference is documented. The specification is TinkerPop's own test suite, a set of Gherkin scenarios (TinkerPop 3.8.2) that runs with every cargo test of Graphersal. A scenario that passes once is protected from regressing, and the number of supported steps whose results are wrong is kept at zero. The current numbers are on TinkerPop Compliance.

Not every step exists yet. An unimplemented step is an error that names it, never a silently different result; the gaps are listed in Current Limitations.

Deliberate differences

A few behaviours differ on purpose, each for a reason that is written down. The most visible ones:

• Every traversal is a transaction. A failing traversal leaves nothing behind (Transactions).
• Ids are strings, so they sort as text (Predicates).
• One integer and one float type (int64, float64) instead of Java's number tower.
• A removed element stays removed: reading it through an old reference finds nothing, and writing to it is an error (Dropping Elements).
• No match(), io() or graph-computer algorithms; files are read and written by the API and the command line instead.

Every difference, with its page, is in TinkerPop Deviations.

The query text

TinkerPop's reference language is Gremlin embedded in Groovy or Java. Graphersal's text form is Gremlin embedded in Rhai, a small scripting language for Rust. A Groovy line usually pastes as it is; the differences are small:

The full copy-paste table is in Repeated Labels: select with Pop. Every step also has a snake_case name (has_label, out_e) next to its camelCase one (hasLabel, outE), and the Rust API uses the snake_case names.

Additions

Graphersal adds what an embedded engine needs: schemas, saved queries in the graph, path keys into nested values (jpath), multi-label vertices, change capture, permissions and resource limits, a durable Store, and profile() with memory figures. These are extensions: they do not change what a TinkerPop query means.

TinkerPop Deviations

This page lists every place where Graphersal knowingly differs from Apache TinkerPop 3.8.2, and every known gap that is deliberately not fixed (yet). Pass/fail numbers are on TinkerPop Compliance; the backlog is section 4 ("TinkerPop backlog") of roadmap/first-public-release.md. Each row links to the page that explains the behaviour for users.

The scenarios of the rows select() of an undeclared label, order() of property elements, multi-properties and meta-properties, property(k, null), and asString() of a map, and the families excluded for good (match(), the extra number types, io(), the graph algorithms), are excluded from the compatibility numbers: see Deliberate incompatibilities.

Excluded for good

These TinkerPop features are not planned. Their scenarios are listed by id in INCOMPATIBILITIES (crates/graphersal/tests/tinkerpop/harness/scope.rs) and are outside the compatibility scope.

Dates (asDate, dateAdd, dateDiff, DT, GType.DATETIME) are not in this list: they are planned for 0.2.0 and stay unsupported until then.

Deliberate differences

GraphSON

GraphSON 3.0 import and export is Graphersal's own API, not the io() step (which stays excluded). Where it differs from TinkerPop's GraphSONReader/GraphSONWriter (details and the full type table on GraphSON):

jpath(..) keys wherever a property name is taken

Extension, not a deviation of an existing TinkerPop behaviour. values, properties, has (every form with a key), hasNot, valueMap, elementMap, every property by(), property and remove_property also accept jpath("a.b[1]"), a singular RFC 9535 path into a nested property value (Path Keys). A plain string is always a literal property name, exactly as in TinkerPop, and is never parsed as a path. A missing path is an absent property, not an error. In maps (valueMap, elementMap) the key of a path entry is the canonical path text ($.a.b[1]). json_path("a.b[1]") stays the standalone string-argument step with the same grammar. A side effect of the key conversion: has(null, v) reads the null key as the name "" and matches nothing, which is what the TinkerPop scenario g_V_hasXnull_testnullkeyX expects.

properties(jpath(..)) yields a path property element

Extension, not a deviation of an existing TinkerPop behaviour: properties("name") is exactly as in TinkerPop. properties(jpath("a.b[1]")) (a Graphersal path key, see Path Keys) yields TraverserValue::PathProperty, a materialized property element: key() is the canonical path text ($.a.b[1]), value() the leaf, label()/hasKey() see the path text, id() is the same deliberate error as for any property element, and a terminal materializes the leaf. Reason: a path has no stored property a lazy handle could point at. It is only produced by a path key, never by a plain string.

property(jpath(..), value) writes below a stored property

TinkerPop has no nested property write. Graphersal's property(jpath("a.b[1]"), v) (Path Keys) sets a value inside the stored property a: missing object keys are created, [n] replaces, [len] appends, anything else out of range or of the wrong type is an error (GraphError::InvalidPropertyPath) and never an overwrite. property(Cardinality, jpath(..), v) is an explicit error in v1. With a schema, the written leaf is coerced at its declared nested type and the resulting property is validated, Closed rejecting undeclared nested keys (Schemas and nested paths). A plain string key behaves exactly as in TinkerPop. A traversal as the key (property(select("a"), v)) is still not implemented.

remove_property(jpath(..)) removes below a stored property

TinkerPop removes a property with properties(k).drop(); Graphersal's remove_property(..) is an extension that keeps the element in the stream, and it now also takes a jpath(..) key (user's guide page "Path keys (jpath)"): an object key is removed, an array element is removed with shift, and a missing path or a type mismatch on the way is a no-op, never an error (more lenient than the write side, where a mismatch is an error). properties(jpath(..)).drop() is an error, because a path property element holds no reference to its owner; use remove_property(jpath(..)).

Known gaps, not fixed yet

Counts are in-scope scenarios (missing unless noted; the current numbers are in target/tinkerpop-report.md after a suite run); a scenario can wait on more than one gap.

Why @DisallowNullPropertyValues stays unfixed: the 3 scenarios expect a write of null to remove the property, the 4 @AllowNullPropertyValues scenarios that pass expect it to be stored. Both cannot hold in one mode; the answer is a graph-level null mode (roadmap/first-public-release.md, section 4).

Number-width literals in the test surface

The harness maps 1b/1s/1n to an integer and 1m to a float, so these scenarios pass by value equality only. They do not show byte, short, BigInteger or BigDecimal support:

• map/AsNumber.feature: g_injectX5bX_asNumber, g_injectX5sX_asNumber, g_injectX5nX_asNumber.
• map/Sum.feature (12): g_V_injectX127b_1bX_sumXX, g_V_injectX_128b__1bX_sumXX, g_V_injectX32767s_1sX_sumXX, g_V_injectX_32768s__1sX_sumXX, g_V_age_injectX1000nX_sum, g_injectX1b_2b_3bX_sum, g_injectX1b_2b_3sX_sum, g_injectX1b_26b_3iX_sum, g_V_age_injectX1000nX_fold_sumXlocalX, g_injectX1b_2b_3bX_fold_sumXlocalX, g_injectX1b_2b_3sX_fold_sumXlocalX, g_injectX1b_26b_3iX_fold_sumXlocalX.
• sideEffect/Inject.feature::g_injectXbigintBoundaryValuesX.

That is 16 scenarios. The 8 semantics/Equality.feature Primitives_Number_* scenarios pass the same way (byte, short, bigint and bigdecimal included); Sum of byte values that overflow a byte is the case where TinkerPop and Graphersal would differ without the collapse.

1 ulp float tolerance in the test surface

The harness compares two float64 result values as equal when they are equal or at most 1 ulp apart (NaN equals NaN, infinities exact, +0 equals -0, other signs must agree). The cause is that Rust's libm and Java's Math differ in the last digit of some results (sin(4.0)); Graphersal's arithmetic does not deviate from TinkerPop. The tolerance applies only to float vs. float result values, never to integers, ids, orderings or error cases. It lets the one map/Math sin scenario pass, which is a pass by tolerance, not proof of bit-identical trigonometry.

Which scenarios could expose negate()

Compare.negate() and a plain complement differ only for incomparable operands (NaN, a string against a number). The P.not/negate() scenarios of the suite (filter/TypeOf, filter/Where, filter/HasLabel, integrated/Recommendation) negate typeOf, within or comparisons of numbers, where both agree. The NaN scenarios of semantics/Comparability.feature (not(is(P.gt(NaN)))) use the not() traversal step, which negates the filter result, not the predicate. No vendored scenario exposes the difference.

Current Limitations

What Graphersal 0.1.0 does not do, in one place. Each item links to the page with the details; the deliberate differences from Apache TinkerPop are listed one by one in TinkerPop Deviations, and the steps and scenarios that are not implemented yet in TinkerPop Compliance.

Data model

• No date or time values. They come with a date type in 0.2.0. A GraphSON import skips dates and reports them (GraphSON); a schema refuses "format": "date-time" (Schemas).
• One value per property key. Only Cardinality.single is written; store several values as one array (Upserts). There are no meta-properties: a GraphSON import folds them into the _meta property.
• Ids are strings. A numeric id becomes its text, and ids order as strings ("10" before "9"; see Id Arguments and Predicates).
• Edges have one label; vertices have a label set (Multi-Label Vertices).
• No property index. has(key, value) is checked while the start step scans; only ids and labels are looked up through an index (Query Optimizer).
• The graph lives in memory. A Store makes it durable, but the whole graph is loaded into memory when the store is opened.

Query language

• The DSL is Rhai, not Groovy. Queries read like Gremlin in either spelling (hasLabel or has_label), but maps are written #{..}, child traversals need __. (where(__.out())) and tokens need their class (Order.desc, Scope.local). A Gremlin text query is not parsed as it is.
• No withStrategies() / withoutStrategies(). Execution options are set with g.with(key, value) (Execution Options Reference).
• No g.tx(). Every traversal is one unit of work; a host can run a whole script as one unit (Transactions).
• No Cypher or GQL front end yet; the multi-label storage is the groundwork for one.
• Saved queries only read and are called at the start of a traversal (g.query(..)), not on incoming traversers (Saved Queries).

Schema

• No map type (additionalProperties with a schema), no oneOf/allOf/not, no tuples, and no format other than uuid (Schemas).
• default is an annotation only: it is never written or substituted (default is not applied).

Security and serving

• Read security per element or label does not exist yet; an authorizer decides per request kind and label as the plan states it (Permissions).
• The dev server (graphersal --server, also MCP and AI Chat) is a local development tool: unstable, bound to the loopback, without authentication (Dev Server and MCP).

Other

• Compression rules cover strings at a path of names; values inside arrays are not compressed (Compressed Properties).
• Generated test data is English only.

Rust Quick Start

Add the crate with the features you need (Installation lists them all):

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

• script: the Gremlin DSL as text, the same language as the CLI, the playground and Python;
• io: GraphSON and GraphML files;
• display: results rendered as tables;
• persist: snapshots, the journal and the Store on disk.

The code on this page is the example crates/graphersal/examples/quick_start.rs; run it with cargo run -p graphersal --example quick_start --features script,io,display.

Read

use graphersal::prelude::* brings everything a query needs. A graph is shared behind a lock: a read lock gives a traversal source, the steps are methods, and a terminal (to_list, next, iterate) runs the traversal.

    // The TinkerPop "modern" sample graph: 4 people, 2 pieces of software, 6 edges.
    let graph = GraphSource::tinkerpop_modern();

    // A read lock gives a traversal source `g`; the traversal is built step by step and run by
    // its terminal (`to_list`, `next`, `iterate`).
    let lock = graph.read();
    let friends = lock
        .traversal()
        .v(None)
        .has("name", "marko")
        .out("knows")
        .values("name")
        .to_list()?;
    println!("marko knows {friends:?}"); // marko knows ["josh", "vadas"]
    drop(lock);

v(None) starts at every vertex; v("1") or v(vec!["1", "2"]) at given ids. The Rust names are the snake_case names of the DSL, with a trailing underscore where Rust needs one (as_, in_).

Write

Writes take the write lock and traversal_mut(). A traversal is one unit: it commits when it succeeds and is rolled back completely when any step fails. Anonymous traversals start with __::.

    // Writes take the write lock. Every traversal is one unit: it commits when it succeeds and
    // leaves nothing behind when it fails.
    graph
        .write()
        .traversal_mut()
        .v(None)
        .has("name", "marko")
        .add_e("knows")
        .to_by(__::add_v("person").property("name", "ann"))
        .iterate()?;
    let people = graph
        .read()
        .traversal()
        .v(None)
        .has_label("person")
        .count()
        .next()?;
    println!("people: {people:?}"); // people: Some(5)

Several traversals become one unit with Transactional::transaction; a dry run shows the changes a closure would make without keeping them (Transactions).

The DSL from Rust

With the script feature a query can also be text, for example one a user typed. eval_value returns the result as a script value, eval renders it for display:

    // The same queries as text, in the Gremlin DSL (feature `script`): what the CLI, the
    // playground and Python run. Both spellings work: `has_label` and `hasLabel`.
    let graph = Arc::new(graph);
    let names = graphersal::script::eval_value(
        graph.clone(),
        r#"g.V().has("name", "marko").out("knows").values("name").order().toList()"#,
    )?;
    println!("{names}"); // ["ann", "josh", "vadas"]

    // `eval` renders the result for display: JSON lines, a table with feature `display`.
    let table = graphersal::script::eval(
        graph,
        r#"g.V().hasLabel("software").valueMap("name", "lang")"#,
    )?;
    println!("{table}");

These two helpers allow everything. For a query you did not write, use script::eval_value_with_limits with an Authorizer such as AccessPolicy::read_only() and ScriptLimits (Permissions, Resource Limits).

Files and samples

With the io feature:

        let modern = GraphSource::tinkerpop_modern(); // the samples: also file_tree(), large_110k()
        modern.read().traversal().export_graphson(path)?; // GraphSON 3.0, TinkerPop's format
        let copy = GraphSource::from_graphson(path)?; // also from_graphml, from_file
        let two = copy
            .read()
            .traversal()
            .v(vec!["1", "2"])
            .values("name")
            .to_list()?;
        println!("{two:?}"); // ["marko", "vadas"]

Where to go from here

• the API reference on docs.rs: prelude for queries, the topic modules (schema, changes, auth, catalog, exec, profile, storage, persist) for integration;
• Transactions: units, dry runs, change capture and commit hooks;
• Schemas;
• Persistence Overview: a graph on disk;
• Custom Storages: run the engine on your own storage.

Python Quick Start

The Python package graphersal embeds the engine into the Python process. Queries are Gremlin text, the same DSL as everywhere else, and results come back as plain Python values (list, dict, int, float, str, bool, None, uuid.UUID).

Install

Build the extension from the repository (Python 3.10 or newer, one wheel covers every later version):

cd bindings/py-graphersal
python3.12 -m venv .venv && .venv/bin/pip install maturin
VIRTUAL_ENV=$PWD/.venv .venv/bin/maturin develop --release     # installs `graphersal` into .venv

maturin build --release writes a wheel to install elsewhere; details are in bindings/py-graphersal/README.md.

Query

import graphersal

graph = graphersal.Graph.tinkerpop_modern()      # or graphersal.Graph() for an empty graph

graph.query('g.V().has("name", "marko").out("knows").values("name")')
# ['josh', 'vadas']

graph.query('g.V().hasLabel("person").group().by("name").by("age").next()')
# {'josh': [32], 'marko': [29], 'peter': [35], 'vadas': [27]}

A traversal the script returns is run for you; inside a longer script, end each traversal with a terminal (.next(), .to_list(), .iterate()).

Parameters

Pass values as parameters instead of pasting them into the text; they arrive as script variables:

graph.query('g.V().has_label("person").has("age", P.gt(min_age)).values("name")',
            params={"min_age": 30})
# ['josh', 'peter']

Write

Every query is one unit: when it fails, nothing it wrote stays, and the error is a graphersal.GraphersalError with the diagnostic and its help text.

graph.execute('g.addV("person").property("name", "ann").property("age", 41).iterate()')

try:
    graph.execute('g.V().has("name", "ann").property("age", 42).fail("stop").iterate()')
except graphersal.GraphersalError as err:
    print(err)                                   # the failing step and how to fix it

graph.query('g.V().has("name", "ann").values("age").next()')
# 41: the failed query changed nothing

Files and persistence

graph.export_graphson("people.json")             # GraphSON 3.0; TinkerGraph reads it
graph = graphersal.Graph.from_graphson("people.json")

with graphersal.Store.create("data") as store:   # a graph on disk, every commit durable
    store.graph.execute('g.addV("person").property("name", "bob").iterate()')

Where to go from here

• bindings/py-graphersal/README.md: every method, schemas, access policies, limits;
• Python: snapshots, the journal and the Store;
• Writing Queries: the DSL.

Web Playground

The playground is a single-page web app that runs Graphersal in the browser: the real engine, compiled to WebAssembly (crates/graphersal-wasm), in a Web Worker. There is no server-side part; any static file server can host it. Its source is playground/ in the repository; the developer details (engine boundary, file layout, libraries) are in playground/README.md.

Build and run

rustup target add wasm32-unknown-unknown                      # one-time
cargo install --locked wasm-bindgen-cli --version 0.2.129     # one-time; must match the wasm-bindgen crate
playground/build.sh                                           # builds playground/pkg/
python3 playground/serve.py 8000                              # open http://localhost:8000/ (no browser caching)

wasm-opt (from binaryen) is optional; when it is installed, build.sh uses it to make the module smaller. Without the build output the page explains how to build it.

The same UI also runs against the CLI as a local engine, without WebAssembly: graphersal --graph <src> --server (DEV mode, unstable, local only; see Dev Server and MCP). There the Query panel can also open an AI Chat tab (EXPERIMENTAL, --ai FILE): an LLM agent that answers questions by querying the served graph. In the WebAssembly playground that tab is read-only.

What it does

• Graphs: the empty graph, the TinkerPop "modern" graph, the generated ~110k element graph (the CLI's --graph large), a file tree sample, or a GraphSON (.json, TinkerPop's g.io() format) or GraphML file from your disk (it stays in the browser). What a GraphSON import skips (dates, unsupported types) is shown in a notice.
• Queries: the full DSL, both spellings, with completion from the engine's own function list (each entry's tooltip shows its overloads, a one-line description and a runnable example). A traversal without a terminal runs as execute(), so one run gives the results and, with Profile on, the metrics; Memory adds the exact per-step memory figures (the module installs the counting allocator, so the source is tracked). Results are shown as a table, JSON and the raw text the CLI prints, within the CLI's display limits (see Displaying Results).
• Query tabs: the Query panel holds several queries side by side. Each tab has its own text, Profile/Memory toggles, last result and last profile; switching tabs shows that tab's results without running anything. The graph is shared: when a run in one tab changes it, the other tabs' results are marked "possibly stale" until they run again. An example from the Examples menu goes into the active tab only when that tab is empty or still holds an unchanged example; otherwise it opens in a new tab, so your own text is never overwritten. The tab menu also offers Duplicate tab, Close other tabs and Run all tabs. The tabs (not their results) are kept in the browser; the query history records every run with its tab's name. Shortcuts: Ctrl/⌘+Enter runs the active tab (or its selection, see Run below), Ctrl/⌘+Shift+Enter runs all tabs, Alt+N opens and Alt+W closes a tab, Alt+[ / Alt+] switch to the previous / next tab and Alt+Shift+1…9 to tab 1…8 or the last one (the browser keeps Ctrl/⌘+T, W and 1…9 for its own tabs).
• Statistics, a tab of the Profile panel (next to Steps and Text), shows two sources side by side: the graph's data (g.statistics(): vertex and edge totals, the counts per vertex label, also as primary label, and per edge label; at most 50 labels per kind, largest first) with its memory footprint (g.memory_usage()), and the limits a query runs under: the host's presets (none in the playground; the dev server's --timeout, --max-*, ...) and the engine's defaults for the rest (see Resource Limits; g.with(..) changes them per query). While open it reloads after every run that changed the data.
• Errors show the message, the step path of a runtime error (the same step ids as the profile), the help() advice, a "Go to line" for script errors, and the full diagnostic.
• Graph, Schema, Profile panels draw the graph (capped), show and edit the schema (see The schema editor below; the drawings, a label graph and a Mermaid diagram, show at most 300 labels), and the optimized plan with timings, traverser counts, loop statistics, path recording and memory. The Graph panel draws the whole graph when it has at most 10 000 vertices and 20 000 edges (Settings), else its labels; it also draws the neighbourhood of a vertex and the last query result. Clicking a vertex or an edge shows its properties, fetched from the engine at that moment (the drawing itself carries only ids, labels and names); double-clicking a vertex in the neighbourhood or the query result expands it by one hop from the engine (in the whole graph: selects it with its neighbours, again for one hop more), double-clicking empty space fits the drawing. Above 200 vertices the engine lays the drawing out (with progress and Stop) instead of the browser. See The graph drawing below for what the panel shows and its two drawing tiers.
• Run (or Ctrl/⌘+Enter) runs the selected text when the editor has a selection, else the whole tab, so a script can be tried piece by piece. The button then reads Run selection, and the status bar and the Results header say "selection (N lines)". A selection of only whitespace runs the whole tab; with several selections (Alt+drag) only the main one runs. Everything else is a normal run: one unit (committed only when it succeeds), the history records the text that ran, Profile and Memory apply, and an error's "Go to line" points into the full text of the tab. Run all tabs always runs whole tabs.
• Stop (next to Run) ends a long query: the engine is restarted and the graph restored as it was last loaded (sample or file) or last saved. Changes made after that point are lost, and so is the history of the store in memory (it starts over from that state). While no query runs but the graph drawing is being laid out, Stop ends only the layout: the drawing keeps the positions reached so far and nothing is restarted.
• Save ▾ (top bar; the start page has the same entries as buttons) downloads ONE file per entry: the graph data as GraphSON 3.0 (graphersal-graph-YYYYMMDD-HHMMSS.json) or GraphML (.graphml), the schema (graphersal-schema-YYYYMMDD-HHMMSS.json; neither data format carries it, see UUID Values), the saved queries, or a snapshot (.gsnap) with data, schema and saved queries in one file. One file per click, because browsers block or drop a second download started by the same click. To load both back, choose both in Load from file on the start page: the graph file and, in the dialog's optional second field, the schema file (JSON). The schema is set on the new, empty graph first and the data is imported against it as one unit, so the elements, ids, labels, properties and the schema come back; in mode open or closed a violation fails the load with the error and nothing changes. Load from file always starts without the previous graph's schema: a graph file loaded without a schema file has no schema (a previous graph's schema has nothing to do with an unrelated file). Dropping ONE file on the card loads it without a schema; dropping a graph file together with its .json schema pairs them when that is unambiguous (the graph file is GraphML, .jsonl or .graphson; two .json files are refused, choose them in the dialog). A snapshot (.gsnap) brings its own schema and takes no schema file. GraphSON keeps every value type (uuid, lists, maps) by itself; GraphML gets them back from the schema's declarations, and Save warns about values that come back as strings without one (an undeclared uuid, lists and maps, a property with different types on different labels).
• Load schema applies a JSON file in the schema format (set_schema) to the current graph. In mode open or closed the existing data is validated first; on violations nothing changes and the error is shown. It changes only the current graph: a graph loaded from a file afterwards does not keep it (give the schema file in Load from file instead).

Scripts run without Rhai resource limits and without a default timeout, as in the CLI: the page is your own local front end, and Stop ends a runaway query or loop. Every run starts with a fresh script scope; the graph keeps the changes queries make until you load another one.

A run is all-or-nothing: the whole script is one unit of work, and a run that shows an error leaves the graph as it was before the run (see Transactions). Scripts may do everything except file access, which the browser does not have (see Permissions).

Links to a query

A link can open the playground on a sample graph with a query in the editor, and run it:

https://play.graphersal.dev/#/play?graph=modern&q=g.v().has_label(%22person%22).values(%22name%22)&run=1

The parameters are in the fragment (after #), so the browser never sends them to a server. The query goes into a new tab when the current one holds your own text. When a graph is already open in the page, the playground asks before it replaces it; declined, the query is only put into the editor. The address then goes back to #/play, so a reload does not apply the link again. With the dev server a link only opens the query: the served graph is your own data, so nothing is replaced and nothing runs.

The book uses these links: every example that runs on a sample graph has a ▶ run button next to each of its queries (or a Run in the playground link under a block with one query).

The graph drawing

What the panel shows

Drawing "the first 1000 vertices" of a large graph shows an arbitrary slice of it. The Graph panel's tabs choose a meaningful part instead:

• Whole graph: the graph itself when it has at most the vertex and edge limits of the settings (10 000 vertices and 20 000 edges by default). A larger graph shows its labels (below) with a note saying how large it is; Draw the first N vertices anyway draws that slice (said to be one), Double the limits raises them.
• Labels: the label overview. Each vertex label is a node sized by its number of vertices, each edge is a label pair (person –created→ software) with its number of edges. The 40 largest labels are drawn, the others form one "other labels" node; the 200 largest pairs are drawn and the note counts the rest. The counts come from the graph's statistics and one pass over the edges, so they are exact (for graphs with more than five million edges, the pairs are counted over the first five million and the note says so). Double-click a label to draw a sample of its vertices with the edges between them, double-click an edge for a sample of that label pair. A sample is the first matching elements in storage order (at most 1000 vertices), not a random choice, and its note says how many of how many it shows.
• Neighbourhood: a vertex and its neighbours, fetched from the engine. Type a vertex id (or click Neighbourhood in a vertex's properties, or the ⌖ button of a vertex row in the Results table) and choose the Depth (1 = the direct neighbours, 2 = their neighbours too, up to 5) and the direction: both, out → (the vertices it points to) or ← in (the vertices pointing to it); changing either redraws from the same vertex. Double-click a vertex to expand it by one hop (along the chosen direction): its neighbours are added, everything already drawn stays where it is and the new vertices are placed around it. The note says how many edges still lead out of the drawing, and when the limits (Settings) cut the neighbourhood, how many vertices and edges within that depth were left out.
• Query result: the vertices, edges and paths the last query returned, with the edges between them. At most 50 000 vertices + edges by default (Result graph in the settings, up to 200 000; the result's data itself is never cut); the note says when a result has more. Double-click a vertex of the result to expand it by one hop from the engine, like in a neighbourhood: the drawing continues as a neighbourhood ("the query result, expanded"), the result's vertices stay in place, and further double clicks keep expanding. A result with more vertices than the drawing limit is not expanded (the note says so; open a vertex's neighbourhood instead).

Editing properties

Click a vertex or an edge for its properties, then the pencil next to the close button: a dialog edits them. Each property is one line with its name, its type (string, int64, float64, boolean, uuid, array, object, null), its value and its buttons, in columns aligned across the rows (in a narrow window a property takes two lines); a changed or invalid property is marked at its left edge. The last line adds a property: name, type and value, then + Add or Enter. Remove (with undo) and rename properties. Arrays and objects are edited as a tree below their line (expand, collapse, add and remove items and keys); the { } button edits any value as JSON, Edit as JSON (next to Save) the whole element. A string always stays a string, whatever it looks like, until you pick another type. Long or multi-line strings, and every string a compression rule covers, get a large text box below their line (⤢ opens one for any string).

When the graph has a schema, the dialog follows it: the properties of the element's label(s) are listed (also the ones not set yet), required ones are marked with *, the type, bounds and description are shown under each line, and an enum is a menu. Every change is checked by the engine before you save; its errors appear next to their fields and Save stays disabled until they are fixed. Saving writes all changes as one commit: if the engine still refuses (for example the schema changed meanwhile), nothing is applied and the dialog stays open with the error. Ids and labels are shown but not edited. The pencil is disabled, with the reason as its tooltip, while a query runs and when the graph cannot be written: a read-only view of a past state (Store menu), a backup, or a store in maintenance mode.

Edit mode

The Edit mode switch in the Graph panel's toolbar turns the mouse into an editor of the graph:

• Add a vertex: double-click empty space. A dialog asks for the label (a menu of the labels the schema declares and the graph already has; any label can be typed unless the schema is closed), an optional id (empty: automatic) and the properties, laid out by the label's schema (required ones are already there, *). The vertex appears where you double-clicked.
• Add an edge: drag from one vertex to another (a dashed line follows the pointer; back onto the start vertex after leaving it makes a loop). The label menu offers the schema's edge labels whose connections allow the two vertices (* matches any label, any label of a multi-label vertex counts), then the graph's other edge labels; with a closed schema only the allowed ones.
• Delete: select a vertex or an edge (click it) and press Delete, or use the bin in its card. A confirmation says how many edges go with a vertex.
• Edit properties: double-click an element (or use the pencil), as above.

Every draft is checked by the engine with a dry run, its errors shown at their fields; each change is one commit. The drawing changes in place: the other vertices keep their positions and no layout runs. In edit mode vertices cannot be dragged around (a drag draws an edge). The Fast tier edits and deletes but adds nothing with the mouse (switch to Detailed to add). Edit mode is off, with the reason as its tooltip, in the Labels overview and when the graph cannot be written (a read-only view of a past state, a backup, a store in maintenance mode or frozen by damage).

A small cloud inventory (58 vertices, 91 edges) in the three views:

Tiers

The Graph panel draws in one of two tiers:

The switch Auto / Detailed / Fast in the panel's toolbar (also in Settings) chooses the tier; Auto decides by size, with a margin so a drawing does not flip back and forth around the threshold. Switching keeps the drawing's positions. In the Fast tier a banner says what it lacks, and the controls it cannot honour (edge labels, the Concentric and Tree layouts) are disabled with the reason as tooltip. The schema drawing and the label overview always use the Detailed tier.

Drill down: in the Fast tier, click a vertex (or double-click it to select its neighbours, again for one hop more) and choose Open in Detailed: that neighbourhood is drawn in the Detailed tier, with every label and style; Back to the whole drawing returns.

A drawing waits for an explicit Draw it only where it can still make the page slow: Detailed forced above 5000 vertices + edges, the Fast tier above 200 000. A browser without WebGL (or where the Fast tier's scripts cannot load) draws in the Detailed tier, at most 10 000 vertices + edges, and says so. The Fast tier's scripts are loaded only the first time a drawing needs them.

The Fast tier draws the first 10 000 vertices of the generated 110k-element graph:

Saved queries

Saved queries are named, parameterized, read-only queries stored in the graph. The top bar's Catalog ▾ ▸ Saved queries manager lists them by folder (the description and the signature; a query whose body no longer compiles is marked error) and manages them, on the WebAssembly playground and on the dev server alike:

• New saved query… / ✎ opens the editor: name, folder, description, the parameter list and the body. Each parameter has a name, a type (string, integer, number, boolean, uuid, array of one of these, object, or a schema written as JSON), constraints (minimum and maximum, length, pattern, allowed values), a default (empty: the parameter is required) and a description; ↑/↓ reorder and ✕ removes one. The body is what goes inside the function, in the code editor with the DSL completion; the line fn name(a, b) { above it follows the parameter list, so a parameter is added or renamed in one place. Save stores it (a rename replaces the old name in the same commit); what the engine refuses is shown next to its field (a bad name or folder, a parameter whose default breaks its schema, a body that does not compile). Moving a query to another folder is changing its folder here. Delete… asks first.
• Clicking a query opens its run form, built from the parameter schemas: a number field with its minimum and maximum, a list for allowed values, a checkbox for a boolean, UUID text that is checked, one line per item for a list; defaults are prefilled and required fields marked with *, the descriptions are hints. Run writes the call, for example g.query("older_than", #{age: 29, label: "person"}), into a query tab and runs it there: it is visible, editable and in the history like any other query. The form remembers the last values per query (in the browser). An empty field takes the parameter's default.
• In the editor, g.query(" completes the names of the saved queries, grouped by folder.
• Saved queries travel in the catalog file, like the schema: Catalog ▾ ▸ Save catalog (.json) (graphersal-catalog-YYYYMMDD-HHMMSS.json, also Save catalog on the start page) holds the whole catalog, saved queries and compression rules (and future kinds such as indexes); Catalog ▾ ▸ Load catalog… (or Load catalog on the start page) adds the file's definitions to the current graph (one of the same kind and name is replaced; a compression rule compresses its values at once). A graph loaded from a GraphSON or GraphML file afterwards keeps them; a sample graph starts without any, a snapshot (.gsnap) brings its own. Stop keeps the catalog the page loaded or edited (like the schema); definitions a script made since the last load or save are gone with the rest of the run's changes.

The Catalog

The top bar's Catalog ▾ lists what the graph stores besides its data and schema, each kind with its count, and opens its manager:

• Saved queries: the queries by folder with Run…, Edit…, Delete and New saved query… (the editor and run form described above).
• Compression: the compression rules with their stats (compressed values, plain and stored size, ratio, saving, dictionary size), Edit…, Recompress and Drop, and New rule…: a form with name, element (vertex or edge), label (the graph's labels are suggested), path, minimum size and dictionary; the engine's errors show next to their field. Saving re-encodes the label's values at once.

The same dropdown holds Save catalog (.json) and Load catalog…. The Statistics tab of the Profile panel shows the compressed strings and the dictionaries in its memory part when there are any.

A catalog change is a commit: in the store in memory it is part of the history, and on the dev server another browser tab or an AI agent sees it through the change feed.

The store in memory

Every graph you load is kept as a Store in memory: every run that changes the graph is a commit, and the Store menu in the top bar checkpoints, marks, opens past states read-only, forks and rolls back. Everything in memory is lost on page reload: download a .gsnap to keep a state. The details are on the page The Store in the Playground.

The schema editor

The Schema panel's Tables tab shows the schema (the stored one, or, without one, the schema inferred from the data; the badge says which) as nested tables on one page: a table per vertex and edge label, one row per property with its type, required, nullable and a compact constraint column (0..150, length 1..80, ^\d{5}$, <= 10, one of a, b). A nested object is a table inside its row; arrays show as array of T (an array of objects gets the item table); objects deeper than the first level start collapsed as object {n fields}. The format is described in Schemas.

Everything is edited in place, and every edit changes a draft, never the stored schema:

• the type (a dropdown; uuid is string + format: "uuid", any is {}; a union of several kinds is edited in the JSON tab), required, nullable, the property name, a + property row in every table, and a detail form per property (open it from the constraint column) with the constraints of its type, enum, const, additionalProperties for objects, and the annotations title, description, default, examples, $comment, deprecated;
• labels: add, rename (a renamed vertex label is renamed in the edge connections too), remove; the connections of an edge label with from/to dropdowns (* is any label; no connection allows every pair); additionalProperties per label;
• the mode (toolbar) and meta (free JSON);
• the JSON tab is the same draft as text, synchronised both ways: text that parses becomes the draft, invalid JSON is shown inline while the tables keep the last valid state;
• Infer from data starts a draft from infer_schema(); Load… reads a schema.json into the draft; Download saves what the editor shows as schema.json;
• Freeze as open / Freeze as closed (offered while the graph stores no enforcing schema and no draft is being edited) store the inferred schema with that mode in one step, set_schema(infer_schema(), mode): see Freeze the structure you have. It always applies, except closed with vertices or edges without a label: then nothing changes and the report is shown.

default is shown as what it is: information for clients, never applied on write or read (see default is not applied); the editor uses it only as the value its backfill script fills in.

With a draft, the toolbar offers the review and the apply:

1. What changes lists the changes from the stored schema (diff_schema), each marked backward compatible or not (compatible: it only adds or relaxes, so data and clients written against the old schema keep working; adding an optional property is compatible, removing one is not; see the rule set). Existing data that conflicts is what the next step finds.
2. Check against data validates the existing data against the draft (validate_schema_patch; nothing changes) and lists the violations grouped by rule. A click on a group opens a new query tab that runs a query showing the offending elements (g.V().hasLabel("person").not(__.has("email")) for a missing required key, the sample ids for a constraint violation).
3. Apply stores the draft with patch_schema (a JSON Merge Patch computed from the stored schema; one unit, all or nothing). It checks first and is blocked while the data violates the draft. To make a key required on existing data, Open a backfill script writes the recipe as one run: the draft with mode none, a property(key, value) for every element that lacks the key (the draft's default, or a placeholder to edit), then the draft itself; a playground run is one unit, so nothing is kept unless all of it succeeds.

Discard drops the draft. A draft that sets a member to null ("default": null) cannot be a merge patch; Apply then uses set_schema with the whole draft. The editor talks to the engine only through the seven schema methods, the same as in Rust, the DSL and Python. The Graph and Mermaid tabs draw the stored (or inferred) schema, not the draft.

When the panel infers. Inferring a schema reads the whole graph, so the panel does it only when it is first shown (expanded) and when you press its refresh button, never after every change of the graph. A stored schema is read again after every change (a schema set or changed by a query shows at once). Without one, a change (a query that writes, the property editor, a change made in another tab or by an AI agent) keeps the schema inferred last on screen and adds the badge may be outdated - refresh next to the refresh button; press refresh to infer it again. The same badge appears when the stored schema is dropped. Loading another graph, opening a read-only view of the Store, going back to the live graph, rolling back or switching databases replaces the graph: the panel infers once for it, right away if it is shown, else when you open it. The WebAssembly playground and the dev server behave the same.

If the playground freezes

Open the playground's address with /reset added (for example http://localhost:8000/reset/). That page loads nothing of the playground itself: it removes the playground's saved state from the browser (settings, panel layout, theme, query tabs, view choices; the query history is kept) and then opens the playground with the Modern sample graph. Use it when a saved state makes the page hang again after every reload, for example a huge drawing that is restored on start.

Dev Server and MCP

DEV mode, unstable, local only, temporary. The dev server is a way to try Graphersal "as a small server" and watch how it behaves. Its HTTP API is internal to the playground and changes without notice; it has no authentication and serves only the loopback (127.0.0.1, and [::1] when the system has IPv6). Do not expose it.

graphersal --server serves the Web Playground UI over HTTP, with the CLI process itself as the engine instead of the WebAssembly worker. It is the same single-page app: the page asks the serving origin GET /api/info at start, and when a Graphersal dev server answers, every engine call goes to it over HTTP. Served from GitHub Pages or any static file server, the page stays the WebAssembly playground.

Start it

cargo run -p graphersal-cli -- --graph modern --server            # or: graphersal --graph ... --server
# Graphersal dev server: http://127.0.0.1:8080/
graphersal --graph ./mygraph.json --server --port 9000            # a GraphSON or GraphML file
graphersal --graph large --server --port 0                        # 0 picks a free port
graphersal --graph data/ --server                                 # a Store: every commit is durable
graphersal --graph new/ --create-store --server                   # create the store when missing
graphersal --graph g.graphml --schema schema.json --server        # a graph file loaded against its schema

• --graph takes the same sources as the CLI: modern (default), empty, large, tree, a GraphSON (.json, .jsonl, .graphson) or GraphML (.xml, .graphml) file, a packed snapshot (.gsnap), or a Store (a directory or a .gstore file; see On a Store).

• --port (default 8080; 0 picks a free one). The address is the only line on stdout; the "dev mode, unstable, local only" banner goes to stderr.

• The playground UI is embedded in the binary (its static files: index.html, css/, js/, assets/, reset/), so graphersal serves it on its own, from any working directory. --ui-dir <DIR> names a directory whose files win over the embedded copy (for working on the UI); a file missing there comes from the embedded copy. Without --ui-dir, ./playground is used that way when it exists (a repository checkout), else the embedded UI alone. An explicit --ui-dir that does not exist is a usage error. The stderr banner says where the UI comes from: UI: embedded or UI: <dir> (embedded fallback). A path leaving the UI root (..) is a 404.

• After the graph is in memory, stderr shows how long loading took and what was loaded, from the same data as the playground's Profile -> Statistics tab: the load time (sample build, file import with --schema, .gsnap load, or Store open = snapshot load + WAL replay, with the number of WAL commits replayed), the vertex and edge totals, the ten largest vertex and edge labels (+N more for the rest), the graph's memory (structure, indexes, properties) with the process heap, and the compressed values when there are any:

  Loaded in 34.3 ms: 6 vertices, 6 edges
  Vertex labels (2): person 4, software 2
  Edge labels (2): created 4, knows 2
  Memory: graph 5.5 KiB (structure 2.2 KiB, indexes 1.1 KiB, properties 2.2 KiB); process heap 1.9 MiB
  Limits: none (start with --timeout, --memory-limit, --safe-limits, --max-* to bound queries)
  

  On a Store the first line reads Loaded in 53.6 ms (snapshot + 2 WAL commits replayed): ....

• The limit options of the CLI apply to every query of the server (see Limits). The display options (--format, --max-rows, --max-items, --no-limit, --spelling) are refused with a usage error, because the UI sets the display per query; -e/--in cannot be combined with --server either.

• Stop the server with Ctrl+C (SIGINT) or SIGTERM: a running query is cancelled (it rolls back) and an open store is closed cleanly; the exit code is 0. A second Ctrl+C exits at once.

The server needs no WebAssembly build: playground/pkg/ is not used in this mode.

Limits

The limit options become session presets: every query sent to the server runs under them, as every script of the one-shot runner does (the resource limits page explains each limit).

A query overrides a traversal option with g.with(..) (for example g.with("evaluationTimeout", 0)), as in the CLI. The values in force are listed on stderr at start ("Limits of every query: ...", or "Limits: none (...)" without limit options) and in GET /api/info (presets). Without limit options the server runs like the playground: no script limits, the engine's traversal defaults, no time budget; Stop is the way to end a runaway query.

graphersal --graph large --server --timeout 5000 --memory-limit auto

What the UI does in this mode

• A red DEV SERVER · unstable badge in the top bar. There is no start page and no graph choice: the server serves the one graph it was started with. To use another graph, restart the server.
• Queries, results, profiles, the graph drawing, the schema views and the schema editor work as in the WebAssembly playground: both run the same session code (the internal crate graphersal-session), so the answers are the same structures.
• The Statistics tab of the Profile panel shows the limits the server applies (its presets, from the options above) beside the engine's defaults for the rest, next to the graph's counts and memory footprint.
• Several browser tabs share the one graph. Queries run one after the other. A change made in another tab (or by an AI agent, see MCP and AI Chat) reloads the page by itself within about 2 seconds and shows "changed: commit N".
• Stop cancels the running query on the server: it stops at its next check (where evaluationTimeout is checked, plus the script loop), fails with "cancelled", and everything it changed is rolled back. The graph stays as it was before the query; nothing restarts. Stop cancels whatever query runs, also one started from another tab.
• Save ▾ downloads the graph data (GraphSON or GraphML), the schema (JSON) or a snapshot, one file per entry, as in the playground. Save to file appears when the server was started with a graph file: it writes the graph back to that file in its format (GraphSON, GraphML or a packed snapshot), atomically (a temporary file next to it, then a rename). The stored schema is not part of a GraphSON or GraphML file: with --schema FILE Save to file writes the schema back to that file too (atomically, both temporary files are written before either is renamed; a cleared schema is written as {}). Without --schema, saving a graph that has a schema shows a warning (the schema is not part of a GraphML/GraphSON file: download it with Save schema, or start the server with --schema FILE); no file is ever written beside the graph implicitly. A snapshot (.gsnap) is lossless: schema and saved queries included.
• Without a Store directory nothing is saved automatically, and nothing survives a restart of the server. On a Store directory every commit is persisted (below).

Safety

The server is a local development tool: it binds the loopback only, 127.0.0.1 and, when the system has IPv6, [::1] on the same port (stderr then says Also listening on http://[::1]:<port>/ (IPv6 loopback); if that bind fails the server stays on IPv4, silently; the URL on stdout is always http://127.0.0.1:<port>/). There is no option to bind elsewhere. It has no authentication, and refuses requests whose Host (127.0.0.1, localhost or [::1] with the server's port) is not the server itself or whose Origin is another site; every write needs Content-Type: application/json, which a page of another site cannot send without a CORS preflight that the server never answers. Scripts cannot read or write files (as in the playground: file access is denied), so a file is written only by the explicit Save to file. Request bodies are limited to 16 MiB; a malformed request gets a 4xx answer with a JSON error. A request that declares a body larger than 64 MiB (Content-Length) is ignored without an answer: the HTTP library would otherwise reserve memory for the whole declared size.

On a Store

graphersal store create data/ --from modern      # once (or: --graph data/ --create-store --server)
graphersal --graph data/ --server                # then open http://127.0.0.1:8080/
graphersal --graph new/ --create-store --on-damage continue --server   # a new store, its damage policy

The server opens the Store read-write (its lock is held while it runs) and serves its graph: every commit is written to the store's write-ahead log before the query answers, so writes survive a restart of the server, also a crash or kill -9 (the next start replays the WAL; stderr then notes that the store was not closed cleanly, which is harmless). Stopping the server with Ctrl+C is such a stop: everything committed is already on disk.

The store's warnings go to stderr as WARN graphersal::persist::store: ... lines: a failed automatic checkpoint, damage found while it runs, a read-only open (also when the store is used with -e, --in or the REPL); an open that rewrote a damaged GRAPH copy notes it on stderr before the start banner. GRAPHERSAL_LOG sets the level (off, error, warn = the default, info, debug, trace; info also notes a checkpoint that encodes the loaded graph because the WAL since the last snapshot exceeds the merge bound). A whole script is ONE commit here, and one commit is at most 1 GiB of uncompressed WAL record: a script that drops and re-creates a large graph can be refused as a whole; run the drop on its own and load in several runs (The size of one commit).

The UI shows a Store menu in the top bar (its ↻ button in the top right corner reloads it): the position (commit number and last commit time), the WAL size, Checkpoint (write a snapshot now, optionally named) and Mark (name the current position), and the history:

• Marks: "a name for a position in the history; any commit can be restored, not only snapshots". Snapshots: "a full copy of the graph at a commit (fast start)", each with a .gsnap download. The menu lists the newest five of each; Calendar… (See all… when there are more) opens the history calendar below. The table in Snapshots and marks compares them.

• Every snapshot and mark has three actions, and Go to commit... / Go to time... (a date and time in your browser's time zone) offer the same for any other point:

  • Open read-only here (View): the server serves the state at that point instead of the live graph. A banner says "Read-only view of commit N (mark X)" and offers Back to the live graph. Queries, the graph drawing, the schema and the statistics show that state; every write is refused ("the served state is a read-only view at commit N ...: writes are refused"; its help points to Back to the live graph and to a fork), and so are Checkpoint and Mark. The live graph is not changed; Download current state saves the view.
  • Fork to a new directory...: asks for a directory (empty: <store>-fork-<target> next to the store; a relative path is next to the store; it must not exist) and makes a new store there. The answer says where it is and how to open it (graphersal --graph <new> --server --port 0, another server). This store is not changed; to undo, delete the new directory.
  • Roll back here...: a confirmation explains the effect: everything after commit N moves to the attic (restorable as long as nothing new is committed or marked), the live graph switches to commit N. The option "delete instead of keeping in the attic" (off by default) deletes it for good. The server cancels the running query, rolls the store back in place and serves the result at once; the Graph, Schema and Statistics panels reload and every tab's result is marked as possibly stale.

• Attic: one entry per rollback (when, commit range, size) with Show changes (per commit: time, author, counts by kind, examples), Restore (undo the rollback; disabled with the reason once something was committed or marked since, then use Fork), Fork... (the rolled-back history as a new store) and Remove... (delete it for good, asks first).

• Disk space: the compaction advice, refreshed with the menu (cheap, nothing is read): "Compact recommended" or "No compaction needed" with the reason (which threshold decided), the file's size, live and free-inside bytes for a single-file store, what a prune would free first, and the free disk space a compaction needs. Compact (always enabled, except in a read-only view, in maintenance mode or on a store frozen by damage; when the advice does not recommend it, it asks first, showing what it would free and the reason; when marks would become unreachable it ALWAYS asks first, recommended or not, naming them and saying they cannot be opened afterwards) prunes up to the current commit and, for a single file, rewrites it without its free space; queries wait while it runs. On a directory store Compact is the prune.

• Backup: a directory (empty: <store>-backup next to the store, which takes increments from then on; a relative path is next to the store) and full; Back up copies the store while queries and commits go on, reading every checksum in the store and again in the copy. The answer says how much was copied and how to restore it.

• The store's creation parameters: when it was created and its damage policy ("on damage: maintenance (turns read-only; fixed at creation)").

• Damage found on disk while the server runs (a Back up, a Checkpoint, Verify, the automatic checkpoint found it): a red block with what found it, every problem, and what the policy did (with maintenance the store is READ-ONLY now: Checkpoint and Mark are gone, writes are refused); Back up from memory writes the intact graph in memory into a new directory without touching the damaged store, then repair the store with graphersal store repair. A banner at the top says the same in every tab (through the change feed), and MCP's graph_info carries it (damageFound), so an agent learns why writes fail.

The server runs on a single-file store the same way (graphersal --graph graph.gstore --server, --create-store creates it); a fork of it becomes a .gstore file next to it (graph-fork-<target>.gstore).

Opening a view, going back to live, a rollback and an attic restore change the graph the session serves, so they cancel a running query first (it rolls back). Several browser tabs share the one server: a view opened in one tab is the view of all (the other tabs follow through the change feed within two seconds: banner, graph, Schema and Statistics; an MCP agent's graph_info says so too and its writes are refused). The CLI's graphersal store commands that only read (list, fork, verify, ...) work while the server runs; rollback and attic restore from the CLI report "in use" then, use the menu.

On a backup directory (graphersal --graph backup/ --server) the server serves the backup read-only: a banner says "Backup: read-only" with its position and the command that makes it the live store (graphersal store restore backup/, after stopping the server); the Store menu shows the backup's snapshots and marks with View and Fork only (no Checkpoint, Mark or Roll back), and every write is refused. See Backup and Restore.

The history calendar

A store keeps hundreds or thousands of snapshots and marks; the Store menu shows only the newest five of each. Calendar… opens a dialog with a month calendar of all of them: each day shows two badges, the number of marks (M) and of snapshots (S) on that day in your browser's time zone (a snapshot counts on the day of the commit it holds), their colour deeper the more there are. ‹ › and the month and year selectors (each month with its counts) move through the history; Today, Newest and Oldest jump. A click on a day (or Enter) lists all its marks and snapshots with time and commit and the same actions as the menu (View, Fork…, Roll back…, .gsnap). The filter keeps marks and/or snapshots and matches a name or #commit. Keyboard: the arrows move between days (across months), PageUp/PageDown change the month, Home/End go to the start or end of the week, Esc closes. The WebAssembly playground's store in memory has the same calendar.

MCP: an AI agent on the same graph

With --mcp the server also offers a Model Context Protocol endpoint at http://127.0.0.1:<port>/mcp. An AI agent such as Claude Code then works with the same graph and session as the browser: you watch and query in the playground while the agent queries, changes the graph or evolves the schema through MCP tools, and the page reloads by itself when the agent changed something. MCP works with the graph only: persistence (checkpoints, marks, views of past states, rollback, the attic, backups, compaction) stays in the browser's Store menu, so the agent's tool list stays short.

Start the server with MCP

graphersal --graph modern --server --port 9000 --mcp
# Graphersal dev server: http://127.0.0.1:9000/        (stdout)
# MCP endpoint: http://127.0.0.1:9000/mcp              (stderr, with the claude mcp add command)

Any --graph source works, a Store directory too (the agent gets the same graph tools; the commits it makes are journaled like the browser's):

graphersal --graph data/ --server --port 9000 --mcp

Read-only for the agent (only the reading tools are offered, and a query that would create, change or delete data, the schema or a catalog definition (a saved query, a compression rule) is refused; the browser can still write):

graphersal --graph modern --server --port 9000 --mcp --mcp-read-only

With a token (every MCP request must send Authorization: Bearer <token>, otherwise 401):

graphersal --graph modern --server --port 9000 --mcp --mcp-token my-secret-token

With every saved query as a tool of its own (besides list_saved_queries and run_saved_query, which are always there), for a small, curated catalog:

graphersal --graph data/ --server --port 9000 --mcp --mcp-query-tools

The options combine (--mcp --mcp-read-only --mcp-token ... --mcp-query-tools), and the limit options apply to the agent's queries as to the browser's.

Connect Claude Code

claude mcp add --transport http graphersal http://127.0.0.1:9000/mcp

With a token:

claude mcp add --transport http graphersal http://127.0.0.1:9000/mcp \
  --header "Authorization: Bearer my-secret-token"

Check the connection, and remove the entry when you are done:

claude mcp list                  # graphersal: http://127.0.0.1:9000/mcp (HTTP) - ✔ Connected
claude mcp remove graphersal

claude mcp add stores the server for the current project directory (-s user makes it available everywhere). A newly added MCP server is picked up by a NEW Claude Code session: start claude again (or start it after adding). Use the same port as the running server; when you restart the server on another port, remove and add the entry again. The server must be running when Claude Code starts, or claude mcp list shows it as failed (start the server, then a new session).

Try it

1. graphersal --graph modern --server --port 9000 --mcp, and open http://127.0.0.1:9000/ in the browser: the top bar shows an MCP badge.
2. claude mcp add --transport http graphersal http://127.0.0.1:9000/mcp, then start claude.
3. Ask: "Use the graphersal tools: who does marko know?". The agent calls query with a traversal such as g.v().has("name", "marko").out("knows").values("name"). The badge's tooltip now names the agent (claude-code).
4. Ask: "Add a person ada, 36 years old, who knows marko." The browser reloads its graph by itself and shows "changed: commit N"; results you ran before are marked "possibly stale".
5. Ask: "Infer the schema, store it in mode open and add an optional string property email to person." (infer_schema, set_schema, patch_schema); the Schema panel follows.

What the agent gets

The server introduces itself as graphersal-dev with instructions that explain the query language. Tools (each one queues on the server's session like a browser call; read-only tools are marked readOnlyHint, query, set_schema and drop_compression destructiveHint). The list is the same on every --graph source; there are no persistence tools:

A read-only view opened in the browser is server-wide: the agent's queries read that past state too. graph_info then carries a note ("the served state is a read-only view at commit N ..."), and every tool error carries it as a last line, so a refused write says why. The agent cannot close the view; the user does (Back to the live graph).

Resources (read with resources/read): graphersal://schema (the stored schema), graphersal://statistics, graphersal://dsl-reference (every step and function of the language with its signatures, both spellings, a one-line description and a runnable example with its result, generated from the engine's function docs, about 55 KB), graphersal://examples (the playground's examples, about 8 KB) and graphersal://saved-queries (the list of list_saved_queries).

Saved queries first. The server's instructions and the query tool's description tell the agent to look for a saved query (list_saved_queries) before it writes a new query, and to run it with run_saved_query: the queries a user stored for recurring questions are reused instead of rewritten. Both tools are offered with --mcp-read-only too (a saved query is read-only by definition). With --mcp-query-tools, tools/list also lists every saved query as a tool named like the query, with its description (and folder) and an inputSchema built from its parameter schemas (defaults included, required parameters in required, no other properties); calling it is run_saved_query with those arguments. tools/list reflects the catalog at the time of the call; the endpoint has no event stream, so it announces tools.listChanged: false and a client lists the tools again to see a changed catalog. A saved query named like a built-in tool (statistics, ...) is not listed as a tool of its own; run_saved_query reaches it.

The agent's queries share everything with the browser: one query runs at a time, Stop in the browser also cancels a running agent query (it rolls back), a read-only view opened by either side is what both see, and the limits apply.

Live refresh in the browser

Every page polls GET /api/changes every 2 seconds while it is visible (it pauses in a hidden tab and checks at once when it becomes visible again). When the graph changed because of something this page did not do (an agent over MCP, or another browser tab on the same server), the page reloads the graph info, the Graph, Schema and Statistics panels and the Store menu, marks every tab's result as possibly stale and shows "changed: commit N". Its own queries do not trigger the notice.

Protocol details

The endpoint implements MCP's Streamable HTTP transport of the protocol revisions 2025-11-25, 2025-06-18 and 2025-03-26 (the initialize-based ones; initialize negotiates one of them) with JSON answers and no server-sent event stream: POST /mcp with one JSON-RPC message (initialize, ping, tools/list, tools/call, resources/list, resources/read; a notification is answered 202 Accepted), GET /mcp is 405, DELETE /mcp ends the session. initialize returns an Mcp-Session-Id; a request that names an unknown session (after a restart of the server) is 404, so the client initializes again. A request whose MCP-Protocol-Version header names another revision is 400, which tells a client that also speaks newer, stateless revisions to fall back to initialize. The Host/Origin checks of the Safety section apply (another site's Origin is 403), and the server still binds the loopback only: --mcp-token protects against other local users and programs, not against the network.

AI Chat

EXPERIMENTAL, like the dev server. The configuration file, the endpoints and the tab change without notice.

With --ai FILE the playground's Query panel can open an AI Chat tab: you ask questions in plain language and an LLM agent answers them by working on the served graph. The agent uses the same tools as an MCP client (query, the schema tools, saved queries, compression rules, statistics, graph_info), but the agent loop runs inside the dev server process: the server calls the LLM provider, runs the tool calls the model asks for on the session (they queue like every browser and MCP call), sends the results back and repeats until the model answers. The browser only shows the conversation; the API key never reaches the page. --ai does not need --mcp (both may be on).

export ANTHROPIC_API_KEY=...                           # the key stays in the server process
graphersal --graph modern --server --ai ai.json
# Graphersal dev server: http://127.0.0.1:8080/                              (stdout)
# AI Chat (EXPERIMENTAL): model ... over the Anthropic API; data the agent queries is sent to api.anthropic.com   (stderr)

Open the page, click + in the Query panel's tab strip and choose AI Chat (the tab has its own colour). Ask, for example, "Who does marko know?" or "Which software was created by more than one person?". The transcript shows:

• your messages and the agent's answers (Markdown: tables, lists, code);
• per question, the steps that led to the answer in ONE collapsed group above it (e.g. "Worked: 2 tool calls (list_saved_queries, query)", "Working: running query" while the turn runs, "Stopped after 1 tool call: list_saved_queries" when it failed); opened, it lists the agent's interim texts and every tool call in order, each collapsible with its arguments, a result summary and the result text; a query call has Open in a query tab and Run;
• a query the agent proposes in its answer (a fenced block) with Copy and Run (Run opens a new query tab and runs it there);
• errors with their help text (a refused key, an unknown model, the provider's rate limit, ...).

Stop ends the agent's turn: the pending provider call is abandoned (the client is synchronous, so the answer is dropped when it arrives) and the query the agent runs is cancelled and rolled back. It stops only this chat; another chat tab, the browser's own query and an MCP client keep running (and the browser's query Stop does not stop the agent's query). /clear (the whole message) starts over: it stops a running turn and deletes the conversation on the server; /help lists the commands. Each chat tab is its own conversation, and a conversation belongs to the page that created it: after a reload the transcript stays as history and the next message starts a new conversation. Conversations live in the server's memory only (at most 64; a restart ends them).

When the agent changes the graph, the page reloads it like after an MCP change: the change feed names the client ai (with the conversation id), and the other tabs' results are marked "possibly stale".

In the WebAssembly playground (no server), an AI Chat tab can be opened but is read-only: it says "AI Chat is available when you run Graphersal locally: graphersal --server --ai ai.json".

The configuration file

--ai FILE names a JSON object. It is read once, at the start of the server, and read strictly: an unknown key, a value of the wrong type or a missing environment variable stops the start with a message that names the key.

A key is required, except for an openai provider with a custom base_url (a local server such as Ollama needs none). The key is never logged, never written to a file by the server and never sent to the page (GET /api/info shows provider, model, read-only and the host data is sent to, never the key). A key sent over plain http:// to a host that is not this machine gets a startup warning.

Examples (the repository holds them as crates/graphersal-cli/examples/ai-*.json; the model ids are examples, use a current model of your provider):

Anthropic:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-5",
  "base_url": null,
  "api_key_env": "ANTHROPIC_API_KEY",
  "read_only": false,
  "max_tool_calls_per_turn": 20,
  "max_tokens": 4096
}

OpenAI (and, with another base_url and key variable, OpenRouter, Groq, Azure, ...):

{
  "provider": "openai",
  "model": "gpt-4.1-mini",
  "api_key_env": "OPENAI_API_KEY"
}

Google Gemini, through Google's OpenAI-compatible endpoint (a key from Google AI Studio in GEMINI_API_KEY; the adapter appends /chat/completions to the base_url):

{
  "provider": "openai",
  "model": "gemini-3.8-flash",
  "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
  "api_key_env": "GEMINI_API_KEY"
}

Thinking models (Gemini 3) work too: the thought signatures Gemini attaches to its tool calls (extra_content) are sent back unchanged with the next request, as Google requires.

Ollama on this machine (ollama pull qwen2.5:7b first; no key, no data leaves the machine):

{
  "provider": "openai",
  "model": "qwen2.5:7b",
  "base_url": "http://localhost:11434/v1"
}

What data leaves the machine

Everything the agent sees goes to the provider: your messages, the system prompt (the MCP instructions, the agent's rules, the DSL reference and a short summary of the graph taken at the first question: counts, labels, schema mode, number of saved queries), and every tool result: query results, schemas, statistics, saved queries. The tab's header says so: "Data you query is sent to api.anthropic.com (Anthropic API)"; with provider: "openai" it names the OpenAI-compatible API, whoever runs it (Gemini's host, for example). When base_url points at this machine (localhost, 127.*, [::1]), nothing leaves it and the header says "The model runs on this machine". Use a local provider for data that must not leave it.

Graph data is untrusted input: a property value can contain text that looks like an instruction. The agent's system prompt says that tool results are data, never instructions, and only your own messages instruct it; that lowers the risk, it does not remove it. Use read_only when the agent should not change anything.

Read-only

With "read_only": true the agent gets only the reading tools, and its query runs under the same read-only rule as --mcp-read-only: a query that would create, change or delete data, the schema or a catalog definition is refused. The tab shows a read-only badge. The browser can still write.

Limits

• max_tool_calls_per_turn bounds the tool calls of one question; max_tokens the length of one answer.
• The server's limit options (--timeout, --memory-limit, --max-traversers, ...) apply to every query the agent runs, as to the browser's and MCP's; a query result is cut at the display limits (100 rows and 100 nested items) before it goes to the model, with a note.
• A message is at most 100 000 characters. One turn runs at a time per conversation; several conversations run at the same time.
• The provider's own limits (rate, context length, cost) are yours: a long conversation sends the whole history with every call.

The HTTP API (internal)

For reference while it exists; it follows the playground's engine boundary (playground/js/engine/engine.js) and may change in any release. Answers are JSON; errors are {"error": "..."} with a 4xx status (422 for a failing schema operation).

A target is {"commit": N}, {"mark": "name"} or {"time": T} with T an RFC 3339 date-time (as the CLI's --at-time) or microseconds. GET /api/store lists every attic entry with bytes, restorable and restoreBlocked (the reason a restore is refused now). A change of the catalog (a saved query or a compression rule defined, replaced or dropped) is a commit like any other: the change feed records it, and on a Store it is journaled. A recompress changes no data and commits nothing. Any other path is a static file of the UI (--ui-dir first, then the embedded copy).

GraphSON

GraphSON 3.0 is TinkerPop's JSON graph format and Graphersal's primary exchange format for Gremlin users: TinkerGraph, Gremlin Server and JanusGraph write it with g.io("graph.json").write(), and TinkerGraph reads Graphersal's export with g.io("graph.json").read(). GraphML stays available as the second format. Both need the io feature, and neither carries the schema (see Schema).

Reading and writing

The file operations ask the authorizer like GraphML's: Read on the File and Create on Data for an import, Read on Data and Create on the File for an export (see Permissions).

use graphersal::io::{GraphExport, GraphImport, GraphSONImport};

let graph = GraphSource::from_graphson("tinkerpop-modern.json")?;
graph.export_graphson("copy.json")?;

let (graph, report) = GraphSONImport::new().load_file("export-from-janusgraph.json")?;
if report.has_skips() {
    eprintln!("{report}");
}

Accepted input

• Line form: one vertex object per line, TinkerPop's default and the only form io() reads. Blank lines, a UTF-8 byte order mark and \r\n line ends are accepted.
• Wrapped form: one document {"vertices": [...]} (TinkerPop's wrapAdjacencyList), compact or pretty-printed. Other top-level keys are ignored and reported.
• Versions: GraphSON 3.0 typed (the default), 3.0 types=false, 2.0 typed and untyped 1.0 and 2.0 are read by one decoder: an {"@type": .., "@value": ..} object is a typed value, anything else is plain JSON. Typed GraphSON 1.0 (@class) and the TinkerPop 2 (Blueprints) format are rejected with IOError::UnsupportedGraphSON.
• A vertex object is read from id, label, properties, outE and inE. Other keys (Cosmos DB's type, _partition) are ignored and reported. A vertex-property entry needs only value (its id is not kept); an edge entry needs inV/outV.

Type mapping

Nothing is guessed: a string stays a string whatever it looks like, and a value whose type Graphersal cannot hold is skipped, never converted to a string or a number. Dates in particular are skipped until Graphersal has a date type, so that adding it later changes no existing import. A skipped value inside a container skips the whole property value. A value nested deeper than 128 levels, a g:Map with an odd number of items or a non-string key, and a payload that does not fit its type ({"@type": "g:Int32", "@value": "7"}) are skipped as malformed.

A number outside int64/float64 (a plain integer above i64::MAX, 1e999) makes its line fail to parse; the import stops with IOError::GraphSONParse.

Structure mapping

Export does the reverse: every vertex is one line with id, label, inE, outE and properties; ids are JSON strings; a label set is joined with "::"; vertex-property ids are a file-wide g:Int64 sequence. _meta is written back as meta-properties when it has exactly the shape an import produces (an object per key, or an array aligned with an array value of two or more items: then the array becomes that many entries); any other _meta is written as an ordinary property, so a round trip never loses it.

A graph exported by Graphersal and imported again is the same graph: ids, label sets, every property with its exact logical type (int64, float64 including NaN and infinities, uuid, nested array/object), edge ids, labels and properties. Only the iteration order of edges may differ, because GraphSON groups them by vertex and label. Two Graphersal elements have no TinkerPop counterpart and come back changed: a vertex without labels is written with TinkerPop's default label vertex, an edge without a label with edge, and both are read back with that label.

The import report

ImportReport (graphersal::io) holds the counts of imported vertices and edges and one ImportNote per kind of event, with a count and up to five sample locations (line 3: vertex "1", property "born"; vertices[2]: ... in the wrapped form). ImportNoteKind says what happened; its Skipped* kinds lost data (is_skip()), the others only changed the representation:

Its Display is the text the CLI, Rhai and Python show: a first line with the counts and one line per note.

Limits and errors

One line (line form) or the whole document (wrapped form) is read only up to GraphSONImport::max_text_bytes (512 MiB natively, 64 MiB on wasm32); a longer one fails with IOError::InputTooLarge before it is held in memory (GraphSONImport::new().with_max_text_bytes(n) changes it). Use the line form for large graphs: it is read line by line, and only the edges are buffered until every vertex is known. JSON nesting is bounded, so no input can exhaust the stack.

Fatal errors stop the import, and on a live graph roll it back as a whole: invalid JSON or a line that is not an object (IOError::GraphSONParse with the line), an unsupported variant (IOError::UnsupportedGraphSON), an oversized line, and every graph error, such as a schema violation or a vertex id that already exists in the target graph (IOError::Graph).

Schema

GraphSON carries no schema. Typed values keep their own types, so a GraphSON file needs no schema to come back exactly. When the target graph stores a schema, the import goes through it like any other write: open/closed coerce declared fields (an untyped canonical UUID string becomes a declared string with format: uuid) and reject what violates it, which fails the import. Save the schema separately (g.get_schema(), its JSON in the schema format) and set it on the target with g.set_schema(..) before importing. The front ends do both steps in that order for you: graphersal --graph graph.json --schema schema.json [--schema-mode closed], Python Graph.from_graphson(path, schema=.., mode=..) and the playground's Load from file with its optional schema file.

Loading an export into TinkerGraph

Element ids are strings in Graphersal, the same model as Amazon Neptune and Azure Cosmos DB, and the export writes them as JSON strings ("id":"1"). A TinkerGraph opened with its default id manager keeps them as Strings, so it answers g.V("1"), and g.V(1) finds nothing. When the ids are numeric, open the TinkerGraph with the LONG id managers: they convert every id they read (and every id a query passes, 1, 1L or "1") to a Long, so g.V(1) works as on TinkerPop's own sample graphs:

import org.apache.commons.configuration2.BaseConfiguration
import org.apache.tinkerpop.gremlin.tinkergraph.structure.TinkerGraph

conf = new BaseConfiguration()
conf.setProperty("gremlin.tinkergraph.vertexIdManager", "LONG")
conf.setProperty("gremlin.tinkergraph.edgeIdManager", "LONG")
// keeps every value of an array that came from a multi-property (see below)
conf.setProperty("gremlin.tinkergraph.defaultVertexPropertyCardinality", "list")
graph = TinkerGraph.open(conf)
g = graph.traversal()
g.io("modern.json").read().iterate()
g.V(1).out("knows").values("name")   // ==> vadas, josh

The same keys go into a Gremlin Server's TinkerGraph .properties file (gremlin.tinkergraph.vertexIdManager=LONG, ...). The LONG managers need ids that parse as numbers: a graph with ids such as "V_0_0" fails to load with them (Expected an id that is convertible to class java.lang.Long); load it with the default managers and query it by its string ids.

Verified with TinkerGraph 3.8.2 (Gremlin Console, g.io(file).read()) on the exports of modern, large (111 110 vertices, 111 100 edges) and a graph with every value type:

TinkerGraph's default vertex-property cardinality is single: an array exported as several entries with meta-properties (a former multi-property, _meta aligned with it) keeps only its last entry unless the graph is opened with defaultVertexPropertyCardinality list. With list, the file TinkerGraph writes back (g.io(file).write()) imports into Graphersal as the same graph: values with their types, the array, _meta, and the label set from "A::B".

Deviations from TinkerPop

Listed in TinkerPop Deviations as well:

• Ids are strings. Imported numeric ids become strings, and export writes string ids, so a TinkerGraph that loads the export answers g.V("1"), not g.V(1), unless it is opened with the LONG id managers (recipe).
• Multi- and meta-properties are folded into an array and the _meta property, because Graphersal stores one value per key; export restores them only from _meta, otherwise an array is one vertex property holding a g:List.
• Multi-labels are written as "A::B", which TinkerGraph treats as one opaque label (Neptune's convention, see Multi-Label Vertices).
• Unlabeled elements are written with the default labels vertex/edge and read back with them.
• Skipped values: dates and the other types listed above are skipped and reported where TinkerPop reads them.
• Lenient structure: an edge to a missing vertex is skipped (TinkerPop's readGraph fails), a duplicate vertex id keeps the first vertex, and vertex-property ids are not kept.
• Widening: g:Int32 and g:Float come back as g:Int64 and g:Double on export.

Generating Test Data

Fake(seed) is a generator of test data for scripts: English names, e-mail addresses, job titles, addresses, companies and words, plus the random numbers a script needs to build a graph's shape (how many reports a manager has, who knows whom). It is part of the Rhai DSL (feature script), so it works in the CLI, the playground, the dev server and Python alike.

let f = Fake(42);
f.full_name()             // "Lawrence Young"
f.int(1, 6)               // 2: a die roll
f.email("Ada Lovelace")   // "ada.lovelace35@example.com"

Reproducible by design

The same seed and the same sequence of calls give the same values, on every platform (native and WebAssembly) and in every run. A graph generated from a seed can be rebuilt exactly, to reproduce a bug, to compare two versions of a query, or to benchmark on the same data.

• Fake() without a seed picks a random one; f.seed() tells which, so a run you liked can be repeated with Fake(that_seed).
• The generator is Graphersal's own (SplitMix64), not the rand crate's, whose algorithms may change between versions. The word lists and the way each method draws are part of the contract as well: a change to them changes what every seed produces, so it is treated as a breaking change (a test pins the values of seed 42).
• random.seed (g.with("random.seed", n)) seeds the random steps of one traversal (coin(), sample(), order().by(Order.shuffle)); Fake is independent of it.

Copies share one stream

A Fake value is a handle. A copy (let b = a;, a function argument) draws from the same stream, so a helper function advances the caller's generator and every call gets new values:

fn person(f) { #{ name: f.full_name(), age: f.int(18, 90) } }
let f = Fake(1);
[person(f), person(f)]   // two different people

Forks: independent streams

f.fork(name) returns a generator for the stream name of the same seed. A fork depends only on the seed and its name (and the names of the forks above it), never on what was drawn before. Give each part of a generator its own fork, and drawing one more value in one part does not shift the values of all the others:

let f = Fake(42);
let people = f.fork("people");
let social = f.fork("social");   // unchanged when the people part draws more values

Methods

Methods of two words have both spellings (full_name/fullName, zip_code/zipCode, ...). A wrong argument (int(5, 1), chance(1.5), pick([]), sample([1], 2)) is a script error that names the method.

Only English data exists for now. Dates come with the date type in a later release.

Building a graph

The playground's Examples menu has a complete generator under Generated test data (Fake): its parameters (seed, number of companies, depth and fan-out of the management trees, number of knows edges, number of cities) are Rhai variables at the top of the script. Its core:

let f = Fake(42);
let people = f.fork("people");
let ids = [];
for i in 0..100 {
    let name = people.full_name();
    ids.push(g.add_v("person").property("name", name)
        .property("email", people.email(name)).property("age", people.int(21, 67))
        .id().next());
}
let social = f.fork("social");
for k in 0..300 {
    let a = ids[social.int(0, ids.len() - 1)];
    let b = ids[social.int(0, ids.len() - 1)];
    if a != b { g.v(a).add_e("knows").to(g.v(b)).to_list(); }
}

Pick from a large array by index, as above: pick(), shuffle() and sample() receive a copy of the array they are given, which costs one copy per call. The example's largest setting (3 companies, depth 6, fan-out 4: 16 383 people, 50 000 knows edges) takes about a second in a native release build.

Running Queries Safely

By default the library trusts its caller: the Rust API and the plain script::eval* helpers allow everything and run without limits beyond the safe script defaults. A host that runs queries it did not write (a web service, a plugin system, an AI agent) restricts them on three levels:

• Permissions decide what a query may do: read or write data, change the schema, read files, set administrative options. A ready-made AccessPolicy (for example read_only()) or your own Authorizer checks the plan once, before it runs.
• Limits decide how much it may use: script operations, traversers, materialized bytes, string sizes, nesting depth, a memory budget.
• Time bounds how long it may run: evaluationTimeout, loop limits, and a cancel token that stops a running query from another thread.

A host sets the defaults and can lock them, so a query cannot raise its own limits with g.with(...). Every refused or stopped query is rolled back.

Permissions

Graphersal is an in-process, in-memory library: the program that holds the graph usually also writes the queries. Everything is therefore allowed by default, in the Rust API and in the Rhai script entry alike. A host that runs input it does not trust (a web form, a multi-tenant query service, a pasted snippet, an LLM) plugs in an authorizer: a graphersal::auth::Authorizer that is asked for every request a query makes, before the query runs.

Resource use is a separate concern, bounded by Resource Limits and Query Limits.

Requests: an action on a resource

Every step and every file or schema operation of a query makes one or more AccessRequests, an Action on a Resource:

What each step requests is decided in one place in the engine (GraphStep::for_each_access):

Only steps that reach graph data ask for a read: the sources (V(), E(), also in the middle of a traversal) and the adjacency steps. A value-only step works on what earlier steps produced, so it asks nothing: g.V().has("age", P.gt(30)).values("name").limit(2) asks exactly once, for Read on Data(vertex), and g.inject(1, 2).sum() runs under AccessPolicy::deny_all(). No live element handle survives a run: let v = g.V().next() is the vertex materialized as a map and inject() takes values, so g.inject(v) reads that copy and asks nothing.

Labels of reads are not reported: a request reports what the plan states, and a plan cannot say statically which labels a read reaches. Element- and label-level read security is a later storage decorator (Later). A policy that restricts one element kind or label must treat None as "possibly that one".

The ready-made policy: AccessPolicy

AccessPolicy allows or denies by action kind and resource kind, plus an optional file root. It covers what the shipped front ends need without a trait implementation of their own:

#![allow(unused)]
fn main() {
use graphersal::prelude::*;
use graphersal::auth::{AccessPolicy, ActionKind, ResourceKind};
use graphersal::catalog::Definition;

let query_service = AccessPolicy::read_only();             // Read on Data, Schema, Definition;
                                                           // Execute on Definition (saved queries)
let editor = AccessPolicy::read_only()
    .allow(ActionKind::Create, ResourceKind::Data)
    .allow(ActionKind::Update, ResourceKind::Data)
    .allow(ActionKind::Delete, ResourceKind::Data);
let server = AccessPolicy::allow_all().deny_resource(ResourceKind::File);
let nothing = AccessPolicy::deny_all();                    // a script can only compute
let _ = (query_service, editor, server, nothing);
}

Restricting a script

graphersal::script::engine(), graph_scope(g) and the eval_* functions without limits allow everything. The entries that take explicit limits take the authorizer too:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use graphersal::prelude::*;
use graphersal::auth::{AccessPolicy, Authorizer};
use graphersal::script::ScriptLimits;

let graph = Arc::new(GraphSource::tinkerpop_modern());
let read_only: Arc<dyn Authorizer> = Arc::new(AccessPolicy::read_only());
let names = graphersal::script::eval_value_with_limits(
    graph.clone(),
    r#"g.V().hasLabel("person").values("name").toList()"#,
    Default::default(),
    &ScriptLimits::default(),
    read_only.clone(),
);
assert!(names.is_ok());
let denied = graphersal::script::eval_value_with_limits(
    graph,
    r#"g.addV("x").next()"#,
    Default::default(),
    &ScriptLimits::default(),
    read_only,
);
assert!(denied
    .unwrap_err()
    .to_string()
    .contains(r#"Permission denied for 'add_v' (Create Data(vertex "x"))"#));
}

A host that drives its own engine passes the same authorizer to both halves of the entry: the engine (Rhai's import, and the graphs a script creates with GraphSource::empty() and friends) and the scope (the session's g):

#![allow(unused)]
fn main() {
use std::sync::Arc;
use graphersal::prelude::*;
use graphersal::auth::{AccessPolicy, Authorizer};
use graphersal::script::{engine_with_limits, graph_scope_with_options, ScriptLimits};

let graph = Arc::new(GraphSource::tinkerpop_modern());
let authorizer: Arc<dyn Authorizer> = Arc::new(AccessPolicy::read_only());
let engine = engine_with_limits(&ScriptLimits::default(), authorizer.clone());
let mut scope = graph_scope_with_options(graph, &[], authorizer);
}

A Rust-built traversal is checked the same way with GraphTraversalSource::with_authorizer(authorizer).

The front ends this project ships:

Writing an authorizer: roles from a token

The subject (who asks) is not part of the request. It lives inside the authorizer instance, so a server builds one authorizer per connection or session, for example from the roles in a JWT it has already verified, and maps them to actions and resources. Roles are not a library concept:

#![allow(unused)]
fn main() {
use std::sync::Arc;
use graphersal::prelude::*;
use graphersal::auth::{AccessRequest, Action, Authorizer, Denied, Resource};

/// Built per connection from the verified token's claims.
struct Session {
    roles: Vec<String>,
}

impl Session {
    fn has(&self, role: &str) -> bool {
        self.roles.iter().any(|r| r == role)
    }
}

impl Authorizer for Session {
    fn authorize(&self, request: &AccessRequest<'_>) -> Result<(), Denied> {
        let allowed = match (request.action, request.resource) {
            (_, _) if self.has("admin") => true,
            // Everybody reads data and the schema.
            (Action::Read, Resource::Data { .. } | Resource::Schema) => true,
            // Editors change data, except elements labelled `salary`.
            (Action::Create | Action::Update | Action::Delete, Resource::Data { label, .. }) => {
                self.has("editor") && label != Some("salary")
            }
            // Server-owned resources go through the same policy.
            (Action::Custom("open"), Resource::Custom { kind: "database", name }) => {
                name == Some("shared") || self.has("dba")
            }
            _ => false,
        };
        if allowed {
            Ok(())
        } else {
            Err(Denied::new(format!("{request} needs another role")))
        }
    }
}

let session = Arc::new(Session { roles: vec!["editor".into()] });
// The server checks its own resources at its own boundary ...
let open = AccessRequest::new(
    Action::Custom("open"),
    Resource::Custom { kind: "database", name: Some("shared") },
);
assert!(session.authorize(&open).is_ok());
// ... and hands the same authorizer to the script entry.
let graph = Arc::new(GraphSource::tinkerpop_modern());
let denied = graphersal::script::eval_value_with_limits(
    graph,
    r#"g.addV("salary").property("amount", 1).next()"#,
    Default::default(),
    &graphersal::script::ScriptLimits::default(),
    session,
);
assert!(denied.unwrap_err().to_string().contains("needs another role"));
}

Resource::Custom and Action::Custom are never produced by the library: they exist so that an embedding server can put its own resources (databases, tenants, endpoints) under the same policy and call authorize itself.

The check

The check runs once per execution, before anything runs, on the plan as written: before the optimizer, so no rule can hide a step by fusing it (add_property_fold folds property() into addV, count_pushdown folds count() into V(); the check still sees each of them). It recurses into every child traversal (union, where, by, repeat, sideEffect, ...), and it costs one pass over the steps. Each distinct request is asked once per execution: g.V().out().in() asks Read on Data(vertex) and on Data(edge), once each. There are no per-element checks. A denial is TraverserError::PermissionDenied { step, request, reason } naming the first step (in plan order) whose request was denied, the request (AccessRequestBuf, as_request() gives the action and the resource) and the authorizer's reason; nothing of the traversal has run. A denied step is located like a failing one: the error is the TraverserError::StepFailed chain of that step (at #1: v().add_v("x"), step_location(); step ids are positions of the plan as written) and the denial is its root_cause(). A denied with("key") option or a source method (file, schema) has no step and stays the bare denial. execute() returns the denial in its error instead of throwing.

"Once per execution" means once per traversal that runs. A script, and a saved query's body, may run several traversals: each one is checked when it runs, so a denial in a later one comes after the earlier ones have run (in the playground the whole script is one unit and is rolled back; a saved query only reads). A saved query is checked in two layers. g.query("name", ..) asks Execute on the query before its body runs. The body's traversals then go through the same check with the host's authorizer plus the saved query's read-only restriction: a step the host denies is denied inside the body too (the error carries a line in saved query: "name"), and every write is denied whatever the host allows. A traversal the query returns keeps that restriction, so g.query("name").drop() is denied as well. Nothing in a saved query can do more than its caller may.

Functions are never hidden: a denied step is still registered, listed by help() and completed by the playground. Only running it is denied.

Administrative g.with() options

A query may set the semantic options freely; setting an administrative one is an Update on Option(key):

An option the host preset (graph_scope_with_options(graph, &[("evaluationTimeout", ..)], ..), or set on a Rust source before with_authorizer) is not the query's setting and asks nothing; a query that sets such a key to another value does. The presets apply to every source of the session: g, _g and __, and, when the engine is built with engine_with_options(&limits, authorizer, &options) and the same options, the sources a script creates itself (GraphSource::empty(), ...), so a script cannot escape a preset by starting a traversal elsewhere.

ExecutionPolicy is the complementary control on the storage: it fixes the value of an option (locked keys, defaults) for every entry, Rust included. Both apply; the authorization check runs first.

File access and the file root

An authorizer decides each file request; Authorizer::resolve_file(path) then maps the path to the file actually accessed (the default returns it unchanged). AccessPolicy::with_file_root(dir) confines every file access to dir:

• a relative path is resolved under dir (g.export_graphml("out.graphml") writes dir/out.graphml);
• a path that leaves dir is denied: .. past the root, an absolute path elsewhere, a symbolic link inside the root that points out of it;
• Rhai's import "helpers" loads dir/helpers.rhai the same way;
• the root must exist; on wasm32 (no file system) every rooted access is denied, never a panic.

The root does not allow file access by itself: the policy must also allow the action on ResourceKind::File. A host that reads files on behalf of a script calls policy.resolve_file(path) itself.

Graphs the script builds itself

A graph the script built itself is private to it: GraphSource::empty(), GraphSource::tinkerpop_modern(), GraphSource::file(path), schema.toGraph(), the scratch sources __ and _g, and the results of subgraph()/cap() and toGraph(). Changing it is not a change of the host graph, so a request that writes data or the schema of it (Create/Update/Delete on Data, Schema or Definition, AccessRequest::writes_graph) is allowed without asking the authorizer:

let sg = g.E().hasLabel("knows").subgraph("sg").cap("sg").next();
sg.addV("note").property("text", "mine").next();   // allowed with AccessPolicy::read_only()

Reading a private graph still asks for Read, and its file and option requests are asked as usual. Naming the host graph as the explicit target of a subgraph (GraphSource::tinkerpop_modern().withSideEffect("sg", g).E().subgraph("sg")) writes into the host graph: it asks for Create on Data (operation with_side_effect) and gets no relaxation. Such a target must be a TraversalGraph: a host graph of another storage is refused with GraphError::Unsupported (Set Side Effects).

A whole script as one unit

eval_value_atomic(graph, script, params, &limits, authorizer) (Transactions) checks every traversal the same way. While it runs, the script works on a private copy of the graph's lock, so it must not return a closure or function pointer (also inside an array or a map): a closure that captured g would point at an empty graph once the script ends. Such a script fails with ScriptError::ReturnedClosure and everything it changed is rolled back; return data or a traversal instead.

Later

Element- and label-level read security (a Filtered<S, Policy> storage decorator) and a ReadOnly<S> decorator are additive follow-ups; a future GQL/Cypher text front end uses the same authorizer.

Resource Limits

A script is untrusted input as soon as a front end faces a user. loop {}, a string that doubles forever, a huge array or unbounded recursion would hang or exhaust the process. Graphersal bounds all of them with two kinds of limit, both reported as one error, TraverserError::ResourceLimitExceeded { limit, max, observed }:

A 0 for any of the four script counters means unlimited; the call depth and the value depth are never unlimited because they protect the native stack of the thread (0 reads as the default for them, and ScriptLimits::unlimited() keeps both defaults).

A graph with a journal (a Store, or a journal attached by hand) has one more, fixed limit that is not an option: the size of one commit, 1 GiB of uncompressed journal record per unit.

Script limits

graphersal::script::engine() and the eval_* functions use the SAFE defaults above. To change them, build the engine yourself (it also takes the script's authorizer):

#![allow(unused)]
fn main() {
use std::sync::Arc;
use graphersal::auth::{AccessPolicy, AllowAll};
use graphersal::script::{engine_with_limits, ScriptLimits};

let limits = ScriptLimits::default().with_max_operations(50_000_000);
let engine = engine_with_limits(&limits, Arc::new(AccessPolicy::read_only()));
// or, for a trusted local front end only:
let engine = engine_with_limits(&ScriptLimits::unlimited(), Arc::new(AllowAll));
}

eval_value_with_limits(graph, script, params, &limits, authorizer) does the same for a one-shot evaluation. Raising a traversal limit with the query's own g.with(..) is an Update on Resource::Option (Permissions). A host that drives its own engine turns a Rhai limit error into the structured error with resource_limit_from_rhai(&err, &limits); the eval_* functions do this themselves and return the formatted diagnostic.

The defaults were sized so every example of this book, every doctest and the TinkerPop scenarios run unchanged. The array and map caps are deliberately modest: Rhai re-measures an array on each method call that touches it, so a loop pushing items is quadratic and a large cap is also a CPU budget (measured: a loop filling a one-million-item cap ran about half an hour in a debug build). Assigning to a map by index (m[k] = v) is not size-checked by Rhai at all; only the operation limit bounds it.

Traversal limits

traversal.max_traversers is an ordinary g.with() option, checked once per step boundary (a counter comparison, no per-item work). A single step can overshoot the cap by one expansion, since the check runs when the step has produced its output.

g.with("traversal.max_traversers", 50000000).v().out().out().count()

A host sets a default and locks it with an ExecutionPolicy, exactly like evaluationTimeout:

let policy = ExecutionPolicy::permissive()
    .with_default("traversal.max_traversers", 1_000_000)
    .with_locked("traversal.max_traversers");

Every traversal limit is an administrative option: a script's own g.with(..) of it asks the host's authorizer for Update on Option(key), while a host's preset (graph_scope_with_options) or policy default asks nothing. The presets of graph_scope_with_options reach every traversal source of the session: g, _g and __ (also a traversal started from __, such as __.inject(1).repeat(..)). Build the engine with engine_with_options(&limits, authorizer, &options) and the same options, so the sources a script creates itself (GraphSource::empty(), GraphSource::tinkerpop_modern(), schema.toGraph(), ...) get them too; otherwise a script could escape a preset evaluationTimeout by building its own source.

Memory: materialized bytes and expansions

Equal traversers are merged into one record with a multiplicity (bulk), so a query like g.v().repeat(__.both()).times(17) stays cheap while it only counts. A step that needs every value as its own item (fold(), aggregate(), store(), group() value lists, a terminal list) expands the bulk, and that is where memory is spent. Two limits bound it, both checked before anything is allocated:

• traversal.max_materialized_bytes (default 1 GiB natively, 256 MiB on wasm32): the estimated size of one expansion, size_of::<Traverser>() plus the value's own heap estimate per copy (the estimator of the Mem column of .profile_with(ProfileType::Memory) without alloc-tracking). The same budget bounds a value a repeat() loop builds up again on every iteration, checked once per traverser per iteration together with the depth: the value, its sack, and the values the execution's path records keep (repeat(__.path()) doubles its value on every iteration and keeps each earlier one in the path records). Such a loop stops at most one doubling past the budget. The size is an estimate, not a measurement.
• bulk.max_expansion (default 10 000 000 values): the number of values one expansion may produce, a second line behind the byte budget (BulkExpansionLimit).

g.with("traversal.max_materialized_bytes", 2147483648).v().repeat(__.both()).times(8).fold()

Prefer a step that works on the multiplicity directly (count(), groupCount(), dedup(), limit(n)) over raising either limit.

Memory budget

The limits above bound one value or buffer. memory.limit bounds the whole: the memory in use while a traversal runs. It exists so that a query which would exhaust the memory of the process fails with ResourceLimitExceeded (and is rolled back, like every failing traversal) instead of the operating system killing the process (a Kubernetes or cgroup OOM kill).

There is no budget by default. A host opts in, either with an explicit number of bytes or with "auto":

• bytes: g.with("memory.limit", 4294967296), or better a host setting (below).
• "auto": the cgroup memory limit of the process minus a headroom. Graphersal reads /sys/fs/cgroup/memory.max (cgroup v2) or, failing that, /sys/fs/cgroup/memory/memory.limit_in_bytes (cgroup v1), once per process. max, the v1 "unlimited" value or no file at all means no limit, so "auto" is no budget outside a memory-limited container, and always on wasm32. memory.headroom (bytes) is what stays free below the cgroup limit for the stack, the code, allocator overhead and whatever the engine does not count; the default is a tenth of the limit, at least 64 MiB and at most half of it (a 512 MiB container gets a budget of 448 MiB).

What is compared with the budget:

• with a tracking allocator (the alloc-tracking feature and graphersal::alloc_tracking::TrackingAllocator installed as the binary's global allocator, as the graphersal command line, the playground and the Python binding do; in Python it counts the extension's Rust heap only, not Python objects): the process's exact live heap bytes, plus what a check is about to allocate;
• otherwise the engine's estimate: the graph's footprint (g.memory_usage()), taken once when the traversal starts, plus the traversers alive between two steps, the elements the traversal added (at the graph's average element size) and what a check is about to allocate. Property values written to existing elements are not counted. The footprint is a walk of the graph (time proportional to its size), cached by the graph's commit position: a traversal on a graph that has not changed since the last walk reuses the figure, and only the first traversal after a committed change walks again (a rolled-back traversal changes nothing, so the figure stays; inside an explicit unit with uncommitted changes every traversal walks). For large graphs that change often, prefer the tracking allocator.

The budget is cooperative (an allocator cannot fail softly): it is checked at every step boundary and at the places that check traversal.max_materialized_bytes, before a bulk expansion allocates, before a bucket push of copies and on every repeat() iteration. A single step can overshoot it by what it builds before the next check. Writes are checked the same way: a traversal that grows the graph past the budget fails and leaves nothing behind. When the graph alone is over the budget, every traversal fails at its first step; a trusted host frees memory with a raised budget for one query, for example g.with("memory.limit", 8589934592).v().has_label("tmp").drop().

Units that are not traversals are checked too, against the budget of the graph's ExecutionPolicy default (and, for a script's g.import_graphml(..)/g.import_graphson(..), the session's preset options; a query's own g.with(..) does not reach them):

• a GraphML or GraphSON import into a live graph (import_graphml*, import_graphson*, GraphMLImport::import_reader, GraphSONImport::import_reader) and apply_change_set every 4096 elements (imported vertices and edges, applied mutations) and at their end;
• every outermost unit at its commit: a transaction(|g| ..) closure, an applied change set, an import, a traversal (whose steps already checked their own budget).

Over the budget the whole unit is rolled back and fails with GraphError::ResourceLimitExceeded (wrapped in IOError::Graph for an import), whose message names the operation: Resource limit 'memory.limit' exceeded by the GraphML import (limit N, reached M); the help() gives the same host advice as a traversal's. The measure is the one above: the live heap with a tracking allocator, else the footprint when the unit started plus the elements it added. Only a unit that grew that measure is stopped, so a unit that only removes or rewrites data commits even on a graph that is already over its budget. Without a budget nothing is paid: no walk, no check. Loading a graph nobody sees yet (GraphSource::from_graphml, from_graphson, GraphSONImport::load, a snapshot or store load) is not checked; the next traversal is.

The budget is a host setting, like the other ceilings: an ExecutionPolicy default (locked or not) on the graph, or a session preset of graph_scope_with_options/engine_with_options:

let policy = ExecutionPolicy::permissive()
    .with_default("memory.limit", "auto")
    .with_locked("memory.limit");
let graph = TraversalGraph::new().with_execution_policy(policy);

A query's own g.with("memory.limit", ..) is an administrative option (Update on its Option), refused outright when the host locked the key.

Strings built by steps

script.max_string_size bounds the strings a script builds; traversal.max_string_bytes (default 16 MiB, the SAFE script.max_string_size) bounds the strings the engine builds: replace(), concat(), conjoin(), format(), as_string(), to_upper()/to_lower(), substring(), reverse(), the trims and the elements of split(). The steps that can multiply the length of their input (replace() at every match, concat()/conjoin() of many parts) compute the length first and fail before the string is allocated; the others check their result.

g.with("traversal.max_string_bytes", 67108864).v().values("name").replace("a", "aa")

Time inside a step

evaluationTimeout is checked between steps, every 1024 traversers a step consumes or produces, and every 1024 values a step materializes: the copies of a bulk expansion (fold(), a terminal list, aggregate(), group() value lists), the members group() and tree() collect, the sort keys order() computes (and once after the sort) and every repeat() iteration. The timeout is reported at the step that was running (Step #2 'fold()'), not at the next step boundary.

Value depth

Almost everything that reads a value walks it recursively: the conversion to a script value, hashing in dedup(), schema inference, rendering. A value nested thousands of levels deep would overflow the native stack and abort the whole process, so Graphersal bounds the depth where a value enters the engine; no deeper value can exist afterwards, and every reader stays bounded. A scalar has depth 0 and every array, object, map or path around it adds one level: [1] is 1, [[1]] and {"a": [1]} are 2.

• script.max_value_depth (ScriptLimits::with_max_value_depth, default 128, the recursion limit serde_json applies to JSON input): a value a script hands to the engine (a step argument such as inject(x), property("k", x), has("k", x), a token argument), a host parameter (eval_*_with_params), and the result of a whole-script unit (eval_value_atomic, eval_value_dry_run, materialize_traversals). The conversion stops at the limit; nothing recurses deeper.
• traversal.max_value_depth (a g.with() option, default 128, administrative, lockable with an ExecutionPolicy like every option): what the engine builds itself. A repeat() whose body wraps its value again on every iteration (repeat(__.fold()), repeat(__.path()), repeat(__.group()), a sack folded into itself) is checked once per traverser per iteration; a property write is checked for the depth it leaves behind, so property(jpath("a.b.c"), v) counts two levels for the path plus the depth of v.
• jpath: a path has at most 256 segments (a parse error beyond), so even a direct GraphStorage::set_vertex_property_path call cannot build an unbounded value.
• Imports: GraphML values are scalars (containers cannot be imported), and schema and change-set JSON is parsed by serde_json, whose own recursion limit (128) applies. A GraphSON import skips a property value nested deeper than 128 levels (reported) and bounds the JSON nesting of a line, so no file can exhaust the stack.
• GraphSON input size: one line (line form) or the whole document (wrapped form) is read only up to GraphSONImport::max_text_bytes (512 MiB natively, 64 MiB on wasm32), checked before the text is held in memory (IOError::InputTooLarge, whose help() names with_max_text_bytes(n)).

g.with("traversal.max_value_depth", 256).inject(1).repeat(__.fold()).times(200).count()

Raise the limits only moderately: a few hundred levels are fine on every thread stack, thousands are not. The display of a script value the script never handed to the engine (a deeply nested Rhai array returned as the result) is cut with […] after 128 levels; the data itself is not changed.

Front ends

• graphersal (CLI): a trusted local tool, so no script limits by default. --safe-limits applies the SAFE defaults; --max-operations, --max-string-size, --max-array-size, --max-map-size and --max-traversers set one limit (0 is unlimited; --max-string-size also sets traversal.max_string_bytes, which follows the script's string limit and is unlimited by default). --max-value-depth <n> sets script.max_value_depth and traversal.max_value_depth (0 is the default, 128). --memory-limit <bytes|auto> (and --memory-headroom <bytes>) sets the memory budget of the session, measured on the live heap (the CLI installs the tracking allocator); 0 or no flag is no budget. In the REPL, /set max-operations <n> (and the other script limits, max-value-depth included) and /set safe-limits. The presets reach every source a script creates. The session runs on a thread with a 64 MiB stack.
• Web playground: no script limits, no default timeout and no memory budget, like the CLI (it runs in your own browser); its Stop button restarts the engine to end a runaway query.
• Python: SAFE defaults; graph.set_limits(max_operations=..., max_value_depth=..., unlimited=True, ...). The memory budget is a graph setting: Graph(memory_limit=..., memory_headroom=...) (also on Graph.tinkerpop_modern, Graph.from_graphml and Graph.from_graphson), measured on the live Rust heap of the extension (the binding installs the tracking allocator). Python objects are not counted, so with memory_limit="auto" the memory_headroom must also cover the Python side of the process. Scripts run on a worker thread with a 64 MiB stack (one per calling Python thread).

The large stack is a mitigation for the scripting engine itself: Rhai copies a nested map value recursively (x = #{a: x} in a loop), and a few thousand levels overflowed the 8 MiB stack of a debug build before any Graphersal code ran, which no depth limit of Graphersal can catch. A host that embeds the engine on a thread of its own should give that thread a large stack too (std::thread::Builder::stack_size; not available on wasm32).

wasm32

The script limits are counters Rhai checks itself, so they work on wasm32-unknown-unknown. evaluationTimeout works there too: the engine reads the clock through web_time::Instant (performance.now() in the browser). The operation counter stays the portable, deterministic bound; the playground additionally has a Stop button that restarts the engine.

Mutating traversals

A limit abort in the middle of a mutating traversal rolls back every write the traversal made before the abort: an aborted write traversal is all-or-nothing (see Transactions). A Rhai limit that stops a script (operations, call depth, string or collection size) stops it in the script code around the traversals; the traversals that already finished stay applied (the unit is one traversal, not the script), unless the host runs the script as one unit with eval_value_atomic (Transactions), where a limit abort rolls back the whole script.

The size of one commit (journal)

A journal (the write-ahead log of a Store, or a persist::Journal) writes every committed unit as ONE record, and the body of a record is at most 1 GiB before compression (format spec 9.3). The body holds every change of the unit with its before and after values, so dropping an element writes its full properties too: dropping 300 000 vertices with long texts and creating them again in the same unit writes both. The limit is fixed (it is not an option, and the record is not split over several records).

A larger commit is refused by the journal's commit hook: the whole unit is rolled back, nothing is written, and the journal keeps working. The error is

The commit was rejected by the commit hook 'journal': Commit 2 is too large for the journal:
its uncompressed record body is 1203145990 bytes, more than the limit of 1073741824 bytes per commit

and its help says how to split the work. The limit applies per unit, so the fix is more, smaller units:

• Web playground and dev server: a whole script is one unit. Drop the old data in a run of its own (g.v().drop().iterate()) and create the new data over several runs (a part of the input per run).
• CLI, Python, Rust: each traversal is already its own unit; only a single huge traversal (one drop() of everything, one load of millions of elements) can reach the limit. Split it into batches. In Rust, transaction(..) blocks and whole-script units (script::eval_value_atomic) commit as one, so keep each below the limit.

A graph without a journal (in memory only) has no such limit; the memory budget bounds it instead.

Query Limits

See the Execution Options Reference for the full table of every g.with() key, including how a host embedding this engine can lock evaluationTimeout and repeat.max_loops so a query cannot override them.

Nothing bounds the running time of a traversal by default. A Cartesian fan-out such as v().out().out().out() on a large graph can hold the graph lock and a CPU for as long as it takes. When queries come from users, as in the web playground, set a budget. Only repeat() loops have a default bound, repeat.max_loops.

evaluationTimeout

evaluationTimeout is the TinkerPop per-request option of the same name (Tokens.ARGS_EVAL_TIMEOUT). It sets the wall-clock budget of one traversal execution, in milliseconds:

let count = graph
    .traversal()
    .with("evaluationTimeout", 5000)
    .v(None)
    .out(None)
    .out(None)
    .count()
    .next()?;

In the script DSL:

g.with("evaluationTimeout", 5000).V().out().out().count().next()

• The value is a non-negative integer number of milliseconds. 0 means no timeout, which is also the default when the key is absent.
• The budget covers the whole execution, nested traversals included: a where(), not(), union() or by() child traversal spends the same budget as its parent.
• .profile() executes the traversal, so it honours the budget too. A profile that times out returns the error; no partial profile is produced.
• An invalid value (negative, fractional, or not a number) is reported as InvalidOption when the traversal is executed, because with() itself cannot fail.
• Setting the key again replaces the previous value.

When the budget runs out, the traversal stops with a Timeout error, for example:

Error: Step #3 'out()' execution failed
  at #3: v().out().out().out().count()
                   ^^^^^
  plan:  v().out().lazy_barrier().out().lazy_barrier().out().count()
                                  ^^^^^
Caused by: Traversal exceeded evaluationTimeout of 50 ms (ran 50 ms)
Help: The traversal ran longer than its evaluationTimeout budget of 50 ms. ...

The diagnostic names the step that was running, in the query as written and, when the optimizer changed it, in the executed plan (plan:). Its help rewrites the failing query: narrow the start set with has_label()/has_id(), cap the stream with limit(), or raise the budget.

repeat.max_loops

A repeat() loop on a graph with cycles, such as g.V().repeat(__.both()), never runs out of traversers. Graphersal stops every repeat() that is not bounded by times() after a number of iterations, instead of letting it run until the timeout or forever:

g.with("repeat.max_loops", 100).V("1").repeat(__.out()).until(__.has("name", "ripple"))

• The default is 10 000 iterations. The value must be an integer from 1 to 4 294 967 295; anything else is reported as InvalidOption when the traversal is executed.
• A loop with times(n) is never limited: it already ends after n iterations, so repeat(__.out()).times(50000) runs all of them.
• The limit applies to each repeat() separately, nested loops included.
• When a loop exceeds it, the traversal fails with RepeatLimitExceeded. The help suggests times(), until(), simple_path() in the body, and a raised limit, written on the failing loop.

The limit is deterministic: the same query on the same graph always fails after the same iteration. evaluationTimeout bounds wall-clock time instead, including the time a bounded loop spends. The two complement each other. See Recursive Traversals.

Granularity

The timeout is cooperative. The engine checks the clock:

• between steps,
• every 1024 traversers a step consumes or produces, and
• every 1024 values a step materializes (the copies of a bulk expansion in fold(), a terminal list, aggregate(), group() value lists; the members group() and tree() collect; the sort keys of order(), and once after its sort), so the timeout is reported at the step that spent the time.

A single storage call, such as one full index scan, is not interrupted, so a query can overrun its budget by the time one such call takes; so can one sort, or one step that copies a single large value (a repeat(__.path()) iteration copies the whole growing path once).

Mutating traversals

A mutating step (property(), add_v(), add_e(), drop(), ...) is never interrupted: the budget is checked only at its step boundaries.

A traversal that times out is rolled back as a whole, also the mutations of the steps before the timed-out one: a failing traversal leaves nothing behind (see Transactions).

Script expression depth

A script is rejected with Expression exceeds maximum complexity when its expressions nest deeper than 128 levels (64 inside a script-defined function). Every call of a method chain counts as one level, so a chain of about 120 steps or 30 nested union(..) levels is accepted; a 150-step chain is not.

The limit is the same in debug and release builds. Rhai's own default is 64 in release but only 32 in debug builds, which made the same query run in a release graphersal and fail in cargo test. It is not higher because the parser recurses: on a 2 MiB thread stack (the default of spawned threads) a debug build overflowed the stack at 160/80. Split a very long query into several statements with a variable (let people = g.V().hasLabel("person")).

Script hosts

• graphersal --timeout <ms> sets a default evaluationTimeout for every traversal of the session. Without the flag there is no timeout. A query overrides the default with its own g.with("evaluationTimeout", ms), where 0 disables it.
• The CLI also stops a script whose own Rhai code (a loop {}) runs past the same budget, because such code is not a traversal and would otherwise bypass the timeout.
• The web playground sets no default timeout: it runs in your own browser, and its Stop button ends any query or script loop by restarting the engine (the graph comes back as last loaded or saved).
• An embedder builds the same defaults with graphersal::script::graph_scope_with_options(graph, &[("evaluationTimeout", 5000.into())], authorizer). A preset option is the host's; a script that changes evaluationTimeout itself asks the host's authorizer for Update on Option("evaluationTimeout") (Permissions).

Execution Options Reference

This page is the single, canonical list of every g.with(key, value) option Graphersal recognises. Query authors: this is where to find every key that exists. Hosts embedding this engine (a CLI, a web playground, a multi-tenant backend): this is where to find every key an ExecutionPolicy can lock down.

Every key above changes a query's behavior, its safety bound, or its plan — never its result, except evaluationTimeout/repeat.max_loops themselves failing the query when a bound is hit. Setting a key again replaces its previous value; an unrecognised key is silently ignored.

An invalid value for a recognised key (wrong shape, out of range, an unknown rule name) fails with TraverserError::InvalidOption when the traversal is executed — with() itself has no error channel and always returns Self.

Host-Controlled Execution Policy

evaluationTimeout and repeat.max_loops exist specifically to bound a runaway query's resource use. But by themselves, both are just ordinary options: a query is free to set g.with("evaluationTimeout", 999999999).with("repeat.max_loops", 999999999) and defeat them. A host that runs untrusted queries against a shared graph — a public web playground, a multi-tenant backend — needs a way to fix a ceiling on any option above, outside the query's reach.

ExecutionPolicy is that ceiling. It is built once, by the trusted host, and attached to a TraversalGraph at construction time — before the graph is ever wrapped for sharing (Graph/Arc<TraversalGraph>) and handed to code that might run an untrusted query against it:

#![allow(unused)]
fn main() {
use graphersal::prelude::*;
use graphersal::exec::ExecutionPolicy;

let policy = ExecutionPolicy::permissive()
    // A query can no longer touch evaluationTimeout at all; every execution gets 2000 ms.
    .with_default("evaluationTimeout", 2000)
    .with_locked("evaluationTimeout")
    // Same for repeat.max_loops: no query-supplied value is ever honored.
    .with_default("repeat.max_loops", 500)
    .with_locked("repeat.max_loops");

let graph = TraversalGraph::tinkerpop_modern().with_execution_policy(policy);
let g = Graph::new(graph);
}

There is no setter after this point — not &mut self, not one gated behind a write lock. Once a TraversalGraph is constructed, its policy cannot change for the rest of its life; a host that wants different limits for a different session constructs a different graph instance.

Two independent knobs, settable per key:

• with_default(key, value) — applied when the query's own g.with() doesn't set key. Takes precedence over the engine's own hardcoded default, but the query can still override it unless the key is also locked.
• with_locked(key) — a query's own g.with(key, ..) attempt fails immediately with TraverserError::LockedOption, regardless of the value it tried to set. The policy's default (or, absent one, the engine's hardcoded default) always applies instead.

ExecutionPolicy::permissive() — no key locked, no default overridden — is the implicit policy of any TraversalGraph built without with_execution_policy(..): every option takes its engine default unless the query sets it.

Every key in the table above is checked against the policy the same, generic way, so a future option automatically participates in locking and defaulting without special-cased code.

Persistence

Graphersal keeps the graph in memory. The persist feature keeps it on disk too: in Graphersal's own binary format, losslessly, with every committed change made durable before the commit returns, so nothing committed is lost on a restart or a crash.

Looking for a command? The Command Cheat Sheet has every one of them, ready to copy.

What to choose

GraphML and GraphSON stay the exchange formats. The snapshot is the lossless one: every value type (uuid, nested arrays and objects, NaN payloads, property order), multi-label and unlabeled vertices, unlabeled edges, the schema, the catalog of definitions (saved queries), and the graph's position (commit sequence number, commit time, auto-id sequences).

graphersal = { version = "0.1", features = ["persist"] }        # LZ4 chunks, the Store, journals
graphersal = { version = "0.1", features = ["persist-zstd"] }   # also zstd chunks (pure Rust)
graphersal = { version = "0.1", features = ["persist-zip"] }    # also ZIP backups of a Store

Where it runs:

Concepts

Guarantees

• Durable commits. A Store commit (and a journal commit with Durability::EveryCommit, the default) is written and fsynced before it returns. A failed write or sync rolls the commit back: the caller never gets "ok" for a commit that is not on disk, and the WAL never holds a commit that did not happen.
• Crash safety. Opening a store after a crash (or kill -9) brings back exactly the last committed state: an interrupted last write is cut off, an interrupted multi-file operation is completed.
• Damage is found, never silently lost. Every header, chunk and record carries a CRC-32C; the small critical metadata exists twice. A damaged store opens read-only in maintenance mode with a report, and repair writes a new store elsewhere, never in place.
• Nothing is deleted implicitly. History goes away only through an explicit prune, a rollback with --delete, or removing an attic entry.
• Point in time. Every commit, time and mark that the retained history covers can be viewed read-only, forked into a new store, or rolled back to.
• Portable bytes. Little-endian, the same bytes on every platform and in WebAssembly; no file holds an absolute path, so a store can be moved or copied anywhere. The format is a public specification.
• One writer. A store has at most one writer (an operating-system lock); readers, backups and forks work while it runs.

This part of the book

• Quick Start: the CLI, Rust, Python and the playground in five minutes.
• Packed Snapshots and Journal and Recovery: the stream-level API.
• The Store and its pages: opening, commits, checkpoints, marks, point in time, fork, rollback, backups, prune and compaction, verify, damage and repair, format versions, backends, the single-file store, a Store over your own storage, and the creation parameters.
• Tools: the graphersal store command, the dev server and MCP, the store in the playground, Python.
• Storage Format Specification: the normative byte layouts.
• FAQ and Troubleshooting.

Quick Start

Command line

cargo build -p graphersal-cli                        # target/debug/graphersal
graphersal store create data/ --from modern          # a store with the modern graph, at commit 0
graphersal --graph data/ -e 'g.add_v("person").property("name", "zoe").to_list()'
graphersal store mark data/ before-import            # name this position
graphersal --graph data/ -e 'g.add_v("person").property("name", "ada").to_list()'
graphersal store info data/                          # commit 2, 1 snapshot, 1 mark
graphersal store fork data/ branch/ --at-mark before-import   # the state at the mark, as a new store
graphersal store backup data/ backup/                # a consistent copy, also while in use
graphersal --graph data/ --server                    # the playground UI on the store: http://127.0.0.1:8080/

Every commit to data/ is durable before the command returns; the REPL (graphersal --graph data/) and the dev server keep it open and commit every query. Ctrl+C closes the store cleanly; a crash or kill -9 loses nothing committed either.

Without a store, a packed snapshot saves and loads the whole graph:

graphersal -e 'g.export_snapshot("m.gsnap")'          # Exported a snapshot to m.gsnap (6 vertices, 6 edges, commit 0)
graphersal --graph m.gsnap -e 'g.v().count().next()'  # 6

Rust

graphersal = { version = "0.1", features = ["persist"] }

#![allow(unused)]
fn main() {
use graphersal::persist::{RecoveryTarget, Store, StoreOptions};

let store = Store::create("data", StoreOptions::new())?;      // later: Store::open("data", ..)
store.graph().write().traversal_mut().add_v("person").property("name", "ann").to_list()?;
store.mark("after-ann")?;                                      // a point-in-time target
store.checkpoint(Some("nightly"))?;                            // a snapshot of the current state
store.close()?;                                                // a clean close (Drop does it too)

let store = Store::open("data", StoreOptions::new())?;        // recovery: snapshot + WAL replay
assert_eq!(store.graph().read().vertex_count(), 1);
let past = Store::open_read_only("data", RecoveryTarget::Mark("after-ann".into()))?;
assert_eq!(past.graph.vertex_count(), 1);
Ok::<(), Box<dyn std::error::Error>>(())
}

store.graph() is the shared graph (Graph, a TraversalGraph behind a read-write lock); every commit of it is written to the store's write-ahead log and synced before it returns.

A packed snapshot over any Write / Read:

#![allow(unused)]
fn main() {
use graphersal::prelude::*;

let graph = TraversalGraph::tinkerpop_modern();
let mut bytes = Vec::new();
graph.write_snapshot(&mut bytes).unwrap();
let loaded = TraversalGraph::read_snapshot(bytes.as_slice()).unwrap();
assert_eq!(loaded.vertex_count(), 6);
}

Python

import graphersal

graph = graphersal.Graph.tinkerpop_modern()
graph.save("g.gsnap")                                    # {"commit_seq", "vertex_count", "edge_count"}
graph = graphersal.Graph.load("g.gsnap")

with graphersal.Store.create("data") as store:           # later: graphersal.Store.open("data")
    store.graph.execute('g.addV("person").property("name", "ann").next()')
    store.mark("after-ann")
    store.checkpoint("nightly")

Web playground

Every graph you load in the playground is a Store in memory: the Store menu in the top bar checkpoints, marks, opens past states read-only, forks and rolls back, exactly as the dev server does on a directory (The Store in the Playground). Everything in memory is lost on a page reload: Download current state (.gsnap) keeps a state, and the start page loads it back.

Packed Snapshots

A packed snapshot is the whole graph in one file or stream, conventionally named *.gsnap. It works over any std::io::Write / Read, so it runs in WebAssembly and on any stream a host has (a file, a socket, an upload). There is no journal and no directory: the application decides when to save. For durability between saves, add a journal or use the Store.

#![allow(unused)]
fn main() {
use graphersal::prelude::*;
use graphersal::persist::{self, ReadOptions, WriteOptions};
use graphersal::storage::PersistentStorage; // graph_id()

let graph = TraversalGraph::tinkerpop_modern();
let mut bytes = Vec::new();
let info = persist::write_snapshot(&graph, &mut bytes, &WriteOptions::new().with_name("nightly"))
    .unwrap();
assert_eq!(info.vertex_count, 6);

let header = persist::read_snapshot_info(bytes.as_slice()).unwrap();   // the manifest only
assert_eq!(header.name, "nightly");

let loaded = persist::read_snapshot(bytes.as_slice(), &ReadOptions::new()).unwrap();
assert_eq!(loaded.vertex_count(), 6);
assert_eq!(loaded.graph_id(), graph.graph_id());
}

graph.write_snapshot(w) and TraversalGraph::read_snapshot(r) are the same with default options.

Your own storage (EXPERIMENTAL): persist::write_snapshot takes any storage that implements graphersal::storage::PersistentStorage (for a shared graph pass &*graph.read()), and persist::read_snapshot_into(reader, &options, MyStorage::default()) loads a snapshot into an empty one through the trait's load sink. The same graph gives the same bytes in every storage. A shared Graph<MyStorage> built with Graph::new_persistent can also be written by the DSL's g.export_snapshot(path); built with plain Graph::new it cannot (Unsupported), except a Graph<TraversalGraph>, which is written either way. Recovery::new_in(MyStorage::default()) recovers a snapshot plus journals into it.

What a snapshot holds

• Every vertex (id, label set, properties in insertion order) and edge (id, optional label, endpoints, properties); every value type losslessly (uuid, nested arrays and objects, NaN payloads).
• The stored schema (its mode and declarations).
• The catalog of definitions (saved queries, ...). A definition of a kind this version does not know (written by a newer Graphersal) is kept byte for byte and written back unchanged (format spec 6.3, 16).
• The graph's identity and position: the lineage id (graph_id), the commit position (last_commit_seq), the time of the last commit, and the auto-id sequences, so the next automatic id never repeats one handed out before the snapshot.
• Counts and an estimate of the in-memory size (for a memory check before loading), a name and free-form meta text (WriteOptions::with_name, with_meta).

Indexes and statistics are not stored: they are rebuilt during the load.

Writing

• Writing holds the graph's read access for the whole write, so the snapshot is consistent; its position is graph.last_commit_seq().
• Elements are written sorted by id, in compressed, self-contained chunks (1 MiB uncompressed by default, with_chunk_bytes) grouped into segments (256 MiB by default, with_segment_bytes). Chunks are LZ4 (with_codec(Codec::Zstd) with the persist-zstd feature); a chunk below 4 KiB, or one compression does not shrink, is stored as is.
• The writer streams: the manifest at the start lists every segment's size and checksum, so a first pass encodes every chunk to plan them and keeps only those figures; the second pass encodes each chunk again and writes it straight to the writer. Memory: the sorted id index (about 24 bytes per element) and one chunk, never the encoded snapshot; the writer need not seek (a pipe, a socket, a download). The price is encoding the graph twice.
• A store imports a packed snapshot (Store::create_from_packed, graphersal store create --from x.gsnap) by copying it section by section into its snapshot directory, and exports one (export_packed) by streaming the files: neither holds the snapshot in memory.

Reading

• Reading loads vertices, then edges, rebuilds indexes and statistics, and restores the schema, the lineage id, the position, the commit time and the auto-id sequences.
• The schema is not re-validated: the data was valid when it was committed. Integrity comes from CRC-32C checksums on every header, chunk and section. Damage is a PersistError::Corrupt naming the section and the byte offset, never a panic or a silently wrong graph.
• ReadOptions::with_memory_limit(bytes) refuses a snapshot whose recorded size estimate does not fit, before anything is loaded (PersistError::MemoryBudget); with_max_value_depth(n) bounds value nesting (default 128, like traversal.max_value_depth).
• persist::read_snapshot_info(r) reads only the manifest: name, meta, identity, position, counts. It is how graphersal store list lists snapshots without loading them.
• A non-seekable stream is fine: the sections come in the order they are needed.

From the DSL, the CLI, Python and the playground

graphersal -e 'g.export_snapshot("m.gsnap")'          # Exported a snapshot to m.gsnap (6 vertices, 6 edges, commit 0)
graphersal --graph m.gsnap -e 'g.v().count().next()'  # 6
graphersal store export data/ data.gsnap              # a Store's latest snapshot as a .gsnap
graphersal store create data2/ --from data.gsnap      # a new Store from a .gsnap

• DSL: g.export_snapshot(path) (or g.exportSnapshot(..)) writes one; GraphSource::file("m.gsnap") loads one. Both need file access (Permissions).
• Python: graph.save(path) and graphersal.Graph.load(path) (Python).
• Playground: Save as snapshot on the start page, and a .gsnap file loads like any graph file; the Store menu downloads any stored snapshot as .gsnap.
• Dev server: GET /api/export?format=gsnap downloads the current state.

The byte layout is section 8 of the format specification: a packed file holds exactly the files of a Store's snapshot directory, so the Store imports and exports .gsnap files by copying (Store::create_from_packed, store.export_packed).

Journal and Recovery

The stream-level durability API: a packed snapshot as the base, a journal (write-ahead log) that records every commit after it, and recovery that replays the journals onto the snapshot, up to the end or to a target. Everything works over std::io::Write / Read, also in WebAssembly. The Store does all of this for you on a directory, a file or memory; use the journal directly when you manage the streams yourself.

#![allow(unused)]
fn main() {
use graphersal::prelude::*;
use graphersal::persist::{self, Durability, Journal, RecoveryTarget, SharedBuffer};

// A graph, its base snapshot, and a journal from then on.
let mut graph = TraversalGraph::tinkerpop_modern();
let mut snapshot = Vec::new();
graph.write_snapshot(&mut snapshot).unwrap();
let wal = SharedBuffer::new();                        // an in-memory Write; a File in practice
Journal::new(wal.clone(), Durability::EveryCommit).attach(&mut graph).unwrap();

graph.traversal_mut().add_v("person").property("name", "ann").to_list().unwrap();
graph.mark("after-ann").unwrap();
graph.traversal_mut().v("1").drop().to_list().unwrap();

// Recovery to the mark: ann is there, vertex 1 is not dropped yet.
let recovered = persist::recover(
    snapshot.as_slice(),
    [wal.contents().as_slice()],
    RecoveryTarget::Mark("after-ann".into()),
)
.unwrap();
assert_eq!(recovered.graph.vertex_count(), 7);
assert_eq!(recovered.report.commit_seq, 1);
}

The journal

A Journal is a commit hook that writes each committed unit (a lossless ChangeSet: every mutation with its before and after values, the commit time, the commit metadata, the auto-id sequences) to its writer before the commit becomes final.

#![allow(unused)]
fn main() {
use graphersal::prelude::*;
use graphersal::persist::{Durability, Journal};

let mut graph = TraversalGraph::new();
let file = std::fs::File::create("graph.wal").unwrap();
Journal::for_file(file, Durability::EveryCommit)       // fsync per commit
    .attach(&mut graph)
    .unwrap();
graph.traversal_mut().add_v("person").to_list().unwrap(); // written and synced, then committed
}

• Write-ahead, with a veto. A failed write or sync rolls the unit back and the caller gets GraphError::CommitRejected: memory and journal never diverge, and nobody gets "ok" for a commit that is not on disk.
• Always last. The journal has its own slot after every other commit hook, whatever the registration order, and the commit sequence number is assigned before it writes. Once its record is written nothing can veto the unit any more, so a journal never holds a commit that did not happen.
• Refused records are cut off. When a write or sync fails, the record is cut off the stream again (with the truncate function: Journal::for_file sets set_len + fsync, with_truncate(f) sets one for any writer), so a later recovery never replays a commit the caller was told failed. A writer without a truncate function cannot do this.
• Poisoning. After a failed write or sync the state of the stream is unknown; the journal then rejects every later commit and mark (PersistError::Poisoned). Recover the graph and attach a new journal.
• Durability (Durability): EveryCommit (the default: sync per commit and mark), Interval(duration) (sync at most that often; a crash of the machine may lose the last interval, never a commit in the middle), Os (flush only; the operating system writes; a crash of the process loses nothing, a crash of the machine may). Journal::new(writer, ..) syncs with flush; with_sync(f) or Journal::for_file give it a real fsync.
• Durable end. attach returns a DurableEnd: the byte offset after the last synced record and its commit number, readable without any lock (a backup copies a journal up to it).
• One journal per graph. attach writes the stream header (the lineage id and the next commit number) and fails when the graph already has one or a unit is open.
• Large records (from 4 KiB) are LZ4-compressed (with_codec).
• One commit is at most 1 GiB of uncompressed record body (every change with its before and after values). A larger unit is vetoed with PersistError::CommitTooLarge (inside GraphError::CommitRejected from the hook journal): it rolls back, nothing is written, and the journal stays usable. Split the work into smaller units (Resource Limits).
• A user hook that panics in before_commit rolls the unit back before the journal runs, so the journal never holds it (Transactions).
• A panic inside the journal (in its own write path: an engine bug, or a writer, sync or store backend that panics) is handled like a failed write: the record is cut off again, the journal poisons itself, and the panic continues; the unit is rolled back on the way out. See Failures while committing.

Failures while committing

A commit asks the user hooks first (in registration order), then the journal. Whatever goes wrong there, the promise is the same: the unit is either committed in memory AND in the journal, or in neither. What you see, and what a reopen (a recovery, Store::open) gives:

A poisoned journal refuses every later commit and mark with PersistError::Poisoned (inside CommitRejected from the hook journal; its help says what to do), also once the disk works again: after a failure in the middle of a record the state of the stream is unknown, so nothing may follow it. A Store's close() then fails with StoreFailure::JournalSyncFailed and does not mark the store as closed cleanly. What to do: check the disk (or report the panic: it is a bug), then reopen the store (or restart the server): the recovery continues from the last durable commit and the store accepts commits again. With a bare Journal, recover the graph (persist::recover) and attach a new journal.

The same applies to a mark (graph.mark(..)) and to the Store's own records (a checkpoint record, the sync at close()): a panic poisons the journal and continues.

Marks

A mark names a point in the journal: the state right after the last commit.

graph.mark("before-import")?;   // Rhai: g.mark("before-import"); Python: graph.mark(..)

Names are unique within a journal (pass the names of earlier journals with Journal::with_known_marks, e.g. from RecoveryReport::marks). A graph without a journal, or a mark inside an open transaction, is an error (GraphError::MarkUnavailable). In the DSL g.mark needs the Update permission on data. The Store keeps mark names unique along its whole history.

Recovery

use graphersal::persist::{self, Recovery, RecoveryTarget};

let recovered = persist::recover(snapshot_reader, [journal_1, journal_2], RecoveryTarget::Latest)?;
let graph = recovered.graph;              // unpublished, no hooks: attach a new journal
println!("{:?}", recovered.report);       // position, commits replayed, marks, torn tail

// The builder: no snapshot (start from an empty graph), read options, a target.
let recovered = Recovery::new()
    .journal(journal_reader)
    .target(RecoveryTarget::CommitSeq(12))
    .run()?;

• Journals are replayed with TraversalGraph::replay: outside units, without hooks and without schema validation. Commits already in the snapshot are skipped; the first one after it must be the next number, and so on (a missing journal is PersistError::Gap). A journal of another lineage is refused (PersistError::LineageMismatch). Without a snapshot the replay starts from an empty graph and the first journal must start at commit 1.
• The report (RecoveryReport): the snapshot's position, the position reached and its time, the number of commits replayed, the marks seen, whether the end was reached, and a torn tail.
• Torn tail vs damage. Only an incomplete record at the very end of the last journal (an interrupted write) is a torn tail: it is ignored and reported. A complete record whose checksum fails, anywhere, is damage and fails the recovery with its location (PersistError::Corrupt). Every record header (sync marker, length, commit number, type) has its own checksum, separate from the payload's, so a damaged length is damage too, never taken for an interrupted write; zeros after the last complete record (space the file system allocated but the write never filled) are a torn tail.
• A past target is a past state. Attach a journal to a graph recovered to a target before the end only as a new history (a new lineage: give it a new id with PersistentStorage::set_graph_id first), never to continue the old journal.
• Reading a journal without replaying it: persist::read_journal(r) iterates its records (JournalRecord: commits as ChangeSets, marks, checkpoints) and reports a torn tail.

Lineage

PersistentStorage::graph_id() (implemented by TraversalGraph; import the trait from graphersal::storage) is a UUID (version 7) created on first use and carried by every snapshot and journal; read_snapshot restores it. Recovery replays a journal only onto a snapshot of the same lineage. In a Store, a fork, an in-place rollback and a repair start a new lineage that records its parent and the commit it branched at; recovery follows that chain.

Python

graph.save("g.gsnap")                                       # the base
graph.start_journal("g.wal", durability="every_commit")     # or "os", or seconds (an interval)
graph.execute('g.addV("person").property("name", "ann").next()')
graph.mark("after-ann")
graph, report = graphersal.Graph.recover("g.gsnap", ["g.wal"], mark="after-ann")   # or commit_seq=, time=

The byte layouts of journal records are section 9 of the format specification.

The Store

For an application that keeps its graph, the Store does everything of the previous pages for you: one directory holds the graph's snapshots and its write-ahead log, every commit is durable before it returns, and opening the directory brings the graph back exactly as the last commit left it, also after a crash. One directory = one graph, one writer: "SQLite for graphs".

The directory is usually a path on disk. It can also be one single file (graph.gstore, for embedded use) or live in memory (every target, the browser included).

#![allow(unused)]
fn main() {
use graphersal::persist::{RecoveryTarget, Store, StoreOptions};

let store = Store::create("data", StoreOptions::new())?;      // or Store::open("data", ..)
store.graph().write().traversal_mut().add_v("person").property("name", "ann").to_list()?;
store.mark("after-ann")?;                                      // a point-in-time target
store.checkpoint(Some("nightly"))?;                            // a snapshot of the current state
store.close()?;                                                // a clean close (Drop does it too)

let past = Store::open_read_only("data", RecoveryTarget::Mark("after-ann".into()))?;
assert_eq!(past.graph.vertex_count(), 1);
Ok::<(), Box<dyn std::error::Error>>(())
}

graphersal store create data/ --from modern     # the same from the command line
graphersal --graph data/ -e 'g.add_v("person").property("name", "ann").to_list()'
graphersal store info data/

The files

data/
├── GRAPH, GRAPH.copy        identity, lineage, state (two copies of the same small file)
├── LOCK                     held by the one writer (an operating-system lock)
├── BACKUP                   the backup pin: held shared while a backup copies, prune waits for it
├── INTENT                   only while a multi-file operation runs (rollback, prune, ...)
├── marks                    the marks, rebuilt from the WAL when lost
├── snapshots/
│   └── 00000000000000000003/      one snapshot, named by its commit (20 digits)
│       ├── manifest               identity, position, counts, the segment list, every chunk's checksum
│       ├── schema.json            the stored schema
│       ├── v-000000.seg           vertices, sorted by id, in compressed chunks
│       └── e-000000.seg           edges
├── wal/
│   └── 00000000000000000004.wal   write-ahead log segments, named by their first commit (16 MiB each)
└── attic/
    └── 20261008T070510Z-00000000000000000002/   history a rollback moved aside

Every name is relative to the store's root, and no file records a path: move or copy the whole directory and open it there. The exact byte layouts are the Storage Format Specification.

The pages of the Store

What works while the store is open elsewhere (a dev server, a REPL, another program):

Opening and Closing

Create

#![allow(unused)]
fn main() {
use graphersal::prelude::*;
use graphersal::persist::{Store, StoreOptions};

let empty = Store::create("data", StoreOptions::new())?;                  // an empty graph
let modern = Store::create_with("modern-data", TraversalGraph::tinkerpop_modern(), StoreOptions::new())?;
let file = std::io::BufReader::new(std::fs::File::open("m.gsnap")?);
let restored = Store::create_from_packed("from-gsnap", file, StoreOptions::new())?;  // from a .gsnap
Ok::<(), Box<dyn std::error::Error>>(())
}

The directory must be missing or empty. A new store has one snapshot (commit 0, the initial graph) and an empty WAL, and is open read-write when create returns. A path ending in .gstore (or Store::create_file) makes a single-file store. StoreOptions::with_chunk_bytes sets the snapshot chunk size, which is fixed for the store's life (Checkpoints).

graphersal store create data/ --from modern       # --from: modern, empty, large, tree, a GraphSON/GraphML file, a .gsnap
graphersal store create small-chunks/ --chunk-size 262144   # 256 KiB chunks
graphersal --graph new/ --create-store -e 'g.add_v("person").to_list()'   # create when missing ("note: created the store new/ (damage policy maintenance)")

Open: recovery on open

Store::open(dir, options) opens a store read-write and always runs its recovery:

1. takes the writer lock (a second writer, in this or another process, gets PersistError::Locked: "the store ... is in use");
2. completes an interrupted multi-file operation (an INTENT file: a rollback, an attic restore, a prune) and removes temporary files of an interrupted checkpoint;
3. checks the set of WAL segments against GRAPH (a lost, emptied or replaced newest segment is damage, never a shorter history);
4. loads the latest snapshot and replays the WAL after it;
5. cuts an interrupted last write of the WAL (a torn tail) and rebuilds a lost marks file;
6. marks the store as open and attaches the journal: from now on every commit is durable.

store.open_report() says what happened: whether the last close was clean (clean_close), the snapshot it started from and the commits replayed, a cut torn tail, a completed intent, removed temporary files, a repaired GRAPH copy, warnings. A store that was not closed cleanly (a crash, kill -9, a power cut) is not damaged: the WAL replay brings back every commit; the CLI then notes "not closed cleanly", which is harmless.

$ graphersal --graph data/ -e 'g.v().count().next()'
9

Damage never fails the open and is never skipped silently: the store opens read-only in maintenance mode with a damage report. A backup directory is refused by Store::open (PersistError::IsBackup): it opens read-only through Store::open_backup until it is restored. A store that holds something critical this build does not know (a critical definition of an unknown kind, written by a newer Graphersal) opens read-only too: Store::read_only_reason() says why, OpenReport::read_only records it, and every write is refused with PersistError::ReadOnly (Format Versions).

In the CLI, --graph <path> opens a Store when the path is a directory, ends in /, is a missing path without an extension, ends in .gstore, or is an existing single-file store. --create-store creates it when it does not exist yet (missing or empty directory).

Read without opening

None of these take the writer lock; all work while a writer has the store open:

Close

store.close() (and Drop) closes cleanly: it syncs, records the last commit and marks the store "closed cleanly" in GRAPH, and releases the lock. After close() the shared graph refuses commits (another holder of the Arc<Graph> gets an error, not a silent loss). store.shutdown() does the same through a shared reference. With StoreOptions::with_checkpoint_on_close(true) a checkpoint is written first, so the next open replays nothing.

Ctrl+C (SIGINT, SIGTERM) in the CLI, its REPL and the dev server closes an open store cleanly: the running query is cancelled first (it rolls back), then the store is closed. A second Ctrl+C exits at once (harmless too: every commit is already durable). The dev server exits with 0, the REPL and -e runs with 130.

Stopping: closing the store data/ (Ctrl+C again to exit at once)...
The store data/ was closed cleanly.

Locking

One store has at most one writer: an operating-system lock on LOCK (on a single file, the lock on the file itself; in memory, an in-process flag), released by the operating system when the process ends, so a crashed writer never leaves a stale lock. Readers (inspect, listings, open_read_only, verify, fork, backups, export) take no lock. Two Store values of the same directory in one process are two writers: the second gets PersistError::Locked too.

Commits and Durability

Every commit of store.graph() (every traversal, every transaction(..), every import; see Transactions) is written to the store's write-ahead log as one record and made durable before it returns. A commit that changes nothing writes nothing.

#![allow(unused)]
fn main() {
use std::time::Duration;
use graphersal::persist::{Durability, Store, StoreOptions};

let store = Store::open("data", StoreOptions::new())?;                    // fsync per commit
let fast = Store::open(
    "other",
    StoreOptions::new().with_durability(Durability::Interval(Duration::from_millis(200))),
)?;
store.graph().write().traversal_mut().add_v("person").to_list()?;          // on disk when it returns
Ok::<(), Box<dyn std::error::Error>>(())
}

Durability

The write-ahead guarantees

• The journal runs last. The store's journal is a commit hook in its own slot after every other hook (your own hooks, schema checks, a veto), and the commit's sequence number is assigned before it writes. Once the record is written nothing can veto the commit any more: the WAL never holds a commit that did not happen.
• A failed write or fsync vetoes the commit: it rolls back and the caller gets GraphError::CommitRejected with the reason. Memory and disk never diverge, and nobody gets "ok" for a commit that is not on disk.
• Refused records are cut off. Before the store gives up, the refused record is cut off the WAL again (and synced), so a commit the caller was told failed is never replayed. If even that cut fails, its position is recorded in GRAPH, and the next open cuts there (every reader stops there meanwhile).
• A panicking hook rolls back. A commit hook of your own that panics in before_commit rolls the unit back (the panic then continues to the caller); the journal runs after it and never writes that unit (Transactions). A panic inside the journal itself (a bug, or a store backend that panics while the WAL is written) cuts the record off again, poisons the journal and rolls the unit back too. Every case, with what a reopen gives, is in the table Failures while committing.
• Poisoning. After a failed fsync the state of the file is unknown, so the store refuses every later commit and mark (PersistError::Poisoned) until it is reopened. Reopening runs the recovery and continues from the last durable commit.
• After close() the graph refuses commits.

The durable end

store.durable_end() is the position after the last record whose sync completed (its WAL segment, byte offset and commit). It is readable without any lock: a backup copies the WAL only up to it, because a record after it may still be vetoed.

WAL segments

The WAL is a sequence of segment files wal/<first commit>.wal, 16 MiB each by default (StoreOptions::with_wal_segment_bytes; a record is never split, a segment closes after the record that passes the size). A segment is closed with an fsync before the next one starts, so only the last segment can end in an interrupted write. Starting a segment is recorded in GRAPH, so a lost, emptied or replaced newest segment is reported as damage instead of opening the store at an earlier commit (Damage).

Large records (from 4 KiB) are compressed (StoreOptions::with_codec).

The size of one commit

Every commit is one WAL record, and its body is at most 1 GiB before compression (format spec 9.3). The body holds every change of the unit with its before and after values, a dropped element with its full properties included, so a unit that drops and re-creates a few hundred thousand elements with long texts can reach it. Such a commit is refused (GraphError::CommitRejected from the hook journal, its source PersistError::CommitTooLarge): the unit rolls back, nothing is written, the store keeps working. Split the work into smaller units: in the playground and the dev server a whole script is one unit, so drop in a run of its own and create the data over several runs; in the CLI, Python and Rust every traversal is its own unit already. See Resource Limits.

Reading the committed changes (CDC)

#![allow(unused)]
fn main() {
use graphersal::persist::{Store, StoreOptions};
let store = Store::open("data", StoreOptions::new())?;
for change in store.changes_since(10)? {        // every commit after commit 10, in order
    let change = change?;
    println!("commit {} at {}: {} mutation(s)", change.commit_seq(), change.committed_at(),
             change.mutations().len());
}
Ok::<(), Box<dyn std::error::Error>>(())
}

changes_since(commit) streams the committed ChangeSets from the WAL, up to the durable end: every mutation with its before and after values, the commit time and metadata. It is the basis for change data capture, replication and audit. It fails when the WAL it needs was pruned. For a live process, a commit hook gets every ChangeSet as it commits; the WAL's byte format is public (format specification, section 9) for readers in other processes and languages.

Checkpoints and Snapshots

A snapshot is a full copy of the graph at one commit, in snapshots/<commit>/. A checkpoint writes a new one from the current state. Snapshots make opening fast (only the WAL after the latest snapshot is replayed) and are the starting points of every point-in-time load. The WAL is not shortened by a checkpoint: old history stays until you prune it.

#![allow(unused)]
fn main() {
use graphersal::persist::{Store, StoreOptions};
let store = Store::open("data", StoreOptions::new())?;
let info = store.checkpoint(Some("nightly"))?;        // a name is optional
println!("snapshot at commit {} ({} vertices)", info.commit_seq, info.vertex_count);
for snapshot in store.snapshots()? {
    println!("{} {} {}", snapshot.commit_seq, snapshot.name, snapshot.vertex_count);
}
Ok::<(), Box<dyn std::error::Error>>(())
}

$ graphersal store checkpoint data/ --name nightly
Snapshot at commit 3 (8 vertices, 6 edges).
Merged from the snapshot at commit 0 and 3 commits: 0 segment files reused, 0 copied, 2 written.
$ graphersal store list data/
      commit  last commit             vertices       edges  name
           0  -                              6           6
           3  2026-10-08T07:05:08Z           8           6  nightly

How a checkpoint is written

A checkpoint is merged: the new snapshot is built from the newest snapshot and the WAL after it, not from the graph in memory, and without the graph's lock: commits go on while it runs and land after its position (the next checkpoint picks them up).

1. The WAL records after the newest snapshot are read (every checksum) and the ids they touch are collected: the vertices and edges a change names, and the endpoints of the edges added or dropped.
2. The chunks of the newest snapshot that hold one of these ids (found through its manifest's chunk index, each checksum checked) are decoded into a small delta graph, with the snapshot's schema, catalog of saved queries, position and auto-id sequences.
3. The WAL is replayed onto the delta graph exactly as an open replays it, and every change's before image must match: a WAL that does not continue the snapshot is damage.
4. The touched segments are read again as streams and merged on the sorted id with the delta into new segment files (planned first, then written chunk by chunk and checked against the plan). A segment no touched id falls into keeps its bytes under the donor rule: it is reused by reference (the manifest names a file of an older snapshot's directory: an incremental snapshot) when the snapshot before the old one holds an identical copy in another file, and copied into a new file otherwise.
5. The new snapshot goes into a temporary directory, is synced, verified (every file it names, the referenced ones too, read back one chunk at a time) and only then renamed to its final name. A Checkpoint record goes to the WAL and the next commit starts a new WAL segment.

Memory is proportional to the changes since the last snapshot (the delta graph, one decoded chunk, one chunk being written), not to the graph. Beyond a bound, StoreOptions::with_checkpoint_merge_bytes(bytes) (the WAL bytes after the last snapshot; 1 GiB by default, 64 MiB in the browser; 0 = never merge), the checkpoint encodes the graph in memory instead, under its read lock (writers wait, readers do not; memory: about 24 bytes per element and one chunk). The same streaming encoder writes a store's first snapshot, a fork, a repaired store and packed snapshots.

Damage in anything the merge reads (a manifest, schema.json, a chunk, a segment file, a WAL record, a gap in the commits, a foreign lineage, a WAL that does not continue the snapshot) stops the checkpoint with the error: nothing visible is written (the temporary directory is removed) and the store keeps running. Run graphersal store verify then.

• A checkpoint at a commit that already has a snapshot returns that snapshot (nothing committed since: nothing written).
• The live store merges up to the WAL's durable end (with Durability::EveryCommit, the last commit; a manual checkpoint or a checkpoint on close syncs the WAL first).
• Segment files are the unit of reuse: a change rewrites the whole segment holding it (64 MiB by default for a store, with_snapshot_segment_bytes), and the next checkpoint copies it once (the donor rule). Smaller segments mean less rewriting per checkpoint and more files.
• Files of an older snapshot that a newer one uses stay when prune removes the older snapshot; a packed export of an incremental snapshot is self-contained.
• In a backup, in maintenance mode or in a store this version may only read, checkpoints are refused; while a dev server holds the store, use its Store menu (Checkpoint).

A closed store

graphersal store checkpoint <dir> (Rust: Store::checkpoint_dir(dir, options, name)) merges a CLOSED store without loading its graph: it takes the writer lock (a store open elsewhere is refused as "in use"), completes an interrupted operation and removes temporary files as an open would, merges the newest snapshot with the whole WAL (an interrupted last record is ignored; the next open cuts it), and writes nothing else (no Checkpoint record, GRAPH unchanged). The report says what it did:

$ graphersal store checkpoint data/ --name nightly
Snapshot at commit 3 (8 vertices, 6 edges).
Merged from the snapshot at commit 0 and 3 commits: 4 segment files reused, 0 copied, 1 written.

The donor rule

A repair rebuilds a damaged chunk of the newest snapshot from the previous snapshot plus the WAL between them: the previous snapshot is the donor. A file both used would be damaged in both. So a checkpoint never uses a file the newest snapshot (its base) uses:

• a segment it rewrites is a new file anyway;
• an unchanged segment is referenced only through a twin: the snapshot before the base holds the same bytes (same id range, element count, length, checksum and chunk index) in another file, and the new snapshot names that file;
• without a twin, its bytes are copied into a new file of the new snapshot (every byte read and checked).

An unchanged range therefore alternates between two files from checkpoint to checkpoint (the newest snapshot uses one, the previous one the other): only the first checkpoint after a range was rewritten copies it (the store's second snapshot copies everything unchanged once). CheckpointReport::segments_reused, segments_copied and bytes_copied say what happened. verify warns (not damage) when the newest snapshot shares a file with the previous one, which only a store written otherwise can show; the next checkpoint copies it.

Automatic checkpoints

When the WAL since the last snapshot passes 256 MiB, a checkpoint runs automatically on a background thread (StoreOptions::with_checkpoint_after_bytes(bytes); 0 = never; a store opened with more WAL than that checkpoints right away). It merges like a manual one, so commits do not wait for it. Without threads (WebAssembly) it runs when the host calls store.run_due_checkpoint() (the playground does after every run; the default threshold there is 4 MiB). store.last_auto_checkpoint_error() reports a failed background checkpoint; store.wal_bytes_since_checkpoint() the current amount.

When it runs:

• Every commit wakes the background thread while the WAL since the last snapshot is at or above the threshold (wakes coalesce: a commit during a running checkpoint leaves one pending).
• After a checkpoint that wrote a snapshot, the thread checks the level again at once: commits that landed while it ran (a single commit can be larger than the threshold) get the next checkpoint without waiting for another commit.
• A failed automatic checkpoint is retried at the next commit, as long as the level is still at or above the threshold. It is never retried in a loop of its own: a checkpoint that keeps failing (a full disk, say) costs at most one attempt per commit, and none while nothing is committed. last_auto_checkpoint_error() keeps the last failure until a checkpoint succeeds.
• run_due_checkpoint() follows the same rule: one attempt per call, while the level is at or above the threshold. StoreOptions::with_checkpoint_on_close(true) writes one at every clean close.

The chunk size

Elements are stored sorted by id in compressed, self-contained chunks (1 MiB uncompressed by default), grouped into segment files (64 MiB in a store, 256 MiB in a packed snapshot; with_snapshot_segment_bytes). The chunk is the unit of repair: a damaged chunk is rebuilt from an older snapshot's chunks for the same id range. Its size is a property of the store, chosen at creation (StoreOptions::with_chunk_bytes, graphersal store create --chunk-size) and fixed for the store's life. Smaller chunks mean finer repair and more overhead.

Snapshots as .gsnap files

A stored snapshot is exactly a packed snapshot laid out as files:

graphersal store export data/ data.gsnap              # the latest snapshot
graphersal store export data/ first.gsnap --commit 0  # Exported the snapshot at commit 0 to first.gsnap.
graphersal store create copy/ --from data.gsnap       # a new store from a .gsnap

store.export_packed(commit, writer) and Store::create_from_packed(dir, reader, options) do the same in Rust; the dev server's Store menu offers each snapshot as a .gsnap download. A .gsnap of a state that has no snapshot: open it read-only at that target and write it with write_snapshot, or download Download current state (.gsnap) from a read-only view.

Marks

A mark names a position in the store's history: "the state right after the last commit". It is a record in the WAL (and a line in the marks file) and costs a few bytes; no data is copied. Use it to remember a moment by name, "before-import", and come back to it later with --at-mark before-import.

#![allow(unused)]
fn main() {
use graphersal::persist::{Store, StoreOptions};
let store = Store::open("data", StoreOptions::new())?;
let mark = store.mark("before-import")?;
println!("{} at commit {}", mark.name(), mark.commit_seq());
for mark in store.marks()? {
    println!("{} {} {}", mark.commit_seq(), mark.time(), mark.name());
}
Ok::<(), Box<dyn std::error::Error>>(())
}

$ graphersal store mark data/ before-import
Mark "before-import" at commit 1.
$ graphersal store marks data/
           1  2026-10-08T07:05:08Z  before-import

• Mark names are unique along the store's whole history, across rollbacks and lineages; a duplicate is refused. A mark is never removed (an in-place rollback hides the marks after its target in the attic with the rest of that history).
• A mark needs its history: a snapshot at or before it and the WAL from there to it. A prune that removes that history makes the mark unreachable: store.marks(), store info and the Store menu leave it out from then on, --at-mark on it fails with "a prune removed the history it needs", and its name stays taken (setting it again says so). The prune names such marks (report.marks_unreachable), and the compaction advice names them before you compact.
• A mark's time is the time it was set (never earlier than the last commit).
• From a script: g.mark("before-import") on a graph that has a journal (the CLI's --graph data/, the dev server; it needs the Update permission on data). From the dev server: the Store menu's Mark (MCP has no persistence tools). From Python: store.mark(name).
• A mark inside an open transaction, or on a graph without a journal, is an error (GraphError::MarkUnavailable). A store that is a backup, read-only or in maintenance mode refuses marks.
• Marks are not copied by a fork or a repair: they belong to the history they were set in.

Snapshots and marks

Both name a point in the store's history, but they are different things, and neither limits where you can go back to: every commit is a target (--at-commit N), and so is every point in time (--at-time).

Point in Time

Every state the retained history covers can be brought back: read-only, as a new store, or as the store's own state again.

Targets

Every commit is a target, not only snapshots and marks. A target is resolved the same way for every action: the nearest snapshot at or before it is loaded and the WAL is replayed up to the target, following the lineage chain across forks and in-place rollbacks. A target needs the snapshot and WAL that lead to it: after a prune, targets before the oldest kept snapshot are gone (PersistError::TargetNotReached).

The time format

TIME is an RFC 3339 / ISO 8601 date-time with a zone, or microseconds since the Unix epoch:

2026-10-08T02:43:00Z          UTC
2026-10-08T02:43Z             seconds may be left out
2026-10-08T04:43:00+02:00     an offset
2026-10-08T02:43:00.250Z      a fraction of a second
1760000000000000              microseconds since 1970-01-01T00:00:00Z

• A time without a zone is refused (it would depend on the machine's time zone), and so is a bare date: a day is not a moment, and whether its start or its end is meant, in which zone, changes the target. The error shows the explicit forms (the same text in the CLI and the dev server's {"time": ..}):

  --at-time: "2026-10-08" is a date without a time and a zone, which is refused (it names no moment): write 2026-10-08T23:59:59Z for the end of that day in UTC, or with an offset, e.g. 2026-10-08T00:00:00+02:00 for its start at UTC+02:00 (RFC 3339)
  

  Python takes a time only as microseconds since the epoch (time=), so no text is parsed there.

• A time covers the whole second (or minute) it names: 2026-10-08T02:43Z means up to 02:43:59.999999. So a time copied from store list or store marks, which print whole seconds in this format, includes the commit printed with it.

• Times are printed in UTC (2026-10-08T07:05:08Z). The dev server's Go to time... takes a date and time in the browser's time zone.

What you can do with a target

Read-only views

#![allow(unused)]
fn main() {
use graphersal::persist::{RecoveryTarget, Store};

let past = Store::open_read_only("data", RecoveryTarget::CommitSeq(12))?;
println!("commit {}: {} vertices", past.report.commit_seq, past.graph.vertex_count());
let mut graph = past.graph;                  // an unpublished TraversalGraph: query it, export it
let names = graph.traversal_mut().v(None::<()>).values("name").to_list()?;
Ok::<(), Box<dyn std::error::Error>>(())
}

Store::open_read_only takes no lock and works while a writer has the store open, also on a backup. It returns the graph with a RecoveryReport; the graph has no journal, so changes to it are not stored anywhere (attach a journal only as a new history: a new lineage). A commit after the end of the history, or a mark that does not exist, is an error (PersistError::TargetNotReached); a time after the last commit is the latest state.

In the dev server, Open read-only here makes the server serve that state instead of the live graph: queries, the drawing, the schema and the statistics show it, every write is refused ("the served state is a read-only view at commit N ...: writes are refused"; its help points to Back to the live graph and to a fork), and a banner offers Back to the live graph. The view is shared by every browser tab and the MCP agent. See Dev Server and MCP.

Fork

A fork makes a past (or the current) state of a store into a new, writable store in another directory. The source store is not changed; to undo a fork, delete the new directory.

#![allow(unused)]
fn main() {
use graphersal::persist::{RecoveryTarget, Store, StoreOptions};

let store = Store::open("data", StoreOptions::new())?;
let report = store.fork(RecoveryTarget::Mark("before-import".into()), "branch")?;
let info = &report.snapshot;
println!("forked at commit {}: graph {:032x}, parent {:032x}",
         info.commit_seq, info.graph_id, info.parent_graph_id);
for mark in &report.marks_not_carried {
    println!("mark not carried: {} @ commit {}", mark.name(), mark.commit_seq());
}
let branch = Store::open("branch", StoreOptions::new())?;
// Without opening the source (works while a writer has it open):
Store::fork_dir("data", RecoveryTarget::CommitSeq(2), "branch2")?;
Ok::<(), Box<dyn std::error::Error>>(())
}

$ graphersal store fork data/ branch/ --at-mark before-import
Forked into branch/ at commit 1: graph 01a11a54-87d2-7995-b2cb-e450e4319735 (parent 01a11a54-8209-7661-92e2-147ae6d8bbd3).
Marks not carried (1; they stay targets of data/ only):
  before-import @ commit 1
Open it: graphersal --graph branch/ --server (or the REPL: graphersal --graph branch/).
data/ is unchanged; to undo the fork, delete the directory branch/.

• The target is any point in time; without one, the latest state.
• The new store has a new lineage id that records its parent and the commit it branched at (graphersal store info branch/ shows parent and branched at), one snapshot at the target, and an empty WAL. It keeps the source's chunk size and damage policy, but it is another store with its own store id: it never continues the source's incremental backups (back it up into a new directory).
• Marks are not carried: the new lineage starts without marks (they are names in the source's history, which the fork does not copy). The ForkReport (marks_not_carried), the CLI (Marks not carried ..., one name @ commit N line each), Python ("marks_not_carried") and the dev server (marksNotCarried) list the source's marks at or before the fork's position; they stay targets of the source store. Set them again in the fork if you need them there (store.mark(..), graphersal store mark).
• NEW_DIR must not exist (or be empty). A fork of a single-file store can be a .gstore file (the dev server names it <store>-fork-<target>.gstore next to the source).
• A fork reads the source without any lock: it works while a dev server or a REPL has the source open, and on a backup (the way to get a writable copy that leaves the backup as it is).
• A fork of a past state is how you continue writing from it without touching the source. To take the source itself back, use an in-place rollback.
• An attic entry can be forked too: store.attic_fork(id, dir), graphersal store attic <DIR> fork <ID> <NEW_DIR>. Its report lists the marks of the entry's history (the store's before the rollback target, the entry's own after it), not carried either.

Python: store.fork("branch", mark="before-import") (or commit_seq=, time= in microseconds) returns the snapshot's dict plus "marks_not_carried": [{"name", "commit_seq"}].

Rollback and the Attic

An in-place rollback takes the store itself back to a commit, a time or a mark. Everything after the target is not deleted: it moves into the attic, so the rollback can be undone.

#![allow(unused)]
fn main() {
use graphersal::persist::{RecoveryTarget, RollbackMode, Store, StoreOptions};

let store = Store::open("data", StoreOptions::new())?;
let report = store.rollback_to(RecoveryTarget::Mark("before-import".into()), RollbackMode::Move)?;
println!("{} -> {}", report.previous_commit_seq, report.target);
let id = report.attic.unwrap();
for change in store.attic_changes(&id)? {               // what was rolled back
    println!("{}", change?.commit_seq());
}
store.attic_restore(&id)?;            // undo the rollback (only while nothing was committed since)
// store.attic_fork(&id, "branch")?;  // or: the rolled-back history as a new store
// store.attic_remove(&id)?;          // or: delete it for good
Ok::<(), Box<dyn std::error::Error>>(())
}

$ graphersal store rollback data/ --at-mark before-import
Rolled back from commit 4 to commit 1: new lineage 01a11a54-8977-7c30-b874-01937ab2e3a4.
The history after it (commits 2..=4, 1 snapshot(s), 2 WAL file(s)) is in the attic as 20261008T070510Z-00000000000000000002.
Undo (only while nothing new is committed or marked): graphersal store attic data/ restore 20261008T070510Z-00000000000000000002
Keep it as a new store instead: graphersal store attic data/ fork 20261008T070510Z-00000000000000000002 <NEW_DIR>; delete it: graphersal store attic data/ remove 20261008T070510Z-00000000000000000002

What a rollback does

• Everything after the target (the later snapshots and the WAL after it; the WAL segment holding the target is split at the first commit after it) moves into attic/<time>-<first moved commit>/, with an ATTIC file that says what it is.
• The store continues as a new lineage: a new graph_id whose parent is the old one at the target, with a new WAL segment. Point-in-time loads and verify follow the lineage chain, so the history before the target stays reachable.
• The marks after the target go with the history into the attic.
• store.graph() is replaced in place: the Arc<Graph> your application holds now holds the state at the target, and the commit hooks you registered on it stay.
• RollbackMode::Delete (CLI --delete) deletes the history instead: there is no undo.
• The rollback runs under an INTENT file with idempotent steps: a crash in the middle is completed at the next open, never left half done. Commits wait while it runs.
• Refused: a target at or after the current commit ("there is nothing after commit N"), a target before the oldest retained snapshot, a store that is a backup, read-only or in maintenance mode. From the CLI the store must not be open elsewhere ("in use"); with a dev server running, use its Store menu (Roll back here...), which cancels a running query first.

The attic

$ graphersal store attic data/
20261008T070510Z-00000000000000000002  commits 2..=4 rolled back at 2026-10-08T07:05:10Z (rollback to mark "before-import"), 9.3 KiB, 1 snapshot(s)
$ graphersal store attic data/ changes 20261008T070510Z-00000000000000000002
commit        2  2026-10-08T07:05:08Z  1 mutation(s)
commit        3  2026-10-08T07:05:08Z  1 mutation(s)
commit        4  2026-10-08T07:05:09Z  1 mutation(s)

• Restore brings the store back to where it was before the rollback (the old lineage, the moved snapshots and WAL, the marks). It is possible only while nothing was committed or marked since the rollback; after that, attic_fork still keeps the rolled-back history as a new store.
• prune never removes the snapshot an attic entry is based on; remove the entry first. The attic is not part of a backup.
• Every entry stays whole, whatever you do afterwards: a later rollback to a commit before an entry's history copies the WAL that entry needs into it first (and points it at its own base snapshot; the entry's own snapshots may go then, its WAL rebuilds them), so no entry ever depends on another. Removing one never touches another. verify rebuilds every entry's history. Several rollbacks restore newest first (see Restore order).
• A rollback or restore that fails half way (a full disk, an I/O error) stops the store: it writes nothing more (commits, marks, checkpoints, prune, rollback and restore are refused with the cause stopped, and closing it writes no GRAPH) until it is closed and opened again; the open completes the operation from its INTENT (or undoes it). The reason is in store.stopped_reason(), StoreInfo::stopped and the Store menu (Store stopped).
• If the files were changed but loading the new state into the open graph fails (an I/O error, damage, out of memory, a storage refusing the data), the graph in memory is emptied, never left half-loaded: queries read an empty graph rather than plausible but incomplete data. The error (cause reload_failed) says that the reload after the rollback or restore failed, with its cause, that the graph was emptied and the store stopped, and that the files on disk are intact. Close the store and open it again (restart the dev server): the open completes the change and loads the full graph.

Restore order

After several rollbacks, attic entries restore newest first. This is a deliberate rule (by design), not a limitation to be lifted:

• An entry can be restored into the live store only while the store is on the lineage that entry's rollback started. A newer rollback starts another lineage, so the older entry becomes restorable again once the newer rollbacks are undone (restored) one by one, newest first. Each restore brings back exactly the lineage the next older entry needs.
• Any entry forks at any time (attic_fork, graphersal store attic <DIR> fork <ID> <NEW_DIR>): the history of an older entry is never out of reach, it only cannot be restored in place out of order.
• A restore out of order is refused, changes nothing, and names the newer entry to restore first:

$ graphersal store rollback data/ --at-commit 4        # entry ...-05: commits 5..=6
$ graphersal store rollback data/ --at-commit 2        # entry ...-03: commits 3..=4
$ graphersal store attic data/ restore 20261009T010700Z-00000000000000000005
Error: Cannot restore the attic entry: the store's lineage changed since that rollback (another
rollback or restore; attic entries restore newest first); restore the newer entry
20261009T010702Z-00000000000000000003 first (graphersal store attic <dir> restore
20261009T010702Z-00000000000000000003), or fork the entry instead (...)
$ graphersal store attic data/ restore 20261009T010702Z-00000000000000000003   # back at commit 4
$ graphersal store attic data/ restore 20261009T010700Z-00000000000000000005   # back at commit 6

The rule keeps restores simple and safe: a restore always puts back one whole, consistent history on top of the lineage it branched from, never a mix of lineages.

How to undo what

graphersal store rollback and store fork print these commands after they ran.

Backup and Restore

A backup is a consistent copy of the store's files, taken without any graph lock: writers go on while it copies. It holds the latest snapshot and the WAL after it, up to the last durable commit (a commit whose fsync completed). While it copies, the files are pinned against prune. Every checksum of what it copies is read in the store first and again in the copy: a backup never copies damage silently, and never leaves a copy that does not read back (see Every checksum, twice).

#![allow(unused)]
fn main() {
use graphersal::persist::{BackupMode, RecoveryTarget, Store, StoreOptions};

let store = Store::open("data", StoreOptions::new())?;
store.backup("backup")?;                          // an empty or new directory: a FULL backup
// ... commits ...
let report = store.backup("backup")?;             // the same directory again: an INCREMENT
println!("{} -> {} ({} bytes)", report.previous_commit_seq, report.commit_seq, report.bytes);
store.backup_with("weekly", BackupMode::Full)?;   // always full (the directory must be empty)

let past = Store::open_read_only("backup", RecoveryTarget::CommitSeq(3))?;  // any commit it holds
Store::restore_backup("backup")?;                 // the original is lost: continue from the backup
let live = Store::open("backup", StoreOptions::new())?;
Ok::<(), Box<dyn std::error::Error>>(())
}

graphersal store backup data/ /mnt/backup/data       # full the first time, incremental afterwards
graphersal store backup data/ /mnt/backup/data       # "nothing new since commit N" when current
graphersal store backup data/ weekly/ --full         # always full (an empty or new directory)
graphersal store backup data/ data.zip --zip         # one ZIP archive (always full)
graphersal store info /mnt/backup/data               # "backup  up to commit N, taken T"
graphersal store prune /mnt/backup/data --up-to 5000 # the backup's own retention
graphersal store restore /mnt/backup/data            # make it the live store (same graph id)
graphersal store restore data.zip restored/          # unpack a ZIP backup as the live store

$ graphersal store backup data/ backup/
Full backup into backup/: snapshot 3, the WAL up to commit 3 (1 segment(s)); 8 file(s), 9605 bytes.
The backup is read-only (graphersal --graph backup/ opens it so); `graphersal store restore backup/` makes it the live store.
$ graphersal store backup data/ backup/
Incremental backup into backup/: commits 4..4 (1 new); copied 0 snapshot(s), 0 WAL segment(s), 83 bytes appended to the last segment; 83 bytes in total.

Store::backup_dir(dir, target) (and backup_dir_with, backup_zip_dir) back up a store without opening it: a backup works while a dev server or another program has the store open.

Every checksum, twice

A backup (full, increment, ZIP) checks everything it copies in the store before it writes anything: both GRAPH copies, the marks file, the snapshot (manifest, schema.json, every segment and chunk, the files it references) and every WAL record (header and body checksum, the segment headers, commit continuity, a missing or emptied newest segment). After writing it reads the copy back the same way; a ZIP archive is read back entry by entry through the same handle (backup_zip takes Read + Write + Seek: a file opened for reading and writing, a Cursor<Vec<u8>>).

• Damage in the store stops the backup before a byte is written: PersistError::BackupDamaged with side: DamageSide::Store and the problems as verify lists them (file, byte, reason). Repair the store, never the backup: graphersal store repair <dir> --to <new_dir>. While the store is open in a process whose graph is intact (the dev server, a Python program), save that graph first with a backup from memory.
• A copy that does not read back (a bad backup disk) is side: DamageSide::Backup: a new backup directory is removed, an increment is rolled back to the backup's old state. The store is fine; check the backup's disk and back up again.
• Redundant metadata (one GRAPH copy, one copy of a manifest's fixed part, the derived marks file) is a warning (BackupReport::warnings, printed by the CLI): the backup is intact (two fresh GRAPH copies, the manifest with the intact copy in both places, marks rebuilt from the WAL it holds). Plan a repair of the store.
• In an open store, damage a backup finds is damage found while the store is open: the store's damage policy applies (by default it turns read-only).

$ graphersal store backup data/ backup/
Error: The backup stopped: the store data/ is damaged: wal/00000000000000000001.wal at byte 64: record of commit 1: checksum mismatch; nothing of the backup into backup/ was kept
Help: Repair the MAIN store, never the backup: graphersal store repair data/ --to <new_dir> (Store::repair_dir) builds a verified, repaired copy in a new directory and reports what was repaired, lost and diverged; the damaged files are never changed. The full damage report: graphersal store verify data/. Existing backups stay valid: keep them until the repaired store is backed up.

A backup from memory

When damage was found while the store is open (by a backup, a checkpoint, verify), its graph in memory is still intact: it was verified when the store was opened and changed only by commits since. store.backup_from_memory(target, mode) writes that graph into a backup directory with the streaming encoder (under the graph's read lock; commits wait meanwhile) and reads or writes nothing in the store's directory:

• one snapshot at the graph's commit, an empty WAL segment after it, GRAPH with the backup marker and the store's identity, lineage and creation parameters;
• into an empty or new directory a full backup; into a backup of the same store an increment (its snapshot is newer than everything the backup holds; a later normal increment of it needs a full backup and says so);
• the result is an ordinary backup: graphersal store restore <dir> makes it the live store (same graph id), store fork a new one. Marks are not carried (like a fork).

It is refused while no damage was found (a normal backup is the right tool and checks every checksum), for a store opened in maintenance mode (its graph was salvaged from donors: use repair_to) and for a backup opened read-only. Where: Rust Store::backup_from_memory; the dev server's Store menu (Back up from memory) and POST /api/store/backup {"from_memory": true}; Python store.backup(path, from_memory=True). The graphersal store backup command runs in a new process, so --from-memory there explains where to do it.

store = graphersal.Store.open("data")
try:
    store.backup("/mnt/backup/data")
except graphersal.GraphersalError as err:          # "the store data is damaged: ..."
    store.backup("/mnt/backup/saved", from_memory=True)

A backup is marked and read-only

A backup's GRAPH file says "a backup of graph X up to commit N, taken at T". It keeps the original's graph_id and lineage. It opens read-only: Store::open refuses it (PersistError::IsBackup), so nothing writes to it by accident.

• Store::open_backup(dir, options) is a read-only Store over it: info, listings, views at any commit it holds (read_only_at), fork, verify, export and backups of it work; every write is refused. store.backup_marker() returns the marker.
• Store::open_read_only(dir, target) loads any commit it holds.
• graphersal --graph backup/ (REPL, -e, --server) opens it read-only with a note: note: backup/ is a BACKUP (up to commit 4, taken 2026-10-08T07:05:09Z): opened READ-ONLY, writes are refused. Help: ... (the help names store restore and store fork).
• The dev server shows a "Backup: read-only" banner; its Store menu offers View and Fork only.

Restore

• In place: Store::restore_backup(dir) (graphersal store restore <BACKUP_DIR>) clears the marker: the directory becomes the live store with the same graph id. This is the case "the original is lost, continue from the backup". Stop anything that has the backup open first.
• As an independent copy that leaves the backup as it is: fork it (graphersal store fork backup/ copy/, a new graph id).
• From a ZIP (persist-zip): Store::restore_zip(reader, dir) (graphersal store restore data.zip restored/) unpacks it as the live store (unpacking is the explicit restore).

Incremental backups