Github user spmallette commented on a diff in the pull request:
https://github.com/apache/tinkerpop/pull/371#discussion_r73552034
--- Diff: docs/src/recipes/traversal-induced-values.asciidoc ---
@@ -0,0 +1,83 @@
+////
+Licensed to the Apache Software Foundation (ASF) under one or more
+contributor license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright ownership.
+The ASF licenses this file to You under the Apache License, Version 2.0
+(the "License"); you may not use this file except in compliance with
+the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+////
+[[traversal-induced-values]]
+Traversal Induced Values
+------------------------
+
+The parameters of a `Traversal` can be known ahead of time as constants or
might otherwise be passed in as dynamic
+arguments.
+
+[gremlin-groovy,modern]
+----
+g.V().has('name','marko').out('knows').has('age', gt(29)).values('name')
+----
+
+In plain language, the above Gremlin asks, "What are the names of the
people who Marko knows who are over the age of
+29?". In this case, "29" is known as a constant to the traversal. Of
course, if the question is changed slightly to
+instead ask, "What are the names of the people who Marko knows who are
older than he is?", the hardcoding of "29" will
+no longer suffice. There are multiple ways Gremlin would allow this second
question to be answered. The first is
+obvious to any programmer - use a variable:
+
+[gremlin-groovy,modern]
+----
+marko = g.V().has('name','marko').next()
+g.V(marko).out('knows').has('age', gt(marko.value('age'))).values('name')
+----
+
+The downside to this approach is that it takes two separate traversals to
answer the question. Ideally, there should
+be a single traversal, that can query "marko" once, determine his `age`
and then use that for the value supplied to
+filter the people he knows. In this way the _value_ for the `age` filter
is _induced_ from the `Traversal` itself.
+
+[gremlin-groovy,modern]
+----
+g.V().has('name','marko').as('marko'). <1>
+ out('knows').as('friend'). <2>
+ filter(select('marko','friend').by('age'). <3>
+ where('friend', gt('marko'))). <4>
+ values('name')
+----
+
+<1> Find the "marko" `Vertex` and label it as "marko".
+<2> Traverse out on the "knows" edges to the adjacent `Vertex` and label
it as "person".
+<3> Filter the incoming "person" vertices. It is within this filter, that
the traversal induced values are utilized.
+The inner `select` grabs the "marko" vertex and the current "friend". The
`by` modulator extracts the "age" from both
+of those vertices which yields a `Map` with two keys, "marko" and
"friend", where the value of each is the "age".
+<4> The `Map` produced in the previous step can then be filtered with
`where` to only return a result if the "friend"
+age is greater than the "marko" age. If this is successful, then the
`filter` step from the previous line will succeed
+and allow the "friend" vertex to pass through.
+
+This traversal could also be written declaratively with `match` step as
follows:
--- End diff --
I thought about going into more detail there, but opted not to. I kinda
thought that if we wanted that sort of content that it didn't belong in a
recipe but in reference docs. It seemed a little out of scope of the recipe.
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
