CosmosDB Graph : “upsert” query pattern

There are a number of ways to do this but I think that the TinkerPop community has generally settled on this approach:

g.V().has('event','id','1').
  fold().
  coalesce(unfold(),
           addV('event').property('id','1'))

Basically, it looks for the “event” with has() and uses fold() step to coerce to a list. The list will either be empty or have a Vertex in it. Then with coalesce(), it tries to unfold() the list and if it has a Vertex that is immediately returned otherwise, it does the addV().

If the idea is to update existing properties if the element is found, just add property() steps after the coalesce():

g.V().has('event','id','1').
  fold().
  coalesce(unfold(),
           addV('event').property('id','1')).
  property('description','This is an event')

If you need to know if the vertex returned was “new” or not then you could do something like this:

g.V().has('event','id','1').
  fold().
  coalesce(unfold().
           project('vertex','exists').
             by(identity()).
             by(constant(true)),
           addV('event').property('id','1').
           project('vertex','exists').
             by(identity()).
             by(constant(false)))

Additional reading on this topic can be found on this question: “Why do you need to fold/unfold using coalesce for a conditional insert?“

Also note that optional edge insertion is described here: “Add edge if not exist using gremlin“.

As a final note, while this question was asked regarding CosmosDB, the answer generally applies to all TinkerPop-enabled graphs. Of course, how a graph optimizes this Gremlin is a separate question. If a graph has native upsert capabilities, that capability may or may not be used behind the scenes of this Gremlin so there may be better ways to implement upsert by way of the graphs systems native API (of course, choosing that path reduces the portability of your code).

TinkerPop 3.6.0 Update – this question and answer has become a bit of a central point for get/create patterns in Gremlin so I thought it was worth adding that Gremlin now has a mergeV() and mergeE() step that encapsulates the fold()/coalesce()/unfold() pattern described above making it considerably easier to implement this sort of functionality. Be sure that your graph provider supports version 3.6.0 or greater prior to using this new feature.