Except Retain Pattern

In many instances its desirable to traverse to only those elements that have not been seen in a previous step. Specific use cases are:

• “Who are my friends friends that are not already my friends?”
• “What is liked by the people that like the same things as me that I don’t already like?”

The solution to these types of problems is provided by the except pattern. Its opposite is the retain pattern—only traverse to those vertices that have been seen in a previous step.

gremlin> g = TinkerGraphFactory.createTinkerGraph()                                                               
==>tinkergraph[vertices:6 edges:6]
gremlin> g.v(1).outE.inV
==>v[2]
==>v[3]
==>v[4]
gremlin> g.v(1).outE.inV.outE.inV
==>v[5]
==>v[3]

Both the first outE.inV and the second emit v[3]. To ensure that v[3] is not traversed to on the second step, its necessary to save the results seen after the first outE.inV. There are three high-level pipes called aggregate, except, and retain. In the examples below, x stores all the values seen up to the aggregate step. Note that, everything in inV is “drained” into x before going to the next outE.

gremlin> x = []
gremlin> g.v(1).outE.inV.aggregate(x).outE.inV.except(x)
==>v[5]

gremlin> x = []
gremlin> g.v(1).outE.inV.aggregate(x).outE.inV.retain(x)
==>v[3]
==>v[3]