(tinkerpop) branch master updated: Clarify mergeV() option() modulation and start-step semantics

[sp...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

spmallette pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/tinkerpop.git


The following commit(s) were added to refs/heads/master by this push:
     new b035aedadd Clarify mergeV() option() modulation and start-step semantics
b035aedadd is described below

commit b035aedaddfa8e4a529c30b43fedf4de1f5f6a25
Author: Stephen Mallette <st...@amazon.com>
AuthorDate: Fri Sep 11 17:42:08 2026 +0000

    Clarify mergeV() option() modulation and start-step semantics
    
    Keep the mergeV() Modulation bullets generic as option(Merge, MAP) and
    option(Merge, Traversal), updating the type token to the uppercase MAP,
    and add prose noting that onCreate and onMatch are the only Merge tokens
    option() accepts and when each is applied. Reconcile the Start Step
    column of the summary table with the Considerations by clarifying that
    Start Step applies to the mergeV(MAP) and mergeV(Traversal) overloads
    while the zero-arg mergeV() is mid-traversal only, and note that an empty
    MAP is the reproducible form for searchCreate since null is treated as
    equivalent.
    
    Assisted-by: Kiro:claude-opus-4.8
---
 docs/src/dev/provider/gremlin-semantics.asciidoc | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/src/dev/provider/gremlin-semantics.asciidoc b/docs/src/dev/provider/gremlin-semantics.asciidoc
index 27118d2e73..c2b9fdbdb1 100644
--- a/docs/src/dev/provider/gremlin-semantics.asciidoc
+++ b/docs/src/dev/provider/gremlin-semantics.asciidoc
@@ -2749,10 +2749,14 @@ must occur at traversal construction for static values (i.e. a `MAP`) and at run
 
 *Modulation:*
 
-* `option(Merge, Map)` - Sets the `onCreate` or `onMatch` arguments directly.
+* `option(Merge, MAP)` - Sets the `onCreate` or `onMatch` arguments directly.
 * `option(Merge, Traversal)` - Sets the `onCreate` or `onMatch` arguments dynamically where the `Traversal` must
 resolve to a `MAP`.
 
+The only `Merge` tokens accepted by `option()` are `onCreate` and `onMatch`. The `onCreate` argument is applied when
+`searchCreate` finds no match and a new `Vertex` is created, while the `onMatch` argument is applied when `searchCreate`
+matches an existing `Vertex`.
+
 *Exceptions:*
 
 * `MAP` arguments are validated for their keys resulting in exception if they do not meet requirements defined above.
@@ -2761,7 +2765,12 @@ resolve to a `MAP`.
 
 *Considerations:*
 
-* `mergeV()` (i.e. the zero-arg overload) can only be used mid-traversal. It is not a start step.
+* The `Start Step` designation in the summary table applies to the `mergeV(searchCreate: MAP)` and
+`mergeV(searchCreate: Traversal)` overloads. The zero-arg `mergeV()` overload can only be used mid-traversal, as it
+draws its `searchCreate` argument from the incoming `Traverser`.
+* An empty `MAP` is the reproducible way to request the match-all and create-with-defaults behavior for `searchCreate`.
+Supplying `null` is treated as equivalent to an empty `MAP`, so the empty `MAP` form is preferred where the overloaded
+signatures make a bare `null` ambiguous.
 * As is common to Gremlin, it is expected that `Traversal` arguments may utilize `sideEffect()` steps.
 
 See: link:https://github.com/apache/tinkerpop/tree/x.y.z/gremlin-core/src/main/java/org/apache/tinkerpop/gremlin/process/traversal/step/map/MergeVertexStep.java[source],