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 f915868fe2 Clarify subgraph-step TinkerVertex caveat as
implementation-dependent
f915868fe2 is described below
commit f915868fe273e01e77561a1ed949e6b1a04ff29d
Author: stepmall <[email protected]>
AuthorDate: Sat Jul 25 19:53:27 2026 +0000
Clarify subgraph-step TinkerVertex caveat as implementation-dependent
The subgraph-step section warned that a TinkerGraph subgraph's elements
could not be used directly against the original graph and gave an example
it said would likely return an error. That is misleading for the example
shown, where the original graph is also a TinkerGraph: TinkerGraph looks
vertices up by their identifier, so the reference resolves and the
traversal succeeds. Reword the caveat and its callout to frame the
behavior as implementation-dependent. It resolves for a TinkerGraph
original and may fail against a different implementation that does not
recognize a foreign TinkerVertex. The ReferenceVertex/id() block remains
the portable recommendation.
Assisted-by: Kiro:claude-opus-4.8
---
docs/src/reference/the-traversal.asciidoc | 12 ++++++++----
1 file changed, 8 insertions(+), 4 deletions(-)
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index 0965b7fdad..aad44f344a 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -5265,8 +5265,11 @@ user-supplied identifiers which can be any Java object.
It is this last feature
TinkerPop-enabled graphs have complex identifier types and TinkerGraph's
ability to consume those makes it a perfect
host for an incoming subgraph. However care needs to be taken when using the
elements of the TinkerGraph subgraph.
The original graph's identifiers may be preserved, but the elements of the
graph are now TinkerGraph objects like,
-`TinkerVertex` and `TinkerEdge`. As a result, they can not be used directly in
Gremlin running against the original
-graph. For example, the following traversal would likely return an error:
+`TinkerVertex` and `TinkerEdge`. Whether these elements can be used directly
in Gremlin running against the original
+graph depends on the original graph's implementation. When the original graph
is also a TinkerGraph (as in the modern
+graph example shown here), the reference resolves successfully because
TinkerGraph looks up vertices by their
+identifier, so the following traversal returns the expected result. When the
original graph is a different
+implementation, it may not recognize a foreign `TinkerVertex` and could return
an error:
[source,text]
----
@@ -5275,8 +5278,9 @@ List<Vertex> vertices = g.V(v).out().toList(); <2>
----
<1> Here "sg" is a reference to a TinkerGraph subgraph and "v" is a
`TinkerVertex`.
-<2> The `g.V(v)` has the potential to fail as "g" is the original `Graph`
instance and not a TinkerGraph - it could
-reject the `TinkerVertex` instance as it will not recognize it.
+<2> The outcome of `g.V(v)` depends on the implementation of "g", the original
`Graph` instance. If "g" is a
+TinkerGraph, it resolves the reference by its identifier and the traversal
succeeds. If "g" is a different
+implementation, it may reject the `TinkerVertex` instance as it will not
recognize it.
It is safer to wrap the `TinkerVertex` in a `ReferenceVertex` or simply
reference the `id()` as follows:
