Why do you need to fold/unfold using coalesce for a conditional insert?

Question

I'm trying to understand how this pattern for a conditional insert works:

g.V()
  .hasLabel('person').has('name', 'John')
  .fold()
  .coalesce(
    __.unfold(),
    g.addV('person').property('name', 'John')
  ).next();

What is the purpose of the fold/unfold? Why are these necessary, and why does this not work:

g.V()
  .coalesce(
    __.hasLabel('person').has('name', 'John'),
    g.addV('person').property('name', 'John')
  ).next();

The fold-then-unfold pattern seems redundant to me and yet the above does not yield the same result.

Answer 1

Consider what happens when you just do the following:

gremlin> g = TinkerFactory.createModern().traversal()
==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard]
gremlin> g.V().has('name','marko')
==>v[1]
gremlin> g.V().has('name','stephen')
gremlin> 

For "marko" you return something and for "stephen" you do not. The "stephen" case is the one to pay attention to because that is the one where the fold() truly becomes important in this pattern. When that traversal returns nothing, any steps you add after that will not have a Traverser present to trigger actions in those steps. Therefore even the following will not add a vertex:

gremlin> g.V().has('name','stephen').addV('person')
gremlin> 

But looks what happens if we fold():

gremlin> g.V().has('name','stephen').fold()
==>[]

fold() is a reducing barrier step and will thus eagerly evaluate the traversal up to that point and return the contents as a List even if the contents of that traversal up to that point yield nothing (in which case, as you can see, you get an empty list). And if you have an empty List that empty List is a Traverser flowing through the traversal and therefore future steps will fire:

gremlin> g.V().has('name','stephen').fold().addV('person')
==>v[13]

So that explains why we fold() because we are checking for existence of "John" in your example and if he's found then he will exist in the List and when that List with "John" hits coalesce() its first check will be to unfold() that List with "John" and return that Vertex - done. If the List is empty and returns nothing because "John" does not exist then it will add the vertex (by the way, you don't need the "g." in front of addV(), it should just be an anonymous traversal and thus __.addV('person')).

Turning to your example, I would first point out that I think you wanted to ask about this:

g.V().
  coalesce(
    __.has('person','name', 'John'),
    __.addV('person').property('name', 'John'))

This is a completely different query. In this traversal, you're saying iterate all the vertices and for each one execute what is in the coalesce(). You can see this fairly plainly by replacing the addV() with constant('x'):

gremlin> g = TinkerFactory.createModern().traversal()
==>graphtraversalsource[tinkergraph[vertices:6 edges:6], standard]
gremlin> g.V().
......1>   coalesce(
......2>     has('person','name', 'John'),
......3>     constant('x'))
==>x
==>x
==>x
==>x
==>x
==>x
gremlin> g.V().
......1>   coalesce(
......2>     has('person','name', 'marko'),
......3>     constant('x'))
==>v[1]
==>x
==>x
==>x
==>x
==>x

Now, imagine what happens with addV() and "John". It will call addV() 6 times, once for each vertex it comes across that is not "John":

gremlin> g.V().
......1>   coalesce(
......2>     __.has('person','name', 'John'),
......3>     __.addV('person').property('name', 'John'))
==>v[13]
==>v[15]
==>v[17]
==>v[19]
==>v[21]
==>v[23]

Personally, I like the idea of wrapping up this kind of logic in a Gremlin DSL - there is a good example of doing so here.

Nice question - I've described the "Element Existence" issue as part of a Gremlin Recipe that can be read here.