Gremlin mergeV/E() API

mergeV/E(Map|Traversal search).
  option(Merge.onCreate, Map|Traversal).
  option(Merge.onMatch, Map|Traversal)

Examples

mergeV() - "get or create"

approximation of fold().coalesce(unfold(), addV())

// without any option(), the behavior is the same as above, creating using search criteria
// if there is no match
g.mergeV([(T.label): 'person', name: 'marko', age: 29])

// if matched the Vertex will be returned, otherwise create the Vertex with the specified Map
g.mergeV([(T.id): 1]).
    option(Merge.onCreate, [(T.label): 'person', name: 'marko', age: 29])

// if matched the Vertex will be returned, otherwise create the Vertex with the dynamically specified Map
g.withSideEffect('c', [(T.label): 'person', name: 'marko', age: 29]).
  mergeV([(T.id): 1]).
    option(Merge.onCreate, select('c'))

mergeV() - "get/update or create"

approximation of fold().coalesce(unfold().property(...), addV())

// if matched the Vertex will be returned with the "age" property updated, otherwise create the
// Vertex with the specified Map
g.mergeV([(T.id): 1]).
    option(Merge.onCreate, [(T.label): 'person', name: 'marko', age: 29]).
    option(Merge.onMatch, [age: 30])

// if matched the Vertex will be returned with "age" property from the dynamically specified Map of 
// "m", otherwise create the Vertex with the dynamically specified Map of "c"
g.withSideEffect('c', [(T.label): 'person', name: 'marko', age: 29]).
  withSideEffect('m', [age: 30]).
  mergeV([(T.id): 1]).
    option(Merge.onCreate, select('c'))
    option(Merge.onMatch, select('m'))
    
// if matched on the dynamically established search criteria of "s", the Vertex will be returned with 
// "age" property from the dynamically specified Map of "m", otherwise create the Vertex with the 
// dynamically specified Map of "c"
g.withSideEffect('s', [(T.id): 1]).
  withSideEffect('c', [(T.label): 'person', name: 'marko', age: 29]).
  withSideEffect('m', [age: 30]).
  mergeV(select('s')).
    option(Merge.onCreate, select('c'))
    option(Merge.onMatch, select('m'))

mergeV() with Meta Properties

// match on id and return if found otherwise create a Vertex (attempting to set "2" for the id
// if the graph supports it) and in either case set the "name" property and its associated meta
// property
g.mergeV([(T.id): 2]).
  property('name','vadas','acl','public')

// or use the additional properties syntax
g.mergeV([(T.label): 'person', name:'vadas']).
  properties('name').property('acl','public')

// or if there were multi-properties then maybe...
g.mergeV([(T.label): 'person', name:'vadas']).
  properties('name').hasValue('vadas').property('acl','public')

mergeV() with Multi Properties

// this a List object
g.mergeV([(T.label): 'person', lang: ['java', 'scala', 'java'])

// this is a multi-property
g.mergeV([(T.id): 1, (T.label): 'person']).
  property(list, 'lang', 'java'). 
  property(list, 'lang', 'scala').
  property(list, 'lang', 'java')

mergeV() with stream

g.inject([(T.id): 1, (T.label): 'person', name: 'marko'],
         [(T.id): 2, (T.label): 'person', name: 'josh']).
  mergeV(identity())
g.inject([(T.id): 1, (T.label): 'person', name: 'marko'],
         [(T.id): 2, (T.label): 'person', name: 'josh']).
  mergeV()  
  
g.inject([[id: 1], [label: 'person', name: 'marko', created: 2020],[updated: 2021]],
         [[id: 2], [label: 'person', name: 'josh', created: 2020], [updated: 2021]).
  mergeV(limit(local,1)).
    option(onCreate, range(local, 1, 2)).
    option(onMatch, tail(local))

mergeV() explicit failure

// ensure that the a Vertex with id of "1" exists and if not then throw an exception
g.mergeV([(T.id): 1]).
    option(onCreate, fail("vertex did not exist")).
    option(onMatch, [modified: 2021])

mergeE() with incident Vertex checks

mergeE() has similar semantics as mergeV() but includes the availability of Direction in Map arguments

// uses Direction to specify incident edges
g.mergeE([(T.label): 'knows', weight: 0.5, 
          (OUT): new ReferenceVertex(1, 'person'), 
          (IN): new ReferenceVertex(2, 'person')])

// the Vertex for the edge is defaulted to the incoming traverser and the match
// criteria assumes IN/OUT of the edge to be that Vertex (thus a self relationship
// in the following example).
g.V().has('person','name','josh').
  mergeE([(T.label): 'self', weight:0.5])

// the above could could also be accomplished explicitly as follows
g.mergeE([(T.label): 'self', weight:0.5, (BOTH): new ReferenceVertex(2, 'person')])

// override the default Vertex of "josh" for IN to indicate an edge josh-knows->vadas
g.V().has('person','name','josh').
  mergeE([(T.label): 'knows', weight:0.5, (IN): new ReferenceVertex(2, 'person')]).
    option(onMatch, ['weight':0.6])
  
// if the match Vertex does not exist then mergeE() will trigger onCreate to construct the
// missing Vertex with addV() and thus allow the Edge to be created.
g.V().has('person','name','josh').
  mergeE([(T.label): 'knows', weight:0.5, (IN): new ReferenceVertex(2000, 'person')]).
    option(onMatch, ['weight':0.6])    
    
// if the previous behavior of adding the missing Vertex is not desired then the traversal
// should be written more defensively
g.V(2000).
  V().has('person','name','josh').
  mergeE([(T.label): 'knows', weight:0.5, (IN): new ReferenceVertex(2000, 'person')]).
    option(onMatch, ['weight':0.6])

spmallette/gremlin-merge.md