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 9cb7d61aaf Clarify addE()-step from()/to() semantics in reference docs
9cb7d61aaf is described below
commit 9cb7d61aafe1643c8a0b4fef048b0b497f3b88a2
Author: Stephen Mallette <[email protected]>
AuthorDate: Tue Aug 4 16:56:43 2026 +0000
Clarify addE()-step from()/to() semantics in reference docs
Distinguish the two addE() endpoint patterns that previously shared
identical callout prose: using the incoming traverser as the implicit
from-vertex (g.V(vMarko).addE('knows').to(vPeter)) versus spawning the
edge from g, which has no traverser and so requires both from() and
to() to be stated explicitly.
Add an introductory note documenting the two canonical from()/to()
argument forms (a step-label string and a child traversal), that
passing a Vertex object directly is language-variant convenience
syntax rather than canonical Gremlin, and that the examples run
cumulatively against the same graph so edges accumulate across the
block. Also correct the createdBy example callout, whose stated edge
direction was reversed relative to the actual lop->josh and
ripple->josh edges.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/reference/the-traversal.asciidoc | 12 +++++++++---
1 file changed, 9 insertions(+), 3 deletions(-)
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index 130ac5cda0..e4b35f54ee 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -619,6 +619,12 @@ worked on the same project together. This concept can be
represented as a traver
image::addedge-step.png[width=450]
+The `from()` and `to()` modulators identify the outgoing and incoming vertices
of the new edge. In canonical
+Gremlin each accepts one of two forms of argument: a step-label `String` that
refers to a previously labeled
+vertex, or a child traversal that produces a vertex (or a vertex id). When
`from()` or `to()` is omitted for an
+endpoint, the incoming traverser supplies that endpoint. Note that the
examples below execute cumulatively against
+the same graph, so each `addE()` persists a new edge and the graph's edges
accumulate from one line to the next.
+
[gremlin-groovy,modern]
----
g.V(1).as('a').out('created').in('created').where(neq('a')).
@@ -637,11 +643,11 @@ g.addE('knows').from(__.V(1)).to(__.constant(6)) <7>
----
<1> Add a co-developer edge with a year-property between marko and his
collaborators.
-<2> Add incoming createdBy edges from the josh-vertex to the lop- and
ripple-vertices.
+<2> Add incoming createdBy edges to the josh-vertex from the lop- and
ripple-vertices (i.e. lop and ripple each point to josh).
<3> Add an inverse createdBy edge for all created edges.
<4> The newly created edge is a traversable object.
-<5> Add an edge between marko and peter given the directed (detached) vertex
references.
-<6> Add an edge between marko and peter given the directed (detached) vertex
references.
+<5> Add a knows edge from marko to peter: the incoming traverser (the
marko-vertex) serves as the implicit from-vertex, so only `to()` is supplied.
Passing a `Vertex` object directly to `to()` (here `vPeter`) is a convenience
exposed by the language variant -- e.g. Gremlin-Java, which resolves the
`Vertex` down to its id -- rather than a canonical Gremlin argument form.
+<6> Add a knows edge from marko to peter: because the traversal starts from
`g` (the graph) rather than a vertex, there is no incoming traverser to act as
a default endpoint, so both `from()` and `to()` must be given explicitly. As on
the previous line, supplying `Vertex` objects (`vMarko`, `vPeter`) directly is
language-variant convenience syntax rather than canonical Gremlin.
<7> Use child traversals producing either a vertex, or vertex id to add an
edge between marko and peter.
*Additional References*
