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.