Skip to content


Subversion checkout URL

You can clone with
Download ZIP

Gremlin Steps

okram edited this page · 131 revisions

Gremlin comes with a collection of predefined steps. Gremlin steps map to a particular Pipe in Pipes. A Pipe<S,E> extends Iterator<E> and Iterable<E>. It takes an object of type S and emits and object of type E. Chaining pipes together creates a Pipeline. In essence, Gremlin is a DSL for constructing Pipeline objects. Finally, be sure to look at User Defined Steps to learn how to define your own custom steps.

Step Library

Even link in a pipeline is called a step. Steps can be categorized as either being transform-, filter-, sideEffect-, or branch- based.

  • step: a generic, general-purpose computational step.
    • transform: take an object and emit a transformation of it.
    • filter: decide whether to allow an object to pass or not.
    • sideEffect: pass the object, but yield some side effect.
    • branch: decide which step to take.


step description pipe
step{closure} an anonymous/lambda step defined by a closure FunctionPipe(closure)

Transform-Based Steps

step description pipe
transform{closure} emit the result of the closure TransformFunctionPipe(closure)
_ emit the incoming object unchanged IdentityPipe()
V the vertex iterator of the graph VerticesPipe()
E the edge iterator of the graph EdgesPipe()
id the identifier of the element IdPipe()
label the label of the edge LabelPipe()
out(labels...?) out adjacent vertices to the vertex OutPipe(labels...?)
outE(labels...?) the outgoing edges of the vertex OutEdgesPipe(labels...?)
in(labels...?) in adjacent vertices to the vertex InPipe(labels...?)
inE(labels...?) the incoming edges of the vertex InEdgesPipe(labels...?)
both(labels...?) both adjacent vertices of the vertex BothPipe(labels...?)
bothE(labels...?) both incoming and outgoing edges of the vertex BothEdgesPipe(labels...?)
outV the outgoing tail vertex of the edge OutVertexPipe()
inV the incoming head vertex of the edge InVertexPipe()
bothV both incoming and outgoing vertices of the edge BothVerticesPipe()
['key'] get the property value of an element PropertyPipe('key')
key get the property value of an element PropertyPipe(key)
map get the property map of an element PropertyMapPipe()
memoize(string, map?) memoize a named section with optional map being a cache MemoizePipe()
memoize(integer, map?) memoize n-steps ago with optional map being a cache MemoizePipe()
gather{closure?} collect all objects up to that step and process with provided closure GatherPipe() and TransformFunctionPipe(closure)
scatter unroll all objects in the iterable at that step ScatterPipe()
paths(closures..?) the path through the pipeline up to this point, where closures are post-processing for each object in the path PathPipe() or PathFunctionPipe(closures...?)
cap emits the side effect of the pipe prior SideEffectCapPipe(pipe)
select(list?,closures..?) select the named steps to emit after select with post-processing closures SelectPipe(list?, closures..?)
  • The paths step is called paths in Groovy, but called path in the other JVM implementations. This is due to Groovy not requiring get when a getXXX() method is called and getPath() is a method of Pipeline.

Filter-Based Steps

step description pipe
filter{closure} return true to allow the object to pass FilterFunctionPipe(closure)
[i] emit the particular indexed object RangeFilterPipe(i,i)
[i..j] emit the objects indexed by the range RangeFilterPipe(i,j)
has('key',value) allow element if has property PropertyFilterPipe('key',value,Filter.EQUALS)
has('key',T,value) allow element if property is T related to value PropertyFilterPipe('key',value,T)
hasNot('key',value) filter element if has property PropertyFilterPipe('key',value,Filter.NOT_EQUALS)
hasNot('key',T,value) filter element if property is not T related to value PropertyFilterPipe('key',value,!T)
back(integer) go back to the results from n-steps ago BackFilterPipe(Pipe())
back(string) go back to the results as the named step BackFilterPipe(Pipe())
and(pipes...) emit the incoming object if all pipes emit results AndFilterPipe(pipes...)
or(pipes...) emit the incoming object if any pipe emit results OrFilterPipe(pipes...)
random(double) emit the incoming object if biased coin toss is heads RandomFilterPipe(double)
dedup(closure?) emit only incoming objects that have not been seen before with optional closure being object to check on DuplicateFilterPipe(closure?)
simplePath emit the object only if the current path has no repeated elements CyclicPathFilterPipe()
except(collection) allow everything to pass except what is in collection ExceptFilterPipe(collection)
retain(collection) allow everything to pass except what is not in collection RetainFilterPipe(collection)

SideEffect-Based Steps

step description pipe
sideEffect{closure} emits input, but calls a side effect closure on each input SideEffectFunctionPipe(closure)
groupBy(map?){closure}{closure} emits input, but groups input after processing it by provided key-closure and value-closure GroupByPipe(map?, closure, closure)
groupCount(map?){closure?}{closure?} emits input, but updates a map for each input, where closures provides generic map update GroupCountFunctionPipe(map?,closure?,closure?)
aggregate(collection?,closure?) emits input, but adds input in collection, where provided closure processes input prior to insertion (greedy) AggregatePipe(collection?,closure?)
table(table?,strings..?,closures..?) emits input, but stores row of as values (constrained by column names if provided) TablePipe(table?,strings..?,closures..?)
tree(map?, closures..?) emit input, but stores the tree formed by the traversal as a map TreePipe(map?, closures..?)
as(string) emits input, but names the previous step AsPipe(string, Pipe())
optional(integer) go back to the results from n-steps ago OptionalPipe(Pipe())
optional(string) go back to the results as the named step OptionalPipe(Pipe())
store(collection?,closure?) emits input, but adds input to collection, where provided closure processes input prior to insertion (lazy) StorePipe(collection?, closure?)

Branch-Based Steps

step description pipe
loop(integer){whileClosure}{emitClosure?} if whileClosure true for emitted object, put object back at start (emit object mid-loop if emitClosure is true) LoopPipe(Pipe(),whileC,emitC?)
loop(string){whileClosure}{emitClosure?} if whileClosure true for emitted object, put object back at start (emit object mid-loop if emitClosure is true) LoopPipe(Pipe(),whileC,emitC?)
ifThenElse{ifClosure}{thenClosure}{elseClosure} if/then/else branch IfThenElsePipe(ifC,thenC,elseC)
copySplit(pipes...) copies incoming object to internal pipes CopySplitPipe(pipes...)
fairMerge round-robin merges internal pipe objects FairMergePipe()
exhaustMerge exhaustively merges internal pipe objects ExhaustMergePipe()


  • If a pipe’s argument is postfixed with a ?, then the argument is optional. When no argument is provided, a reasonable default argument is created.
  • If you come up a with a generally useful step/pipe and would like to include it into the main Gremlin distribution, please make an issue or provide the appropriate pull request.
Something went wrong with that request. Please try again.