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 <[email protected]>
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],
