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 7faa479 Added more details around subgraph() and TinkerGraph CTR
new 578ac5c Merge branch 'tp33'
7faa479 is described below
commit 7faa4792552376dc83c32cc28ead60cd658ca75f
Author: Stephen Mallette <[email protected]>
AuthorDate: Tue Nov 20 09:39:21 2018 -0500
Added more details around subgraph() and TinkerGraph CTR
---
docs/src/reference/the-traversal.asciidoc | 32 +++++++++++++++++++++++++++++--
1 file changed, 30 insertions(+), 2 deletions(-)
diff --git a/docs/src/reference/the-traversal.asciidoc
b/docs/src/reference/the-traversal.asciidoc
index 46b21f6..96da120 100644
--- a/docs/src/reference/the-traversal.asciidoc
+++ b/docs/src/reference/the-traversal.asciidoc
@@ -2631,8 +2631,36 @@ t.sideEffects.get('knowsG').traversal().E()
t.sideEffects.get('createdG').traversal().E()
----
-IMPORTANT: The `subgraph()`-step only writes to graphs that support user
supplied ids for its elements. Moreover,
-if no graph is specified via `withSideEffect()`, then
<<tinkergraph-gremlin,TinkerGraph>> is assumed.
+TinkerGraph is the ideal (and default) `Graph` into which a subgraph is
extracted as it's fast, in-memory, and supports
+user-supplied identifiers which can be any Java object. It is this last
feature that needs some focus as many
+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:
+
+[source,text]
+----
+Vertex v = sg.V().has('name','marko').next(); <1>
+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.
+
+It is safer to wrap the `TinkerVertex` in a `ReferenceVertex` or simply
reference the `id()` as follows:
+
+[source,text]
+----
+Vertex v = sg.V().has('name','marko').next();
+List<Vertex> vertices = g.V(v.id()).out().toList();
+
+// OR
+
+Vertex v = new ReferenceVertex(sg.V().has('name','marko').next());
+List<Vertex> vertices = g.V(v).out().toList();
+----
*Additional References*
