# tinkerpop/gremlin

### Subversion checkout URL

You can clone with
or
.

# Loop Pattern

##### Clone this wiki locally

Looping is essential for traversing to an arbitrary depth. The `loop` step allows you to loop over a particular set of steps in the pipeline. For the examples to follow, the Grateful Dead graph discussed in Defining a More Complex Property Graph is used. Most of the examples in this section make use of `GremlinPipeline.optimize(boolean)`. Please refer to Traversal Optimization for the rationale behind this method.

``````gremlin> g = new TinkerGraph()
==>tinkergraph[vertices:0 edges:0]
==>null``````

You can create an explicit pipeline to walk a particular path through the graph (`outE.inV`).

``````gremlin> g.v(89).outE.inV.path
==>[v[89], e[7021][89-followed_by->83], v[83]]
==>[v[89], e[7022][89-followed_by->21], v[21]]
==>[v[89], e[7023][89-followed_by->206], v[206]]
==>[v[89], e[7006][89-followed_by->127], v[127]]
...``````

You can also loop for an arbitrary depth (i.e. any arbitrary number of loops through the looped section of the pipeline). In the example below, the `loop` step is used. The single integer argument to `loop` states how many steps back to loop over (i.e. `outE.inV`). The provided closure says to continue to loop while the number of loops that have occurred is less than 3. Thus, what is emitted from `loop` is the vertices 2 steps away from vertex 89 (Dark Star). Finally, the `path` step is used to emit the paths of length 2 emanating from vertex 89.

``````gremlin> g.v(89).outE.inV.loop(2){it.loops < 3}.path
==>[v[89], e[7021][89-followed_by->83], v[83], e[1437][83-followed_by->29], v[29]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1411][83-followed_by->13], v[13]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1436][83-followed_by->14], v[14]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1410][83-followed_by->12], v[12]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1435][83-followed_by->36], v[36]]
...``````

Feel free to use `as` to label the loop point.

``````gremlin> g.v(89).as('x').outE.inV.loop('x'){it.loops < 3}.path
==>[v[89], e[7021][89-followed_by->83], v[83], e[1437][83-followed_by->29], v[29]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1411][83-followed_by->13], v[13]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1436][83-followed_by->14], v[14]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1410][83-followed_by->12], v[12]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1435][83-followed_by->36], v[36]]
...``````

Note the the expression above is equivalent to the “unrolled” version below.

``````gremlin> g.v(89).outE.inV.outE.inV.path
==>[v[89], e[7021][89-followed_by->83], v[83], e[1437][83-followed_by->29], v[29]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1411][83-followed_by->13], v[13]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1436][83-followed_by->14], v[14]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1410][83-followed_by->12], v[12]]
==>[v[89], e[7021][89-followed_by->83], v[83], e[1435][83-followed_by->36], v[36]]
...``````

In fact:

``````gremlin> g.v(89).outE.inV.loop(2){it.loops < 3} == g.v(89).outE.inV.outE.inV
==>true``````

## Loop Bundles and their Metadata

The `it` component of the `loop` step closure has three properties that are accessible. These properties can be used to reason about when to break out of the loop.

1. `it.object`: the current object of the traverser.
2. `it.path`: the current path of the traverser.
3. `it.loops`: the number of times the traverser has looped through the loop section.

NOTE: If you are using `it.path` in the while/emit closure, be sure that the pipeline has had its path functionality enabled.

``````gremlin> g.v(89).out.loop(1){it.loops < 3}{it.path.contains(g.v(12))}
Cannot invoke method contains() on null object
Display stack trace? [yN]
gremlin> g.v(89).out.loop(1){it.loops < 3}{it.path.contains(g.v(12))}.enablePath
==>v[19]
==>v[27]
==>v[130]
==>v[49]
==>v[252]
...``````

## Using an Emit Closure

The `loop` step can be updated with a second closure called the “emit closure.” This boolean-based closure will determine wether the current object in the loop structure is emitted or not. As such, it is possible to emit intermediate objects, not simply those at the end of the loop.

``````gremlin> g.v(89).out.loop(1){it.loops < 4}.count()
==>70307
gremlin> g.v(89).out.loop(1){it.loops < 4}{true}.count()
==>71972
gremlin> g.v(89).out.loop(1){it.loops < 4}{it.object.id == '89'}.count()
==>582``````

Finally, use `toString()` to see how `loop` wraps a section of the pipeline.

``````gremlin> println g.v(89).outE.inV.path
[StartPipe, QueryPipe(out,[],has:false,interval:false,edge), InVertexPipe, PathPipe]
==>null
gremlin> println g.v(89).outE.inV.loop(2){it.loops < 3}.path
[StartPipe, LoopPipe([QueryPipe(out,[],has:false,interval:false,edge), InVertexPipe]), PathPipe]
==>null
gremlin> println g.v(89).out.loop(1){it.loops < 3}.path
[StartPipe, LoopPipe([OutPipe]), PathPipe]
==>null``````
Something went wrong with that request. Please try again.