# Gremlin API Reference
This document maps standard Gremlin steps (TinkerPop 3.x) to their implementations in Interstellar's Rust API and Gremlin text parser.
## Quick Start
### Rust Fluent API
```rust
use interstellar::prelude::*;
let graph = Graph::new();
// ... populate graph ...
let snapshot = graph.snapshot();
let g = snapshot.gremlin();
// Fluent API traversal
let names = g.v()
.has_label("person")
.out_labels(&["knows"])
.values("name")
.to_list();
```
### Gremlin Text Parser
```rust
use interstellar::prelude::*;
use interstellar::gremlin::ExecutionResult;
let graph = Graph::new();
// ... populate graph ...
// Execute a Gremlin query string
let result = graph.query("g.V().hasLabel('person').out('knows').values('name').toList()")?;
if let ExecutionResult::List(names) = result {
for name in names {
println!("{}", name);
}
}
```
### Lower-Level Parser API
```rust
use interstellar::gremlin::{parse, compile, ExecutionResult};
// Parse query to AST (can be reused)
let ast = parse("g.V().hasLabel('person').values('name').toList()")?;
// Compile and execute
let snapshot = graph.snapshot();
let g = snapshot.gremlin();
let compiled = compile(&ast, &g)?;
let result = compiled.execute();
```
---
## Legend
| ✓ | Implemented in both Rust API and Gremlin parser |
| Rust | Implemented in Rust API only |
| Parser | Implemented in Gremlin parser only |
| - | Not implemented |
## API Naming Differences
| `in()` | `in_()` | `in` is a Rust keyword |
| `as()` | `as_()` | `as` is a Rust keyword |
| `is()` | `is_()` | `is` is a Rust keyword |
| `where()` | `where_()` | `where` is a Rust keyword |
| `and()` | `and_()` | `and` is a Rust keyword |
| `or()` | `or_()` | `or` is a Rust keyword |
| `has(key, value)` | `has_value(key, value)` | Distinguishes from `has(key)` existence check |
---
## Source Steps
| `g.V()` | `g.v()` | `g.V()` | ✓ |
| `g.V(id)` | `g.v_by_id(id)` | `g.V(id)` | ✓ |
| `g.V(id...)` | `g.v_ids(ids)` | `g.V(id, id, ...)` | ✓ |
| `g.E()` | `g.e()` | `g.E()` | ✓ |
| `g.E(id)` | `g.e_by_id(id)` | `g.E(id)` | ✓ |
| `g.E(id...)` | `g.e_ids(ids)` | `g.E(id, id, ...)` | ✓ |
| `g.addV(label)` | `g.add_v(label)` | `g.addV('label')` | ✓ |
| `g.addE(label)` | `g.add_e(label)` | `g.addE('label')` | ✓ |
| `g.inject(values...)` | `g.inject(values)` | `g.inject(v1, v2, ...)` | ✓ |
### Full-Text Search Source Steps
Gated on the `full-text` feature. Both steps require a `Graph`-bound traversal source (the snapshot-only `g.snapshot()` path rejects them at compile time). The second argument accepts either a bare string (desugared to `TextQ.match(...)`) or a structured `TextQ.*` expression — see the [`TextQ` DSL](#textq-full-text-query-dsl) below.
| `g.searchTextV(prop, query, k)` | `g.search_text(prop, query, k)` / `g.search_text_query(prop, &q, k)` | `g.searchTextV('body', 'raft', 10)` | ✓ |
| `g.searchTextE(prop, query, k)` | `g.search_text_e(prop, query, k)` / `g.search_text_query_e(prop, &q, k)` | `g.searchTextE('note', 'hello', 5)` | ✓ |
Each source step attaches the BM25 score (`f32`) to the traverser sack; read it later via [`textScore()`](#full-text-search-transform-steps).
---
## Navigation Steps (Vertex to Vertex)
| `out()` | `out()` | `out()` | ✓ |
| `out(label...)` | `out_labels(&[labels])` | `out('label', ...)` | ✓ |
| `in()` | `in_()` | `in()` | ✓ |
| `in(label...)` | `in_labels(&[labels])` | `in('label', ...)` | ✓ |
| `both()` | `both()` | `both()` | ✓ |
| `both(label...)` | `both_labels(&[labels])` | `both('label', ...)` | ✓ |
## Navigation Steps (Vertex to Edge)
| `outE()` | `out_e()` | `outE()` | ✓ |
| `outE(label...)` | `out_e_labels(&[labels])` | `outE('label', ...)` | ✓ |
| `inE()` | `in_e()` | `inE()` | ✓ |
| `inE(label...)` | `in_e_labels(&[labels])` | `inE('label', ...)` | ✓ |
| `bothE()` | `both_e()` | `bothE()` | ✓ |
| `bothE(label...)` | `both_e_labels(&[labels])` | `bothE('label', ...)` | ✓ |
## Navigation Steps (Edge to Vertex)
| `outV()` | `out_v()` | `outV()` | ✓ |
| `inV()` | `in_v()` | `inV()` | ✓ |
| `bothV()` | `both_v()` | `bothV()` | ✓ |
| `otherV()` | `other_v()` | `otherV()` | ✓ |
---
## Filter Steps
| `has(key)` | `has(key)` | `has('key')` | ✓ |
| `has(key, value)` | `has_value(key, value)` | `has('key', value)` | ✓ |
| `has(key, predicate)` | `has_where(key, predicate)` | `has('key', P.gt(x))` | ✓ |
| `has(label, key, value)` | `has_label(...).has_value(...)` | `has('label', 'key', value)` | ✓ |
| `hasLabel(label)` | `has_label(label)` | `hasLabel('label')` | ✓ |
| `hasLabel(label...)` | `has_label_any(&[labels])` | `hasLabel('l1', 'l2')` | ✓ |
| `hasId(id)` | `has_id(id)` | `hasId(id)` | ✓ |
| `hasId(id...)` | `has_ids(&[ids])` | `hasId(id1, id2)` | ✓ |
| `hasNot(key)` | `has_not(key)` | `hasNot('key')` | ✓ |
| `hasKey(key)` | `has_key(key)` | `hasKey('key')` | ✓ |
| `hasKey(key...)` | `has_key_any(&[keys])` | `hasKey('k1', 'k2')` | ✓ |
| `hasValue(value)` | `has_prop_value(value)` | `hasValue(value)` | ✓ |
| `hasValue(value...)` | `has_prop_value_any(&[values])` | `hasValue(v1, v2)` | ✓ |
| `filter(traversal)` | `filter(closure)` | - | Rust |
| `where(traversal)` | `where_(traversal)` | `where(__.out())` | ✓ |
| `where(predicate)` | `where_p(predicate)` | `where(P.gt(x))` | ✓ |
| `not(traversal)` | `not(traversal)` | `not(__.out())` | ✓ |
| `and(traversal...)` | `and_(&[traversals])` | `and(__.t1(), __.t2())` | ✓ |
| `or(traversal...)` | `or_(&[traversals])` | `or(__.t1(), __.t2())` | ✓ |
| `is(value)` | `is_eq(value)` | `is(value)` | ✓ |
| `is(predicate)` | `is_(predicate)` | `is(P.gt(x))` | ✓ |
| `dedup()` | `dedup()` | `dedup()` | ✓ |
| `dedup().by(key)` | `dedup_by_key(key)` | - | Rust |
| `dedup().by(label)` | `dedup_by_label()` | - | Rust |
| `dedup().by(traversal)` | `dedup_by(traversal)` | - | Rust |
| `limit(n)` | `limit(n)` | `limit(n)` | ✓ |
| `skip(n)` | `skip(n)` | `skip(n)` | ✓ |
| `range(start, end)` | `range(start, end)` | `range(start, end)` | ✓ |
| `tail()` | `tail()` | `tail()` | ✓ |
| `tail(n)` | `tail_n(n)` | `tail(n)` | ✓ |
| `coin(probability)` | `coin(probability)` | `coin(0.5)` | ✓ |
| `sample(n)` | `sample(n)` | `sample(n)` | ✓ |
| `simplePath()` | `simple_path()` | `simplePath()` | ✓ |
| `cyclicPath()` | `cyclic_path()` | `cyclicPath()` | ✓ |
| `timeLimit()` | - | - | - |
---
## Transform / Map Steps
| `map(traversal)` | `map(closure)` | - | Rust |
| `flatMap(traversal)` | `flat_map(closure)` | - | Rust |
| `identity()` | `identity()` | `identity()` | ✓ |
| `constant(value)` | `constant(value)` | `constant(value)` | ✓ |
| `id()` | `id()` | `id()` | ✓ |
| `label()` | `label()` | `label()` | ✓ |
| `properties()` | `properties()` | `properties()` | ✓ |
| `properties(key...)` | `properties_keys(&[keys])` | `properties('k1', 'k2')` | ✓ |
| `values(key)` | `values(key)` | `values('key')` | ✓ |
| `values(key...)` | `values_multi(&[keys])` | `values('k1', 'k2')` | ✓ |
| `propertyMap()` | `property_map()` | - | Rust |
| `propertyMap(key...)` | `property_map_keys(&[keys])` | - | Rust |
| `valueMap()` | `value_map()` | `valueMap()` | ✓ |
| `valueMap(key...)` | `value_map_keys(&[keys])` | `valueMap('k1', 'k2')` | ✓ |
| `valueMap(true)` | `value_map_with_tokens()` | `valueMap(true)` | ✓ |
| `elementMap()` | `element_map()` | `elementMap()` | ✓ |
| `elementMap(key...)` | `element_map_keys(&[keys])` | `elementMap('k1')` | ✓ |
| `key()` | `key()` | `key()` | ✓ |
| `value()` | `value()` | `value()` | ✓ |
| `path()` | `path()` | `path()` | ✓ |
| `select(labels...)` | `select(&[labels])` | `select('a', 'b')` | ✓ |
| `select(label)` | `select_one(label)` | `select('a')` | ✓ |
| `project(keys...).by()` | `project(&[keys]).by().build()` | `project('a', 'b').by(...)` | ✓ |
| `unfold()` | `unfold()` | `unfold()` | ✓ |
| `fold()` | `fold()` | `fold()` | ✓ |
| `count()` | `count()` | `count()` | ✓ |
| `sum()` | `sum()` | `sum()` | ✓ |
| `max()` | `max()` | `max()` | ✓ |
| `min()` | `min()` | `min()` | ✓ |
| `mean()` | `mean()` | `mean()` | ✓ |
| `order()` | `order().build()` | `order()` | ✓ |
| `order().by(key)` | `order().by_key_asc(key).build()` | `order().by('key')` | ✓ |
| `order().by(key, desc)` | `order().by_key_desc(key).build()` | `order().by('key', desc)` | ✓ |
| `order().by(traversal)` | `order().by_traversal(t).build()` | `order().by(__.out())` | ✓ |
| `math(expression)` | `math(expr).build()` | - | Rust |
| `index()` | `index()` | `index()` | ✓ |
| `loops()` | `loops()` | `loops()` | ✓ |
### Full-Text Search Transform Steps
Gated on the `full-text` feature.
| `textScore()` | `text_score()` | `textScore()` | ✓ |
`textScore()` reads the `f32` BM25 score the upstream `searchTextV` / `searchTextE` source step attached to the traverser sack and emits it as `Value::Float`. If a traverser arrives without a sack (e.g. it came from a non-FTS source), the step emits `Value::Null` rather than aborting the pipeline.
---
## Aggregation Steps
| `group()` | `group().by_*().build()` | - | Rust |
| `group().by(key)` | `group().by_key(key).build()` | - | Rust |
| `group().by(label)` | `group().by_label().build()` | - | Rust |
| `groupCount()` | `group_count().by_*().build()` | - | Rust |
| `groupCount().by(key)` | `group_count().by_key(key).build()` | - | Rust |
| `groupCount().by(label)` | `group_count().by_label().build()` | - | Rust |
---
## Branch Steps
| `branch(traversal)` | `branch(traversal).option()` | - | Rust |
| `choose(cond, true, false)` | `choose(cond, if_true, if_false)` | `choose(__.cond(), __.t(), __.f())` | ✓ |
| `choose(traversal).option()` | `choose_by(t).option()` | - | Rust |
| `union(traversal...)` | `union(&[traversals])` | `union(__.t1(), __.t2())` | ✓ |
| `coalesce(traversal...)` | `coalesce(&[traversals])` | `coalesce(__.t1(), __.t2())` | ✓ |
| `optional(traversal)` | `optional(traversal)` | `optional(__.out())` | ✓ |
| `local(traversal)` | `local(traversal)` | `local(__.out())` | ✓ |
---
## Repeat Steps
| `repeat(traversal)` | `repeat(traversal)` | `repeat(__.out())` | ✓ |
| `repeat().times(n)` | `repeat().times(n)` | `repeat(__.out()).times(n)` | ✓ |
| `repeat().until(traversal)` | `repeat().until(traversal)` | `repeat(__.out()).until(__.t())` | ✓ |
| `repeat().emit()` | `repeat().emit()` | `repeat(__.out()).emit()` | ✓ |
| `repeat().emit(traversal)` | `repeat().emit_if(traversal)` | `repeat(__.out()).emit(__.t())` | ✓ |
| `repeat().emit()` (first) | `repeat().emit_first()` | - | Rust |
| `loops()` | `loops()` | `loops()` | ✓ |
---
## Side Effect Steps
| `sideEffect(traversal)` | `side_effect(traversal)` | `sideEffect(__.t())` | ✓ |
| `aggregate(key)` | `aggregate(key)` | `aggregate('key')` | ✓ |
| `store(key)` | `store(key)` | `store('key')` | ✓ |
| `cap(key)` | `cap(key)` | `cap('key')` | ✓ |
| `cap(key...)` | `cap_multi(&[keys])` | `cap('k1', 'k2')` | ✓ |
| `subgraph()` | - | - | - |
| `profile()` | `profile()` | - | Rust |
---
## Mutation Steps
| `addV(label)` | `add_v(label)` | `addV('label')` | ✓ |
| `addE(label)` | `add_e(label)` | `addE('label')` | ✓ |
| `property(key, value)` | `property(key, value)` | `property('key', value)` | ✓ |
| `property(cardinality, k, v)` | `property_with_cardinality(...)` | `property(single, 'k', v)` | ✓ |
| `from(vertex)` | `from_vertex(id)` | `from(__.V(id))` | ✓ |
| `from(label)` | `from_label(label)` | `from('label')` | ✓ |
| `to(vertex)` | `to_vertex(id)` | `to(__.V(id))` | ✓ |
| `to(label)` | `to_label(label)` | `to('label')` | ✓ |
| `drop()` | `drop()` | `drop()` | ✓ |
| `mergeV()` | - | - | - |
| `mergeE()` | - | - | - |
---
## Modulator Steps
| `as(label)` | `as_(label)` | `as('label')` | ✓ |
| `by()` | `.by_*()` methods | `.by(...)` | ✓ |
| `with()` | - | `with('key', value)` | Parser |
| `option(key, traversal)` | `.option(key, traversal)` | - | Rust |
| `option(none)` | `.option_none(traversal)` | - | Rust |
| - | `with_path()` | - | Rust |
---
## Terminal Steps
| `next()` | `next()` | `next()` | ✓ |
| `next(n)` | `take(n)` | `next(n)` | ✓ |
| `toList()` | `to_list()` | `toList()` | ✓ |
| `toSet()` | `to_set()` | `toSet()` | ✓ |
| `toBulkSet()` | - | - | - |
| `iterate()` | `iterate()` | `iterate()` | ✓ |
| `hasNext()` | `has_next()` | `hasNext()` | ✓ |
| `tryNext()` | - | - | - |
| `one()` | `one()` | - | Rust |
| `explain()` | - | - | - |
| - | `iter()` | - | Rust |
| - | `traversers()` | - | Rust |
| - | `to_vertex_list()` | - | Rust |
| - | `next_vertex()` | - | Rust |
| - | `to_edge_list()` | - | Rust |
| - | `next_edge()` | - | Rust |
---
## Predicate Functions (P.)
| `P.eq(value)` | `p::eq(value)` | `P.eq(value)` | ✓ |
| `P.neq(value)` | `p::neq(value)` | `P.neq(value)` | ✓ |
| `P.lt(value)` | `p::lt(value)` | `P.lt(value)` | ✓ |
| `P.lte(value)` | `p::lte(value)` | `P.lte(value)` | ✓ |
| `P.gt(value)` | `p::gt(value)` | `P.gt(value)` | ✓ |
| `P.gte(value)` | `p::gte(value)` | `P.gte(value)` | ✓ |
| `P.between(start, end)` | `p::between(start, end)` | `P.between(s, e)` | ✓ |
| `P.inside(start, end)` | `p::inside(start, end)` | `P.inside(s, e)` | ✓ |
| `P.outside(start, end)` | `p::outside(start, end)` | `P.outside(s, e)` | ✓ |
| `P.within(values...)` | `p::within(&[values])` | `P.within(v1, v2)` | ✓ |
| `P.without(values...)` | `p::without(&[values])` | `P.without(v1, v2)` | ✓ |
| `P.and(p1, p2)` | `p::and(p1, p2)` | `P.gt(x).and(P.lt(y))` | ✓ |
| `P.or(p1, p2)` | `p::or(p1, p2)` | `P.lt(x).or(P.gt(y))` | ✓ |
| `P.not(predicate)` | `p::not(predicate)` | `P.not(P.eq(x))` | ✓ |
## Text Predicates (TextP.)
| `TextP.containing(str)` | `p::containing(str)` | `TextP.containing('str')` | ✓ |
| `TextP.startingWith(str)` | `p::starting_with(str)` | `TextP.startingWith('str')` | ✓ |
| `TextP.endingWith(str)` | `p::ending_with(str)` | `TextP.endingWith('str')` | ✓ |
| `TextP.notContaining(str)` | `p::not_containing(str)` | `TextP.notContaining('str')` | ✓ |
| `TextP.notStartingWith(str)` | `p::not_starting_with(str)` | `TextP.notStartingWith('str')` | ✓ |
| `TextP.notEndingWith(str)` | `p::not_ending_with(str)` | `TextP.notEndingWith('str')` | ✓ |
| `TextP.regex(pattern)` | `p::regex(pattern)` | `TextP.regex('pattern')` | ✓ |
---
## TextQ (Full-Text Query DSL)
Gated on the `full-text` feature. `TextQ.*` expressions are only valid as the second argument of `g.searchTextV(...)` / `g.searchTextE(...)`. A bare string in that position desugars to `TextQ.match(...)`.
| `TextQ.match('foo bar')` | `Match(..)` | any term matches (OR) |
| `TextQ.matchAll('foo bar')` | `MatchAll(..)` | all terms must match (AND) |
| `TextQ.phrase('foo bar')` | `Phrase { slop: 0, .. }` | exact adjacent phrase |
| `TextQ.prefix('foo')` | `Prefix(..)` | prefix expansion |
| `TextQ.and(q1, q2, ...)` | `And(..)` | boolean AND of subqueries |
| `TextQ.or(q1, q2, ...)` | `Or(..)` | boolean OR of subqueries |
| `TextQ.not(q)` | `Not(..)` | boolean negation |
Compound forms nest freely:
```text
g.searchTextV('body',
TextQ.and(
TextQ.match('raft'),
TextQ.or(TextQ.prefix('paxos'), TextQ.not(TextQ.phrase('byzantine fault')))
),
20
).textScore()
```
GQL does **not** expose `And/Or/Not`; use Gremlin or the Rust API for compound queries.
---
## Anonymous Traversal Factory (__)
The anonymous traversal factory `__` creates traversal fragments for use in steps like `where()`, `choose()`, `repeat()`, etc.
| `__.identity()` | `__.identity()` | `__.identity()` | ✓ |
| `__.out()` | `__.out()` | `__.out()` | ✓ |
| `__.out(label)` | `__.out_labels(&[label])` | `__.out('label')` | ✓ |
| `__.in()` | `__.in_()` | `__.in()` | ✓ |
| `__.in(label)` | `__.in_labels(&[label])` | `__.in('label')` | ✓ |
| `__.both()` | `__.both()` | `__.both()` | ✓ |
| `__.outE()` | `__.out_e()` | `__.outE()` | ✓ |
| `__.inE()` | `__.in_e()` | `__.inE()` | ✓ |
| `__.bothE()` | `__.both_e()` | `__.bothE()` | ✓ |
| `__.outV()` | `__.out_v()` | `__.outV()` | ✓ |
| `__.inV()` | `__.in_v()` | `__.inV()` | ✓ |
| `__.otherV()` | `__.other_v()` | `__.otherV()` | ✓ |
| `__.bothV()` | `__.both_v()` | `__.bothV()` | ✓ |
| `__.hasLabel(label)` | `__.has_label(label)` | `__.hasLabel('label')` | ✓ |
| `__.has(key)` | `__.has(key)` | `__.has('key')` | ✓ |
| `__.hasNot(key)` | `__.has_not(key)` | `__.hasNot('key')` | ✓ |
| `__.has(key, value)` | `__.has_value(key, value)` | `__.has('key', value)` | ✓ |
| `__.dedup()` | `__.dedup()` | `__.dedup()` | ✓ |
| `__.limit(n)` | `__.limit(n)` | `__.limit(n)` | ✓ |
| `__.skip(n)` | `__.skip(n)` | `__.skip(n)` | ✓ |
| `__.range(s, e)` | `__.range(s, e)` | `__.range(s, e)` | ✓ |
| `__.id()` | `__.id()` | `__.id()` | ✓ |
| `__.label()` | `__.label()` | `__.label()` | ✓ |
| `__.values(key)` | `__.values(key)` | `__.values('key')` | ✓ |
| `__.valueMap()` | `__.value_map()` | `__.valueMap()` | ✓ |
| `__.path()` | `__.path()` | `__.path()` | ✓ |
| `__.constant(value)` | `__.constant(value)` | `__.constant(value)` | ✓ |
| `__.fold()` | `__.fold()` | `__.fold()` | ✓ |
| `__.unfold()` | `__.unfold()` | `__.unfold()` | ✓ |
| `__.count()` | `__.count()` | `__.count()` | ✓ |
| `__.sum()` | `__.sum()` | `__.sum()` | ✓ |
| `__.as(label)` | `__.as_(label)` | `__.as('label')` | ✓ |
### Additional Rust-only Anonymous Functions
These are available in Rust via `__.` but not yet in the Gremlin parser:
- **Filter:** `has_label_any`, `has_id`, `has_ids`, `has_key`, `has_key_any`, `has_prop_value`, `has_prop_value_any`, `is_`, `is_eq`, `filter`, `tail`, `tail_n`, `coin`, `sample`, `simple_path`, `cyclic_path`, `dedup_by_key`, `dedup_by_label`, `dedup_by`
- **Transform:** `values_multi`, `properties`, `properties_keys`, `value_map_keys`, `value_map_with_tokens`, `element_map`, `element_map_keys`, `property_map`, `property_map_keys`, `key`, `value`, `index`, `loops`, `mean`, `order`, `math`, `project`, `map`, `flat_map`
- **Aggregation:** `group`, `group_count`
- **Side Effect:** `select`, `select_one`, `store`, `aggregate`, `cap`, `side_effect`, `profile`
- **Branch:** `where_`, `where_p`, `not`, `and_`, `or_`, `union`, `coalesce`, `choose`, `optional`, `local`, `branch`
- **Mutation:** `add_v`, `add_e`, `property`, `drop`
---
## Convenience Methods
### Graph::query()
Execute a Gremlin query string directly on a Graph:
```rust
let result = graph.query("g.V().hasLabel('person').values('name').toList()")?;
```
This takes an internal snapshot, so it provides a consistent view at call time.
### GraphSnapshot::query()
Execute a Gremlin query string on a snapshot:
```rust
let snapshot = graph.snapshot();
let result = snapshot.query("g.V().out('knows').values('name').toList()")?;
```
### Graph::mutate()
Execute a Gremlin mutation query that actually modifies the graph:
```rust
// Create vertices
graph.mutate("g.addV('person').property('name', 'Alice')")?;
graph.mutate("g.addV('person').property('name', 'Bob')")?;
// Get vertex IDs for edge creation
let alice_id = 0; // First vertex
let bob_id = 1; // Second vertex
// Create an edge between them
graph.mutate(&format!("g.addE('knows').from({}).to({}).property('since', 2020)", alice_id, bob_id))?;
// Update a property on an existing vertex
graph.mutate(&format!("g.V({}).property('age', 30)", alice_id))?;
// Delete elements
graph.mutate(&format!("g.V({}).drop()", bob_id))?;
```
**Important:** Use `mutate()` instead of `query()` when you need mutations to actually execute:
- `query()` returns mutation placeholders but doesn't modify the graph
- `mutate()` executes pending mutations and modifies the graph
### ExecutionResult
Query results are returned as an `ExecutionResult` enum:
```rust
pub enum ExecutionResult {
List(Vec<Value>), // toList()
Single(Option<Value>), // next()
Set(HashSet<Value>), // toSet()
Bool(bool), // hasNext()
Unit, // iterate()
}
```
---
## Algorithm Steps
Algorithm steps perform graph traversals and pathfinding starting from the current vertex. They are available both as fluent Rust API methods and in the Gremlin text parser.
See the [Algorithms Guide](../guides/algorithms.md) for detailed usage, common types, and when to use each algorithm.
### Shortest Path (Unweighted)
BFS-based shortest path returning a list of vertex IDs.
| `shortestPath(targetId)` | `shortest_path_to(target)` | `shortestPath(id)` | ✓ |
```rust
// Rust fluent API
let path = g.v_ids([source]).shortest_path_to(target).next();
// Gremlin script
graph.query("g.V(1).shortestPath(4).next()")?;
```
### Dijkstra (Weighted Shortest Path)
Weighted shortest path using the `by()` modulator to specify the weight property. Returns a map with `"path"` and `"weight"`.
| `shortestPath(targetId).by('weight')` | `dijkstra_to(target, "weight")` | `shortestPath(id).by('prop')` | ✓ |
```rust
// Rust fluent API
let result = g.v_ids([source]).dijkstra_to(target, "distance").next();
// Gremlin script
graph.query("g.V(1).shortestPath(4).by('distance').next()")?;
```
### A* (Heuristic Shortest Path)
A\* pathfinding using `by()` for the weight property and `with('heuristic', 'prop')` for the heuristic vertex property. The heuristic property should contain pre-computed estimated distances to the target. Missing property defaults to 0.0 (Dijkstra behavior). Returns a map with `"path"` and `"weight"`.
| `shortestPath(id).by('w').with('heuristic', 'h')` | `astar_to(target, "w", "h")` | `shortestPath(id).by('w').with('heuristic', 'h')` | ✓ |
```rust
// Rust fluent API
let result = g.v_ids([source]).astar_to(target, "distance", "est_dist").next();
// Gremlin script
graph.query("g.V(1).shortestPath(4).by('distance').with('heuristic', 'est_dist').next()")?;
```
### K-Shortest Paths
Yen's k-shortest loopless paths. The `by()` modulator specifies the weight property. Returns a list of maps, each with `"path"` and `"weight"`.
| `kShortestPaths(targetId, k).by('w')` | `k_shortest_paths_to(target, k, "w")` | `kShortestPaths(id, k).by('prop')` | ✓ |
```rust
// Rust fluent API
let paths = g.v_ids([source]).k_shortest_paths_to(target, 3, "distance").to_list();
// Gremlin script
graph.query("g.V(1).kShortestPaths(4, 3).by('distance').toList()")?;
```
### BFS Traversal
Breadth-first traversal yielding maps with `"vertex"` and `"depth"` for each reachable vertex. Supports `with('maxDepth', n)` and `with('edgeLabels', [...])` modulators.
| `bfs()` | `bfs_traversal(None, None)` | `bfs()` | ✓ |
| `bfs().with('maxDepth', n)` | `bfs_traversal(Some(n), None)` | `bfs().with('maxDepth', n)` | ✓ |
| `bfs().with('edgeLabels', [...])` | `bfs_traversal(None, Some(labels))` | `bfs().with('edgeLabels', ['l1'])` | ✓ |
```rust
// Rust fluent API
let results = g.v_ids([source]).bfs_traversal(Some(3), None).to_list();
// Gremlin script
graph.query("g.V(1).bfs().with('maxDepth', 3).toList()")?;
```
### DFS Traversal
Depth-first traversal yielding maps with `"vertex"` and `"depth"`. Same modulators as BFS.
| `dfs()` | `dfs_traversal(None, None)` | `dfs()` | ✓ |
| `dfs().with('maxDepth', n)` | `dfs_traversal(Some(n), None)` | `dfs().with('maxDepth', n)` | ✓ |
| `dfs().with('edgeLabels', [...])` | `dfs_traversal(None, Some(labels))` | `dfs().with('edgeLabels', ['l1'])` | ✓ |
```rust
// Rust fluent API
let results = g.v_ids([source]).dfs_traversal(Some(5), None).to_list();
// Gremlin script
graph.query("g.V(1).dfs().with('maxDepth', 5).toList()")?;
```
### Bidirectional BFS
Expands frontiers from both source and target simultaneously. Returns a list of vertex IDs.
| `bidirectionalBfs(targetId)` | `bidirectional_bfs_to(target)` | `bidirectionalBfs(id)` | ✓ |
```rust
// Rust fluent API
let path = g.v_ids([source]).bidirectional_bfs_to(target).next();
// Gremlin script
graph.query("g.V(1).bidirectionalBfs(4).next()")?;
```
### IDDFS (Iterative Deepening DFS)
Combines DFS space efficiency with BFS shortest-path optimality. Returns a list of vertex IDs.
| `iddfs(targetId, maxDepth)` | `iddfs_to(target, max_depth)` | `iddfs(id, depth)` | ✓ |
```rust
// Rust fluent API
let path = g.v_ids([source]).iddfs_to(target, 10).next();
// Gremlin script
graph.query("g.V(1).iddfs(4, 10).next()")?;
```
---
## Unsupported Gremlin Features
| `subgraph()` | Complex graph construction |
| `tree()` | Specialized data structure |
| `sack()` / `withSack()` | Requires stateful traverser |
| `barrier()` | Explicit synchronization (implicit in reduce steps) |
| `match()` | Complex pattern matching |
| `program()` | VertexProgram execution |
| `io()` | Graph I/O (use native import/export) |
| `call()` | Procedure calls |
| `tx()` | Transaction management (handled at storage level) |
| Lambda steps | Security/portability concerns |
---
## Implementation Summary
| Source Steps | 9 | 9 | 9 |
| Navigation (V→V) | 6 | 6 | 6 |
| Navigation (V→E) | 6 | 6 | 6 |
| Navigation (E→V) | 4 | 4 | 4 |
| Filter Steps | ~30 | ~34 | ~25 |
| Transform/Map Steps | ~30 | ~32 | ~28 |
| Algorithm Steps | 8 | 8 | 8 |
| Aggregation Steps | 6 | 6 | 0 |
| Branch Steps | 7 | 8 | 5 |
| Repeat Steps | 6 | 7 | 6 |
| Side Effect Steps | 6 | 7 | 5 |
| Mutation Steps | 10 | 10 | 9 |
| Modulator Steps | 5 | 6 | 3 |
| Terminal Steps | 8 | 15 | 6 |
| Predicates (P.) | 14 | 14 | 14 |
| Text Predicates | 7 | 7 | 7 |
| Anonymous Factory | ~30 | 50+ | ~30 |
**Total Parser Coverage:** ~85% of common Gremlin operations