You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@tinkerpop.apache.org by sp...@apache.org on 2015/11/22 06:59:19 UTC
[04/22] incubator-tinkerpop git commit: Made subdirectories for
various "books" in the docs.
http://git-wip-us.apache.org/repos/asf/incubator-tinkerpop/blob/bc46d649/docs/src/the-traversal.asciidoc
----------------------------------------------------------------------
diff --git a/docs/src/the-traversal.asciidoc b/docs/src/the-traversal.asciidoc
deleted file mode 100644
index 0b82823..0000000
--- a/docs/src/the-traversal.asciidoc
+++ /dev/null
@@ -1,2378 +0,0 @@
-////
-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]]
-The Traversal
-=============
-
-image::gremlin-running.png[width=125]
-
-At the most general level there is `Traversal<S,E>` which implements `Iterator<E>`, where the `S` stands for start and
-the `E` stands for end. A traversal is composed of four primary components:
-
- . `Step<S,E>`: an individual function applied to `S` to yield `E`. Steps are chained within a traversal.
- . `TraversalStrategy`: interceptor methods to alter the execution of the traversal (e.g. query re-writing).
- . `TraversalSideEffects`: key/value pairs that can be used to store global information about the traversal.
- . `Traverser<T>`: the object propagating through the `Traversal` currently representing an object of type `T`.
-
-The classic notion of a graph traversal is provided by `GraphTraversal<S,E>` which extends `Traversal<S,E>`.
-`GraphTraversal` provides an interpretation of the graph data in terms of vertices, edges, etc. and thus, a graph
-traversal link:http://en.wikipedia.org/wiki/Domain-specific_language[DSL].
-
-IMPORTANT: The underlying `Step` implementations provided by TinkerPop should encompass most of the functionality
-required by a DSL author. It is important that DSL authors leverage the provided steps as then the common optimization
-and decoration strategies can reason on the underlying traversal sequence. If new steps are introduced, then common
-traversal strategies may not function properly.
-
-[[graph-traversal-steps]]
-Graph Traversal Steps
----------------------
-
-image::step-types.png[width=650]
-
-A `GraphTraversal<S,E>` is spawned from a `GraphTraversalSource`. It can also be spawned anonymously (i.e. empty)
-via `__`. A graph traversal is composed of an ordered list of steps. All the steps provided by `GraphTraversal`
-inherit from the more general forms diagrammed above. A list of all the steps (and their descriptions) are provided
-in the TinkerPop3 link:http://tinkerpop.incubator.apache.org/javadocs/3.0.2-incubating/core/org/apache/tinkerpop/gremlin/process/traversal/dsl/graph/GraphTraversal.html[GraphTraversal JavaDoc].
-The following subsections will demonstrate the GraphTraversal steps using the <<gremlin-console,Gremlin Console>>.
-
-NOTE: To reduce the verbosity of the expression, it is good to
-`import static org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.__.*`. This way, instead of doing `__.inE()`
-for an anonymous traversal, it is possible to simply write `inE()`. Be aware of language-specific reserved keywords
-when using anonymous traversals. For example, `in` and `as` are reserved keywords in Groovy, therefore you must use
-the verbose syntax `__.in()` and `__.as()` to avoid collisions.
-
-[[lambda-steps]]
-Lambda Steps
-~~~~~~~~~~~~
-
-CAUTION: Lambda steps are presented for educational purposes as they represent the foundational constructs of the
-Gremlin language. In practice, lambda steps should be avoided and traversal verification strategies exist to disallow t
-heir use unless explicitly "turned off." For more information on the problems with lambdas, please read
-<<a-note-on-lambdas,A Note on Lambdas>>.
-
-There are four generic steps by which all other specific steps described later extend.
-
-[width="100%",cols="10,12",options="header"]
-|=========================================================
-| Step| Description
-| `map(Function<Traverser<S>, E>)` | map the traverser to some object of type `E` for the next step to process.
-| `flatMap(Function<Traverser<S>, Iterator<E>>)` | map the traverser to an iterator of `E` objects that are streamed to the next step.
-| `filter(Predicate<Traverser<S>>)` | map the traverser to either true or false, where false will not pass the traverser to the next step.
-| `sideEffect(Consumer<Traverser<S>>)` | perform some operation on the traverser and pass it to the next step.
-| `branch(Function<Traverser<S>,M>)` | split the traverser to all the traversals indexed by the `M` token.
-|=========================================================
-
-The `Traverser<S>` object provides access to:
-
- . The current traversed `S` object -- `Traverser.get()`.
- . The current path traversed by the traverser -- `Traverser.path()`.
- .. A helper shorthand to get a particular path-history object -- `Traverser.path(String) == Traverser.path().get(String)`.
- . The number of times the traverser has gone through the current loop -- `Traverser.loops()`.
- . The number of objects represented by this traverser -- `Traverser.bulk()`.
- . The local data structure associated with this traverser -- `Traverser.sack()`.
- . The side-effects associated with the traversal -- `Traverser.sideEffects()`.
- .. A helper shorthand to get a particular side-effect -- `Traverser.sideEffect(String) == Traverser.sideEffects().get(String)`.
-
-image:map-lambda.png[width=150,float=right]
-[gremlin-groovy,modern]
-----
-g.V(1).out().values('name') <1>
-g.V(1).out().map {it.get().value('name')} <2>
-----
-
-<1> An outgoing traversal from vertex 1 to the name values of the adjacent vertices.
-<2> The same operation, but using a lambda to access the name property values.
-
-image:filter-lambda.png[width=160,float=right]
-[gremlin-groovy,modern]
-----
-g.V().filter {it.get().label() == 'person'} <1>
-g.V().hasLabel('person') <2>
-----
-
-<1> A filter that only allows the vertex to pass if it has an age-property.
-<2> The more specific `has()`-step is implemented as a `filter()` with respective predicate.
-
-
-image:side-effect-lambda.png[width=175,float=right]
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').sideEffect(System.out.&println) <1>
-----
-
-<1> Whatever enters `sideEffect()` is passed to the next step, but some intervening process can occur.
-
-image:branch-lambda.png[width=180,float=right]
-[gremlin-groovy,modern]
-----
-g.V().branch(values('name')).
- option('marko', values('age')).
- option(none, values('name')) <1>
-g.V().choose(has('name','marko'),
- values('age'),
- values('name')) <2>
-----
-
-<1> If the vertex is "marko", get his age, else get the name of the vertex.
-<2> The more specific boolean-based `choose()`-step is implemented as a `branch()`.
-
-[[addedge-step]]
-AddEdge Step
-~~~~~~~~~~~~
-
-link:http://en.wikipedia.org/wiki/Automated_reasoning[Reasoning] is the process of making explicit what is implicit
-in the data. What is explicit in a graph are the objects of the graph -- i.e. vertices and edges. What is implicit
-in the graph is the traversal. In other words, traversals expose meaning where the meaning is determined by the
-traversal definition. For example, take the concept of a "co-developer." Two people are co-developers if they have
-worked on the same project together. This concept can be represented as a traversal and thus, the concept of
-"co-developers" can be derived. Moreover, what was once implicit can be made explicit via the `addE()`-step
-(*map*/*sideEffect*).
-
-image::addedge-step.png[width=450]
-
-[gremlin-groovy,modern]
-----
-g.V(1).as('a').out('created').in('created').where(neq('a')).
- addE('co-developer').from('a').property('year',2009) <1>
-g.V(3,4,5).aggregate('x').has('name','josh').as('a').
- select('x').unfold().hasLabel('software').addE('createdBy').to('a') <2>
-g.V().as('a').out('created').addE('createdBy').to('a').property('acl','public') <3>
-g.V(1).as('a').out('knows').
- addE('livesNear').from('a').property('year',2009).
- inV().inE('livesNear').values('year') <4>
-g.V().match(
- __.as('a').out('knows').as('b'),
- __.as('a').out('created').as('c'),
- __.as('b').out('created').as('c')).
- addE('friendlyCollaborator').from('a').to('b').
- property(id,13).property('project',select('c').values('name')) <5>
-g.E(13).valueMap()
-----
-
-<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.
-<3> Add an inverse createdBy edge for all created edges.
-<4> The newly created edge is a traversable object.
-<5> Two arbitrary bindings in a traversal can be joined `from()`->`to()`, where `id` can be provided for graphs that
-supports user provided ids.
-
-[[addvertex-step]]
-AddVertex Step
-~~~~~~~~~~~~~~
-
-The `addV()`-step is used to add vertices to the graph (*map*/*sideEffect*). For every incoming object, a vertex is
-created. Moreover, `GraphTraversalSource` maintains an `addV()` method.
-
-[gremlin-groovy,modern]
-----
-g.addV('person').property('name','stephen')
-g.V().values('name')
-g.V().outE('knows').addV().property('name','nothing')
-g.V().has('name','nothing')
-g.V().has('name','nothing').bothE()
-----
-
-[[addproperty-step]]
-AddProperty Step
-~~~~~~~~~~~~~~~~
-
-The `property()`-step is used to add properties to the elements of the graph (*sideEffect*). Unlike `addV()` and
-`addE()`, `property()` is a full sideEffect step in that it does not return the property it created, but the element
-that streamed into it. Moreover, if `property()` follows an `addV()` or `addE()`, then it is "folded" into the
-previous step to enable vertex and edge creation with all its properties in one creation operation.
-
-[gremlin-groovy,modern]
-----
-g.V(1).property('country','usa')
-g.V(1).property('city','santa fe').property('state','new mexico').valueMap()
-g.V(1).property(list,'age',35) <1>
-g.V(1).valueMap()
-g.V(1).property('friendWeight',outE('knows').values('weight').sum(),'acl','private') <2>
-g.V(1).properties('friendWeight').valueMap() <3>
-----
-
-<1> For vertices, a cardinality can be provided for <<vertex properties,vertex-properties>>.
-<2> It is possible to select the property value (as well as key) via a traversal.
-<3> For vertices, the `property()`-step can add meta-properties.
-
-
-[[aggregate-step]]
-Aggregate Step
-~~~~~~~~~~~~~~
-
-image::aggregate-step.png[width=800]
-
-The `aggregate()`-step (*sideEffect*) is used to aggregate all the objects at a particular point of traversal into a
-`Collection`. The step uses link:http://en.wikipedia.org/wiki/Eager_evaluation[eager evaluation] in that no objects
-continue on until all previous objects have been fully aggregated (as opposed to <<store-step,`store()`>> which
-link:http://en.wikipedia.org/wiki/Lazy_evaluation[lazily] fills a collection). The eager evaluation nature is crucial
-in situations where everything at a particular point is required for future computation. An example is provided below.
-
-[gremlin-groovy,modern]
-----
-g.V(1).out('created') <1>
-g.V(1).out('created').aggregate('x') <2>
-g.V(1).out('created').aggregate('x').in('created') <3>
-g.V(1).out('created').aggregate('x').in('created').out('created') <4>
-g.V(1).out('created').aggregate('x').in('created').out('created').
- where(without('x')).values('name') <5>
-----
-
-<1> What has marko created?
-<2> Aggregate all his creations.
-<3> Who are marko's collaborators?
-<4> What have marko's collaborators created?
-<5> What have marko's collaborators created that he hasn't created?
-
-In link:http://en.wikipedia.org/wiki/Recommender_system[recommendation systems], the above pattern is used:
-
- "What has userA liked? Who else has liked those things? What have they liked that userA hasn't already liked?"
-
-Finally, `aggregate()`-step can be modulated via `by()`-projection.
-
-[gremlin-groovy,modern]
-----
-g.V().out('knows').aggregate('x').cap('x')
-g.V().out('knows').aggregate('x').by('name').cap('x')
-----
-
-[[and-step]]
-And Step
-~~~~~~~~
-
-The `and()`-step ensures that all provided traversals yield a result (*filter*). Please see <<or-step,`or()`>> for or-semantics.
-
-[gremlin-groovy,modern]
-----
-g.V().and(
- outE('knows'),
- values('age').is(lt(30))).
- values('name')
-----
-
-The `and()`-step can take an arbitrary number of traversals. All traversals must produce at least one output for the
-original traverser to pass to the next step.
-
-An link:http://en.wikipedia.org/wiki/Infix_notation[infix notation] can be used as well. Though, with infix notation,
-only two traversals can be and'd together.
-
-[gremlin-groovy,modern]
-----
-g.V().where(outE('created').and().outE('knows')).values('name')
-----
-
-[[as-step]]
-As Step
-~~~~~~~
-
-The `as()`-step is not a real step, but a "step modulator" similar to <<by-step,`by()`>> and <<option-step,`option()`>>.
-With `as()`, it is possible to provide a label to the step that can later be accessed by steps and data structures
-that make use of such labels -- e.g., <<select-step,`select()`>>, <<match-step,`match()`>>, and path.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out('created').as('b').select('a','b') <1>
-g.V().as('a').out('created').as('b').select('a','b').by('name') <2>
-----
-
-<1> Select the objects labeled "a" and "b" from the path.
-<2> Select the objects labeled "a" and "b" from the path and, for each object, project its name value.
-
-A step can have any number of labels associated with it. This is useful for referencing the same step multiple times in a future step.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('software').as('a','b','c').
- select('a','b','c').
- by('name').
- by('lang').
- by(__.in('created').values('name').fold())
-----
-
-[[barrier-step]]
-Barrier Step
-~~~~~~~~~~~~
-
-The `barrier()`-step (*barrier*) turns the the lazy traversal pipeline into a bulk-synchronous pipeline. This step is
-useful in the following situations:
-
- * When everything prior to `barrier()` needs to be executed before moving onto the steps after the `barrier()` (i.e. ordering).
- * When "stalling" the traversal may lead to a "bulking optimization" in traversals that repeatedly touch many of the same elements (i.e. optimizing).
-
-[gremlin-groovy,modern]
-----
-g.V().sideEffect{println "first: ${it}"}.sideEffect{println "second: ${it}"}.iterate()
-g.V().sideEffect{println "first: ${it}"}.barrier().sideEffect{println "second: ${it}"}.iterate()
-----
-
-The theory behind a "bulking optimization" is simple. If there are one million traversers at vertex 1, then there is
-no need to calculate one million `both()`-computations. Instead, represent those one million traversers as a single
-traverser with a `Traverser.bulk()` equal to one million and execute `both()` once. A bulking optimization example is
-made more salient on a larger graph. Therefore, the example below leverages the <<grateful-dead,Grateful Dead graph>>.
-
-[gremlin-groovy]
-----
-graph = TinkerGraph.open()
-graph.io(graphml()).readGraph('data/grateful-dead.xml')
-g = graph.traversal(standard())
-clockWithResult(1){g.V().both().both().both().count().next()} <1>
-clockWithResult(1){g.V().repeat(both()).times(3).count().next()} <2>
-clockWithResult(1){g.V().both().barrier().both().barrier().both().barrier().count().next()} <3>
-----
-
-<1> A non-bulking traversal where each traverser is processed.
-<2> Each traverser entering `repeat()` has its recursion bulked.
-<3> A bulking traversal where implicit traversers are not processed.
-
-If `barrier()` is provided an integer argument, then the barrier will only hold `n`-number of unique traversers in its
-barrier before draining the aggregated traversers to the next step. This is useful in the aforementioned bulking
-optimization scenario, but reduces the risk of an out-of-memory exception.
-
-The non-default `LazyBarrierStrategy` inserts `barrier()`-steps in a traversal where appropriate in order to gain the
-"bulking optimization."
-
-[gremlin-groovy]
-----
-graph = TinkerGraph.open()
-graph.io(graphml()).readGraph('data/grateful-dead.xml')
-g = graph.traversal(GraphTraversalSource.build().with(LazyBarrierStrategy.instance()).engine(StandardTraversalEngine.build()))
-clockWithResult(1){g.V().both().both().both().count().next()}
-g.V().both().both().both().count().iterate().toString() <1>
-----
-
-<1> With `LazyBarrierStrategy` activated, `barrier()` steps are automatically inserted where appropriate.
-
-[[by-step]]
-By Step
-~~~~~~~
-
-The `by()`-step is not an actual step, but instead is a "step-modulator" similar to <<as-step,`as()`>> and
-<<option-step,`option()`>>. If a step is able to accept traversals, functions, comparators, etc. then `by()` is the
-means by which they are added. The general pattern is `step().by()...by()`. Some steps can only accept one `by()`
-while others can take an arbitrary amount.
-
-[gremlin-groovy,modern]
-----
-g.V().group().by(bothE().count()) <1>
-g.V().group().by(bothE().count()).by('name') <2>
-g.V().group().by(bothE().count()).by(count()) <3>
-----
-
-<1> `by(outE().count())` will group the elements by their edge count (*traversal*).
-<2> `by('name')` will process the grouped elements by their name (*element property projection*).
-<3> `by(count())` will count the number of elements in each group (*traversal*).
-
-[cap-step]]
-Cap Step
-~~~~~~~~
-
-The `cap()`-step (*barrier*) iterates the traversal up to itself and emits the sideEffect referenced by the provided
-key. If multiple keys are provided, then a `Map<String,Object>` of sideEffects is emitted.
-
-[gremlin-groovy,modern]
-----
-g.V().groupCount('a').by(label).cap('a') <1>
-g.V().groupCount('a').by(label).groupCount('b').by(outE().count()).cap('a','b') <2>
-----
-
-<1> Group and count verticies by their label. Emit the side effect labeled 'a', which is the group count by label.
-<2> Same as statement 1, but also emit the side effect labeled 'b' which groups vertices by the number of out edges.
-
-[[coalesce-step]]
-Coalesce Step
-~~~~~~~~~~~~~
-
-The `coalesce()`-step evaluates the provided traversals in order and returns the first traversal that emits at
-least one element.
-
-[gremlin-groovy,modern]
-----
-g.V(1).coalesce(outE('knows'), outE('created')).inV().path().by('name').by(label)
-g.V(1).coalesce(outE('created'), outE('knows')).inV().path().by('name').by(label)
-g.V(1).next().property('nickname', 'okram')
-g.V().hasLabel('person').coalesce(values('nickname'), values('name'))
-----
-
-[[count-step]]
-Count Step
-~~~~~~~~~~
-
-image::count-step.png[width=195]
-
-The `count()`-step (*map*) counts the total number of represented traversers in the streams (i.e. the bulk count).
-
-[gremlin-groovy,modern]
-----
-g.V().count()
-g.V().hasLabel('person').count()
-g.V().hasLabel('person').outE('created').count().path() <1>
-g.V().hasLabel('person').outE('created').count().map {it.get() * 10}.path() <2>
-----
-
-<1> `count()`-step is a <<a-note-on-barrier-steps,reducing barrier step>> meaning that all of the previous traversers are folded into a new traverser.
-<2> The path of the traverser emanating from `count()` starts at `count()`.
-
-IMPORTANT: `count(local)` counts the current, local object (not the objects in the traversal stream). This works for
-`Collection`- and `Map`-type objects. For any other object, a count of 1 is returned.
-
-[[choose-step]]
-Choose Step
-~~~~~~~~~~~
-
-image::choose-step.png[width=700]
-
-The `choose()`-step (*branch*) routes the current traverser to a particular traversal branch option. With `choose()`,
-it is possible to implement if/else-based semantics as well as more complicated selections.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').
- choose(values('age').is(lte(30)),
- __.in(),
- __.out()).values('name') <1>
-g.V().hasLabel('person').
- choose(values('age')).
- option(27, __.in()).
- option(32, __.out()).values('name') <2>
-----
-
-<1> If the traversal yields an element, then do `in`, else do `out` (i.e. true/false-based option selection).
-<2> Use the result of the traversal as a key to the map of traversal options (i.e. value-based option selection).
-
-However, note that `choose()` can have an arbitrary number of options and moreover, can take an anonymous traversal as its choice function.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').
- choose(values('name')).
- option('marko', values('age')).
- option('josh', values('name')).
- option('vadas', valueMap()).
- option('peter', label())
-----
-
-The `choose()`-step can leverage the `Pick.none` option match. For anything that does not match a specified option, the `none`-option is taken.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').
- choose(values('name')).
- option('marko', values('age')).
- option(none, values('name'))
-----
-
-[[coin-step]]
-Coin Step
-~~~~~~~~~
-
-To randomly filter out a traverser, use the `coin()`-step (*filter*). The provided double argument biases the "coin toss."
-
-[gremlin-groovy,modern]
-----
-g.V().coin(0.5)
-g.V().coin(0.0)
-g.V().coin(1.0)
-----
-
-[[constant-step]]
-Constant Step
-~~~~~~~~~~~~~
-
-To specify a constant value for a traverser, use the `constant()`-step (*map*). This is often useful with conditional
-steps like <<choose-step,`choose()`-step>> or <<coalesce-step,`coalesce()`-step>>.
-
-[gremlin-groovy,modern]
-----
-g.V().choose(__.hasLabel('person'),
- __.values('name'),
- __.constant('inhuman')) <1>
-g.V().coalesce(
- __.hasLabel('person').values('name'),
- __.constant('inhuman')) <2>
-----
-
-<1> Show the names of people, but show "inhuman" for other vertices.
-<2> Same as statement 1 (unless there is a person vertex with no name).
-
-[[cyclicpath-step]]
-CyclicPath Step
-~~~~~~~~~~~~~~~
-
-image::cyclicpath-step.png[width=400]
-
-Each traverser maintains its history through the traversal over the graph -- i.e. its <<path-data-structure,path>>.
-If it is important that the traverser repeat its course, then `cyclic()`-path should be used (*filter*). The step
-analyzes the path of the traverser thus far and if there are any repeats, the traverser is filtered out over the
-traversal computation. If non-cyclic behavior is desired, see <<simplepath-step,`simplePath()`>>.
-
-[gremlin-groovy,modern]
-----
-g.V(1).both().both()
-g.V(1).both().both().cyclicPath()
-g.V(1).both().both().cyclicPath().path()
-----
-
-[[dedup-step]]
-Dedup Step
-~~~~~~~~~~
-
-With `dedup()`-step (*filter*), repeatedly seen objects are removed from the traversal stream. Note that if a
-traverser's bulk is greater than 1, then it is set to 1 before being emitted.
-
-[gremlin-groovy,modern]
-----
-g.V().values('lang')
-g.V().values('lang').dedup()
-g.V(1).repeat(bothE('created').dedup().otherV()).emit().path() <1>
-----
-
-<1> Traverse all `created` edges, but don't touch any edge twice.
-
-If a by-step modulation is provided to `dedup()`, then the object is processed accordingly prior to determining if it
-has been seen or not.
-
-[gremlin-groovy,modern]
-----
-g.V().valueMap(true, 'name')
-g.V().dedup().by(label).values('name')
-----
-
-Finally, if `dedup()` is provided an array of strings, then it will ensure that the de-duplication is not with respect
-to the current traverser object, but to the path history of the traverser.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out('created').as('b').in('created').as('c').select('a','b','c')
-g.V().as('a').out('created').as('b').in('created').as('c').dedup('a','b').select('a','b','c') <1>
-----
-
-<1> If the current `a` and `b` combination has been seen previously, then filter the traverser.
-
-[[drop-step]]
-Drop Step
-~~~~~~~~~
-
-The `drop()`-step (*filter*/*sideEffect*) is used to remove element and properties from the graph (i.e. remove). It
-is a filter step because the traversal yields no outgoing objects.
-
-[gremlin-groovy,modern]
-----
-g.V().outE().drop()
-g.E()
-g.V().properties('name').drop()
-g.V().valueMap()
-g.V().drop()
-g.V()
-----
-
-[[explain-step]]
-Explain Step
-~~~~~~~~~~~~
-
-The `explain()`-step (*sideEffect*) will return a `TraversalExplanation`. A traversal explanation details how the
-traversal (prior to `explain()`) will be compiled given the registered <<traversalstrategy,traversal strategies>>.
-A `TraversalExplanation` has a `toString()` representation with 3-columns. The first column is the
-traversal strategy being applied. The second column is the traversal strategy category: [D]ecoration, [O]ptimization,
-[P]rovider optimization, [F]inalization, and [V]erification. Finally, the third column is the state of the traversal
-post strategy application. The final traversal is the resultant execution plan.
-
-[gremlin-groovy,modern]
-----
-g.V().outE().identity().inV().count().is(gt(5)).explain()
-----
-
-For traversal profiling information, please see <<profile-step,`profile()`>>-step.
-
-[[fold-step]]
-Fold Step
-~~~~~~~~~
-
-There are situations when the traversal stream needs a "barrier" to aggregate all the objects and emit a computation
-that is a function of the aggregate. The `fold()`-step (*map*) is one particular instance of this. Please see
-<<unfold-step,`unfold()`>>-step for the inverse functionality.
-
-[gremlin-groovy,modern]
-----
-g.V(1).out('knows').values('name')
-g.V(1).out('knows').values('name').fold() <1>
-g.V(1).out('knows').values('name').fold().next().getClass() <2>
-g.V(1).out('knows').values('name').fold(0) {a,b -> a + b.length()} <3>
-g.V().values('age').fold(0) {a,b -> a + b} <4>
-g.V().values('age').fold(0, sum) <5>
-g.V().values('age').sum() <6>
-----
-
-<1> A parameterless `fold()` will aggregate all the objects into a list and then emit the list.
-<2> A verification of the type of list returned.
-<3> `fold()` can be provided two arguments -- a seed value and a reduce bi-function ("vadas" is 5 characters + "josh" with 4 characters).
-<4> What is the total age of the people in the graph?
-<5> The same as before, but using a built-in bi-function.
-<6> The same as before, but using the <<sum-step,`sum()`-step>>.
-
-[[graph-step]]
-Graph Step
-~~~~~~~~~~
-
-The `V()`-step is usually used to start a `GraphTraversal`, but can also be used mid-traversal.
-
-[gremlin-groovy,modern]
-----
-g.V().has('name', within('marko', 'vadas', 'josh')).as('person').
- V().has('name', within('lop', 'ripple')).addE('uses').from('person')
-----
-
-NOTE: Whether a mid-traversal `V()` uses an index or not, depends on a) whether suitable index exists and b) if the particular graph system provider implemented this functionality.
-
-[gremlin-groovy,modern]
-----
-g.V().has('name', within('marko', 'vadas', 'josh')).as('person').
- V().has('name', within('lop', 'ripple')).addE('uses').from('person').toString() <1>
-g.V().has('name', within('marko', 'vadas', 'josh')).as('person').
- V().has('name', within('lop', 'ripple')).addE('uses').from('person').iterate().toString() <2>
-----
-
-<1> Normally the `V()`-step will iterate over all vertices. However, graph strategies can fold `HasContainer`'s into a `GraphStep` to allow index lookups.
-<2> Whether the graph system provider supports mid-traversal `V()` index lookups or not can easily be determined by inspecting the `toString()` output of the iterated traversal. If `has` conditions were folded into the `V()`-step, an index - if one exists - will be used.
-
-[[group-step]]
-Group Step
-~~~~~~~~~~
-
-As traversers propagate across a graph as defined by a traversal, sideEffect computations are sometimes required.
-That is, the actual path taken or the current location of a traverser is not the ultimate output of the computation,
-but some other representation of the traversal. The `group()`-step (*map*/*sideEffect*) is one such sideEffect that
-organizes the objects according to some function of the object. Then, if required, that organization (a list) is
-reduced. An example is provided below.
-
-[gremlin-groovy,modern]
-----
-g.V().group().by(label) <1>
-g.V().group().by(label).by('name') <2>
-g.V().group().by(label).by(count()) <3>
-----
-
-<1> Group the vertices by their label.
-<2> For each vertex in the group, get their name.
-<3> For each grouping, what is its size?
-
-The three projection parameters available to `group()` via `by()` are:
-
-. Key-projection: What feature of the object to group on (a function that yields the map key)?
-. Value-projection: What feature of the group to store in the key-list?
-. Reduce-projection: What feature of the key-list to ultimately return?
-
-[[groupcount-step]]
-GroupCount Step
-~~~~~~~~~~~~~~~
-
-When it is important to know how many times a particular object has been at a particular part of a traversal,
-`groupCount()`-step (*map*/*sideEffect*) is used.
-
- "What is the distribution of ages in the graph?"
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').values('age').groupCount()
-g.V().hasLabel('person').groupCount().by('age') <1>
-----
-
-<1> You can also supply a pre-group projection, where the provided <<by-step,`by()`>>-modulation determines what to
-group the incoming object by.
-
-There is one person that is 32, one person that is 35, one person that is 27, and one person that is 29.
-
- "Iteratively walk the graph and count the number of times you see the second letter of each name."
-
-image::groupcount-step.png[width=420]
-
-[gremlin-groovy,modern]
-----
-g.V().repeat(both().groupCount('m').by(label)).times(10).cap('m')
-----
-
-The above is interesting in that it demonstrates the use of referencing the internal `Map<Object,Long>` of
-`groupCount()` with a string variable. Given that `groupCount()` is a sideEffect-step, it simply passes the object
-it received to its output. Internal to `groupCount()`, the object's count is incremented.
-
-[[has-step]]
-Has Step
-~~~~~~~~
-
-image::has-step.png[width=670]
-
-It is possible to filter vertices, edges, and vertex properties based on their properties using `has()`-step
-(*filter*). There are numerous variations on `has()` including:
-
- * `has(key,value)`: Remove the traverser if its element does not have the provided key/value property.
- * `has(key,predicate)`: Remove the traverser if its element does not have a key value that satisfies the bi-predicate.
- * `hasLabel(labels...)`: Remove the traverser if its element does not have any of the labels.
- * `hasId(ids...)`: Remove the traverser if its element does not have any of the ids.
- * `hasKey(keys...)`: Remove the traverser if its property does not have any of the keys.
- * `hasValue(values...)`: Remove the traverser if its property does not have any of the values.
- * `has(key)`: Remove the traverser if its element does not have a value for the key.
- * `hasNot(key)`: Remove the traverser if its element has a value for the key.
- * `has(key, traversal)`: Remove the traverser if its object does not yield a result through the traversal off the property value.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person')
-g.V().hasLabel('person').out().has('name',within('vadas','josh'))
-g.V().hasLabel('person').out().has('name',within('vadas','josh')).
- outE().hasLabel('created')
-g.V().has('age',inside(20,30)).values('age') <1>
-g.V().has('age',outside(20,30)).values('age') <2>
-g.V().has('name',within('josh','marko')).valueMap() <3>
-g.V().has('name',without('josh','marko')).valueMap() <4>
-g.V().has('name',not(within('josh','marko'))).valueMap() <5>
-----
-
-<1> Find all vertices whose ages are between 20 (inclusive) and 30 (exclusive).
-<2> Find all vertices whose ages are not between 20 (inclusive) and 30 (exclusive).
-<3> Find all vertices whose names are exact matches to any names in the the collection `[josh,marko]`, display all
-the key,value pairs for those verticies.
-<4> Find all vertices whose names are not in the collection `[josh,marko]`, display all the key,value pairs for those vertices.
-<5> Same as the prior example save using `not` on `within` to yield `without`.
-
-TinkerPop does not support a regular expression predicate, although specific graph databases that leverage TinkerPop
-may provide a partial match extension.
-
-[[inject-step]]
-Inject Step
-~~~~~~~~~~~
-
-image::inject-step.png[width=800]
-
-One of the major features of TinkerPop3 is "injectable steps." This makes it possible to insert objects arbitrarily
-into a traversal stream. In general, `inject()`-step (*sideEffect*) exists and a few examples are provided below.
-
-[gremlin-groovy,modern]
-----
-g.V(4).out().values('name').inject('daniel')
-g.V(4).out().values('name').inject('daniel').map {it.get().length()}
-g.V(4).out().values('name').inject('daniel').map {it.get().length()}.path()
-----
-
-In the last example above, note that the path starting with `daniel` is only of length 2. This is because the
-`daniel` string was inserted half-way in the traversal. Finally, a typical use case is provided below -- when the
-start of the traversal is not a graph object.
-
-[gremlin-groovy,modern]
-----
-inject(1,2)
-inject(1,2).map {it.get() + 1}
-inject(1,2).map {it.get() + 1}.map {g.V(it.get()).next()}.values('name')
-----
-
-[[is-step]]
-Is Step
-~~~~~~~
-
-It is possible to filter scalar values using `is()`-step (*filter*).
-
-[gremlin-groovy,modern]
-----
-g.V().values('age').is(32)
-g.V().values('age').is(lte(30))
-g.V().values('age').is(inside(30, 40))
-g.V().where(__.in('created').count().is(1)).values('name') <1>
-g.V().where(__.in('created').count().is(gte(2))).values('name') <2>
-g.V().where(__.in('created').values('age').
- mean().is(inside(30d, 35d))).values('name') <3>
-----
-
-<1> Find projects having exactly one contributor.
-<2> Find projects having two or more contributors.
-<3> Find projects whose contributors average age is between 30 and 35.
-
-[[limit-step]]
-Limit Step
-~~~~~~~~~~
-
-The `limit()`-step is analogous to <<range-step,`range()`-step>> save that the lower end range is set to 0.
-
-[gremlin-groovy,modern]
-----
-g.V().limit(2)
-g.V().range(0, 2)
-g.V().limit(2).toString()
-----
-
-The `limit()`-step can also be applied with `Scope.local`, in which case it operates on the incoming collection.
-The examples below use the <<the-crew-toy-graph,The Crew>> toy data set.
-
-[gremlin-groovy,theCrew]
-----
-g.V().valueMap().select('location').limit(local,2) <1>
-g.V().valueMap().limit(local, 1) <2>
-----
-
-<1> `List<String>` for each vertex containing the first two locations.
-<2> `Map<String, Object>` for each vertex, but containing only the first property value.
-
-[[local-step]]
-Local Step
-~~~~~~~~~~
-
-image::local-step.png[width=450]
-
-A `GraphTraversal` operates on a continuous stream of objects. In many situations, it is important to operate on a
-single element within that stream. To do such object-local traversal computations, `local()`-step exists (*branch*).
-Note that the examples below use the <<the-crew-toy-graph,The Crew>> toy data set.
-
-[gremlin-groovy,theCrew]
-----
-g.V().as('person').
- properties('location').order().by('startTime',incr).limit(2).value().as('location').
- select('person','location').by('name').by() <1>
-g.V().as('person').
- local(properties('location').order().by('startTime',incr).limit(2)).value().as('location').
- select('person','location').by('name').by() <2>
-----
-
-<1> Get the first two people and their respective location according to the most historic location start time.
-<2> For every person, get their two most historic locations.
-
-The two traversals above look nearly identical save the inclusion of `local()` which wraps a section of the traversal
-in a object-local traversal. As such, the `order().by()` and the `limit()` refer to a particular object, not to the
-stream as a whole.
-
-WARNING: The anonymous traversal of `local()` processes the current object "locally." In OLAP, where the atomic unit
-of computing is the the vertex and its local "star graph," it is important that the anonymous traversal does not leave
-the confines of the vertex's star graph. In other words, it can not traverse to an adjacent vertex's properties or edges.
-
-[[match-step]]
-Match Step
-~~~~~~~~~~
-
-The `match()`-step (*map*) provides a more link:http://en.wikipedia.org/wiki/Declarative_programming[declarative]
-form of graph querying based on the notion of link:http://en.wikipedia.org/wiki/Pattern_matching[pattern matching].
-With `match()`, the user provides a collection of "traversal fragments," called patterns, that have variables defined
-that must hold true throughout the duration of the `match()`. When a traverser is in `match()`, a registered
-`MatchAlgorithm` analyzes the current state of the traverser (i.e. its history based on its
-<<path-data-structure,path data>>), the runtime statistics of the traversal patterns, and returns a traversal-pattern
-that the traverser should try next. The default `MatchAlgorithm` provided is called `CountMatchAlgorithm` and it
-dynamically revises the pattern execution plan by sorting the patterns according to their filtering capabilities
-(i.e. largest set reduction patterns execute first). For very large graphs, where the developer is uncertain of the
-statistics of the graph (e.g. how many `knows`-edges vs. `worksFor`-edges exist in the graph), it is advantageous to
-use `match()`, as an optimal plan will be determined automatically. Furthermore, some queries are much easier to
-express via `match()` than with single-path traversals.
-
- "Who created a project named 'lop' that was also created by someone who is 29 years old? Return the two creators."
-
-image::match-step.png[width=500]
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('a').out('created').as('b'),
- __.as('b').has('name', 'lop'),
- __.as('b').in('created').as('c'),
- __.as('c').has('age', 29)).
- select('a','c').by('name')
-----
-
-Note that the above can also be more concisely written as below which demonstrates that standard inner-traversals can
-be arbitrarily defined.
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('a').out('created').has('name', 'lop').as('b'),
- __.as('b').in('created').has('age', 29).as('c')).
- select('a','c').by('name')
-----
-
-In order to improve readability, `as()`-steps can be given meaningful labels which better reflect your domain. The
-previous query can thus be written in a more expressive way as shown below.
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('creators').out('created').has('name', 'lop').as('projects'), <1>
- __.as('projects').in('created').has('age', 29).as('cocreators')). <2>
- select('creators','cocreators').by('name') <3>
-----
-
-<1> Find vertices that created something and match them as 'creators', then find out what they created which is
-named 'lop' and match these vertices as 'projects'.
-<2> Using these 'projects' vertices, find out their creators aged 29 and remember these as 'cocreators'.
-<3> Return the name of both 'creators' and 'cocreators'.
-
-[[grateful-dead]]
-.Grateful Dead
-image::grateful-dead-schema.png[width=475]
-
-`MatchStep` brings functionality similar to link:http://en.wikipedia.org/wiki/SPARQL[SPARQL] to Gremlin. Like SPARQL,
-MatchStep conjoins a set of patterns applied to a graph. For example, the following traversal finds exactly those
-songs which Jerry Garcia has both sung and written (using the Grateful Dead graph distributed in the `data/` directory):
-
-[gremlin-groovy]
-----
-graph.io(graphml()).readGraph('data/grateful-dead.xml')
-g = graph.traversal(standard())
-g.V().match(
- __.as('a').has('name', 'Garcia'),
- __.as('a').in('writtenBy').as('b'),
- __.as('a').in('sungBy').as('b')).
- select('b').values('name')
-----
-
-Among the features which differentiate `match()` from SPARQL are:
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('a').out('created').has('name','lop').as('b'), <1>
- __.as('b').in('created').has('age', 29).as('c'),
- __.as('c').repeat(out()).times(2)). <2>
- select('c').out('knows').dedup().values('name') <3>
-----
-
-<1> *Patterns of arbitrary complexity*: `match()` is not restricted to triple patterns or property paths.
-<2> *Recursion support*: `match()` supports the branch-based steps within a pattern, including `repeat()`.
-<3> *Imperative/declarative hybrid*: Before and after a `match()`, it is possible to leverage classic Gremlin traversals.
-
-To extend point #3, it is possible to support going from imperative, to declarative, to imperative, ad infinitum.
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('a').out('knows').as('b'),
- __.as('b').out('created').has('name','lop')).
- select('b').out('created').
- match(
- __.as('x').in('created').as('y'),
- __.as('y').out('knows').as('z')).
- select('z').values('name')
-----
-
-IMPORTANT: The `match()`-step is stateless. The variable bindings of the traversal patterns are stored in the path
-history of the traverser. As such, the variables used over all `match()`-steps within a traversal are globally unique.
-A benefit of this is that subsequent `where()`, `select()`, `match()`, etc. steps can leverage the same variables in
-their analysis.
-
-Like all other steps in Gremlin, `match()` is a function and thus, `match()` within `match()` is a natural consequence
-of Gremlin's functional foundation (i.e. recursive matching).
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('a').out('knows').as('b'),
- __.as('b').out('created').has('name','lop'),
- __.as('b').match(
- __.as('b').out('created').as('c'),
- __.as('c').has('name','ripple')).
- select('c').as('c')).
- select('a','c').by('name')
-----
-
-If a step-labeled traversal proceeds the `match()`-step and the traverser entering the `match()` is destined to bind
-to a particular variable, then the previous step should be labeled accordingly.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out('knows').as('b').
- match(
- __.as('b').out('created').as('c'),
- __.not(__.as('c').in('created').as('a'))).
- select('a','b','c').by('name')
-----
-
-There are three types of `match()` traversal patterns.
-
- . `as('a')...as('b')`: both the start and end of the traversal have a declared variable.
- . `as('a')...`: only the start of the traversal has a declared variable.
- . `...`: there are no declared variables.
-
-If a variable is at the start of a traversal pattern it *must* exist as a label in the path history of the traverser
-else the traverser can not go down that path. If a variable is at the end of a traversal pattern then if the variable
-exists in the path history of the traverser, the traverser's current location *must* match (i.e. equal) its historic
-location at that same label. However, if the variable does not exist in the path history of the traverser, then the
-current location is labeled as the variable and thus, becomes a bound variable for subsequent traversal patterns. If a
-traversal pattern does not have an end label, then the traverser must simply "survive" the pattern (i.e. not be
-filtered) to continue to the next pattern. If a traversal pattern does not have a start label, then the traverser
-can go down that path at any point, but will only go down that pattern once as a traversal pattern is executed once
-and only once for the history of the traverser. Typically, traversal patterns that do not have a start and end label
-are used in conjunction with `and()`, `or()`, and `where()`. Once the traverser has "survived" all the patterns (or at
-least one for `or()`), `match()`-step analyzes the traverser's path history and emits a `Map<String,Object>` of the
-variable bindings to the next step in the traversal.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out().as('b'). <1>
- match( <2>
- __.as('a').out().count().as('c'), <3>
- __.not(__.as('a').in().as('b')), <4>
- or( <5>
- __.as('a').out('knows').as('b'),
- __.as('b').in().count().as('c').and().as('c').is(gt(2)))). <6>
- dedup('a','c'). <7>
- select('a','b','c').by('name').by('name').by() <8>
-----
-
-<1> A standard, step-labeled traversal can come prior to `match()`.
-<2> If the traverser's path prior to entering `match()` has requisite label values, then those historic values are bound.
-<3> It is possible to use <<a-note-on-barrier-steps,barrier steps>> though they are computed locally to the pattern (as one would expect).
-<4> It is possible to `not()` a pattern.
-<5> It is possible to nest `and()`- and `or()`-steps for conjunction matching.
-<6> Both infix and prefix conjunction notation is supported.
-<7> It is possible to "distinct" the specified label combination.
-<8> The bound values are of different types -- vertex ("a"), vertex ("b"), long ("c").
-
-[[using-where-with-match]]
-Using Where with Match
-^^^^^^^^^^^^^^^^^^^^^^
-
-Match is typically used in conjunction with both `select()` (demonstrated previously) and `where()` (presented here).
-A `where()`-step allows the user to further constrain the result set provided by `match()`.
-
-[gremlin-groovy,modern]
-----
-g.V().match(
- __.as('a').out('created').as('b'),
- __.as('b').in('created').as('c')).
- where('a', neq('c')).
- select('a','c').by('name')
-----
-
-The `where()`-step can take either a `P`-predicate (example above) or a `Traversal` (example below). Using
-`MatchPredicateStrategy`, `where()`-clauses are automatically folded into `match()` and thus, subject to the query
-optimizer within `match()`-step.
-
-[gremlin-groovy,modern]
-----
-traversal = g.V().match(
- __.as('a').has(label,'person'), <1>
- __.as('a').out('created').as('b'),
- __.as('b').in('created').as('c')).
- where(__.as('a').out('knows').as('c')). <2>
- select('a','c').by('name'); null <3>
-traversal.toString() <4>
-traversal <5> <6>
-traversal.toString() <7>
-----
-
-<1> Any `has()`-step traversal patterns that start with the match-key are pulled out of `match()` to enable the graph
-system to leverage the filter for index lookups.
-<2> A `where()`-step with a traversal containing variable bindings declared in `match()`.
-<3> A useful trick to ensure that the traversal is not iterated by Gremlin Console.
-<4> The string representation of the traversal prior to its strategies being applied.
-<5> The Gremlin Console will automatically iterate anything that is an iterator or is iterable.
-<6> Both marko and josh are co-developers and marko knows josh.
-<7> The string representation of the traversal after the strategies have been applied (and thus, `where()` is folded into `match()`)
-
-IMPORTANT: A `where()`-step is a filter and thus, variables within a `where()` clause are not globally bound to the
-path of the traverser in `match()`. As such, `where()`-steps in `match()` are used for filtering, not binding.
-
-[[max-step]]
-Max Step
-~~~~~~~~
-
-The `max()`-step (*map*) operates on a stream of numbers and determines which is the largest number in the stream.
-
-[gremlin-groovy,modern]
-----
-g.V().values('age').max()
-g.V().repeat(both()).times(3).values('age').max()
-----
-
-IMPORTANT: `max(local)` determines the max of the current, local object (not the objects in the traversal stream).
-This works for `Collection` and `Number`-type objects. For any other object, a max of `Double.NaN` is returned.
-
-[[mean-step]]
-Mean Step
-~~~~~~~~~
-
-The `mean()`-step (*map*) operates on a stream of numbers and determines the average of those numbers.
-
-[gremlin-groovy,modern]
-----
-g.V().values('age').mean()
-g.V().repeat(both()).times(3).values('age').mean() <1>
-g.V().repeat(both()).times(3).values('age').dedup().mean()
-----
-
-<1> Realize that traversers are being bulked by `repeat()`. There may be more of a particular number than another,
-thus altering the average.
-
-IMPORTANT: `mean(local)` determines the mean of the current, local object (not the objects in the traversal stream).
-This works for `Collection` and `Number`-type objects. For any other object, a mean of `Double.NaN` is returned.
-
-[[min-step]]
-Min Step
-~~~~~~~~
-
-The `min()`-step (*map*) operates on a stream of numbers and determines which is the smallest number in the stream.
-
-[gremlin-groovy,modern]
-----
-g.V().values('age').min()
-g.V().repeat(both()).times(3).values('age').min()
-----
-
-IMPORTANT: `min(local)` determines the min of the current, local object (not the objects in the traversal stream).
-This works for `Collection` and `Number`-type objects. For any other object, a min of `Double.NaN` is returned.
-
-[[or-step]]
-Or Step
-~~~~~~~
-
-The `or()`-step ensures that at least one of the provided traversals yield a result (*filter*). Please see
-<<and-step,`and()`>> for and-semantics.
-
-[gremlin-groovy,modern]
-----
-g.V().or(
- __.outE('created'),
- __.inE('created').count().is(gt(1))).
- values('name')
-----
-
-The `or()`-step can take an arbitrary number of traversals. At least one of the traversals must produce at least one
-output for the original traverser to pass to the next step.
-
-An link:http://en.wikipedia.org/wiki/Infix_notation[infix notation] can be used as well. Though, with infix notation,
-only two traversals can be or'd together.
-
-[gremlin-groovy,modern]
-----
-g.V().where(outE('created').or().outE('knows')).values('name')
-----
-
-[[order-step]]
-Order Step
-~~~~~~~~~~
-
-When the objects of the traversal stream need to be sorted, `order()`-step (*map*) can be leveraged.
-
-[gremlin-groovy,modern]
-----
-g.V().values('name').order()
-g.V().values('name').order().by(decr)
-g.V().hasLabel('person').order().by('age', incr).values('name')
-----
-
-One of the most traversed objects in a traversal is an `Element`. An element can have properties associated with it
-(i.e. key/value pairs). In many situations, it is desirable to sort an element traversal stream according to a
-comparison of their properties.
-
-[gremlin-groovy,modern]
-----
-g.V().values('name')
-g.V().order().by('name',incr).values('name')
-g.V().order().by('name',decr).values('name')
-----
-
-The `order()`-step allows the user to provide an arbitrary number of comparators for primary, secondary, etc. sorting.
-In the example below, the primary ordering is based on the outgoing created-edge count. The secondary ordering is
-based on the age of the person.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').order().by(outE('created').count(), incr).
- by('age', incr).values('name')
-g.V().hasLabel('person').order().by(outE('created').count(), incr).
- by('age', decr).values('name')
-----
-
-Randomizing the order of the traversers at a particular point in the traversal is possible with `Order.shuffle`.
-
-[gremlin-groovy,modern]
-----
-g.V().hasLabel('person').order().by(shuffle)
-g.V().hasLabel('person').order().by(shuffle)
-----
-
-IMPORTANT: `order(local)` orders the current, local object (not the objects in the traversal stream). This works for
-`Collection`- and `Map`-type objects. For any other object, the object is returned unchanged.
-
-[[path-step]]
-Path Step
-~~~~~~~~~
-
-A traverser is transformed as it moves through a series of steps within a traversal. The history of the traverser is
-realized by examining its path with `path()`-step (*map*).
-
-image::path-step.png[width=650]
-
-[gremlin-groovy,modern]
-----
-g.V().out().out().values('name')
-g.V().out().out().values('name').path()
-----
-
-If edges are required in the path, then be sure to traverser those edges explicitly.
-
-[gremlin-groovy,modern]
-----
-g.V().outE().inV().outE().inV().path()
-----
-
-It is possible to post-process the elements of the path in a round-robin fashion via `by()`.
-
-[gremlin-groovy,modern]
-----
-g.V().out().out().path().by('name').by('age')
-----
-
-Finally, because `by()`-based post-processing, nothing prevents triggering yet another traversal. In the traversal
-below, for each element of the path traversed thus far, if its a person (as determined by having an `age`-property),
-then get all of their creations, else if its a creation, get all the people that created it.
-
-[gremlin-groovy,modern]
-----
-g.V().out().out().path().by(
- choose(hasLabel('person'),
- out('created').values('name'),
- __.in('created').values('name')).fold())
-----
-
-WARNING: Generating path information is expensive as the history of the traverser is stored into a Java list. With
-numerous traversers, there are numerous lists. Moreover, in an OLAP <<graphcomputer,`GraphComputer`>> environment
-this becomes exceedingly prohibitive as there are traversers emanating from all vertices in the graph in parallel.
-In OLAP there are optimizations provided for traverser populations, but when paths are calculated (and each traverser
-is unique due to its history), then these optimizations are no longer possible.
-
-[[path-data-structure]]
-Path Data Structure
-^^^^^^^^^^^^^^^^^^^
-
-The `Path` data structure is an ordered list of objects, where each object is associated to a `Set<String>` of
-labels. An example is presented below to demonstrate both the `Path` API as well as how a traversal yields labeled paths.
-
-image::path-data-structure.png[width=350]
-
-[gremlin-groovy,modern]
-----
-path = g.V(1).as('a').has('name').as('b').
- out('knows').out('created').as('c').
- has('name','ripple').values('name').as('d').
- identity().as('e').path().next()
-path.size()
-path.objects()
-path.labels()
-path.a
-path.b
-path.c
-path.d == path.e
-----
-
-[[profile-step]]
-Profile Step
-~~~~~~~~~~~~
-
-The `profile()`-step (*sideEffect*) exists to allow developers to profile their traversals to determine statistical
-information like step runtime, counts, etc.
-
-WARNING: Profiling a Traversal will impede the Traversal's performance. This overhead is mostly excluded from the
-profile results, but durations are not exact. Thus, durations are best considered in relation to each other.
-
-[gremlin-groovy,modern]
-----
-g.V().out('created').repeat(both()).times(3).hasLabel('person').values('age').sum().profile().cap(TraversalMetrics.METRICS_KEY)
-----
-
-The `profile()`-step generates a `TraversalMetrics` sideEffect object that contains the following information:
-
-* `Step`: A step within the traversal being profiled.
-* `Count`: The number of _represented_ traversers that passed through the step.
-* `Traversers`: The number of traversers that passed through the step.
-* `Time (ms)`: The total time the step was actively executing its behavior.
-* `% Dur`: The percentage of total time spent in the step.
-
-image:gremlin-exercise.png[width=120,float=left] It is important to understand the difference between `Count`
-and `Traversers`. Traversers can be merged and as such, when two traversers are "the same" they may be aggregated
-into a single traverser. That new traverser has a `Traverser.bulk()` that is the sum of the two merged traverser
-bulks. On the other hand, the `Count` represents the sum of all `Traverser.bulk()` results and thus, expresses the
-number of "represented" (not enumerated) traversers. `Traversers` will always be less than or equal to `Count`.
-
-For traversal compilation information, please see <<explain-step,`explain()`>>-step.
-
-[[range-step]]
-Range Step
-~~~~~~~~~~
-
-As traversers propagate through the traversal, it is possible to only allow a certain number of them to pass through
-with `range()`-step (*filter*). When the low-end of the range is not met, objects are continued to be iterated. When
-within the low and high range (both inclusive), traversers are emitted. Finally, when above the high range, the
-traversal breaks out of iteration.
-
-[gremlin-groovy,modern]
-----
-g.V().range(0,3)
-g.V().range(1,3)
-g.V().repeat(both()).times(1000000).emit().range(6,10)
-----
-
-The `range()`-step can also be applied with `Scope.local`, in which case it operates on the incoming collection.
-For example, it is possible to produce a `Map<String, String>` for each traversed path, but containing only the second
-property value (the "b" step).
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out().as('b').in().as('c').select('a','b','c').by('name').range(local,1,2)
-----
-
-The next example uses the <<the-crew-toy-graph,The Crew>> toy data set. It produces a `List<String>` containing the
-second and third location for each vertex.
-
-[gremlin-groovy,theCrew]
-----
-g.V().valueMap().select('location').range(local, 1, 3)
-----
-
-[[repeat-step]]
-Repeat Step
-~~~~~~~~~~~
-
-image::gremlin-fade.png[width=350]
-
-The `repeat()`-step (*branch*) is used for looping over a traversal given some break predicate. Below are some
-examples of `repeat()`-step in action.
-
-[gremlin-groovy,modern]
-----
-g.V(1).repeat(out()).times(2).path().by('name') <1>
-g.V().until(has('name','ripple')).
- repeat(out()).path().by('name') <2>
-----
-
-<1> do-while semantics stating to do `out()` 2 times.
-<2> while-do semantics stating to break if the traverser is at a vertex named "ripple".
-
-IMPORTANT: There are two modulators for `repeat()`: `until()` and `emit()`. If `until()` comes after `repeat()` it is
-do/while looping. If `until()` comes before `repeat()` it is while/do looping. If `emit()` is placed after `repeat()`,
-it is evaluated on the traversers leaving the repeat-traversal. If `emit()` is placed before `repeat()`, it is
-evaluated on the traversers prior to entering the repeat-traversal.
-
-The `repeat()`-step also supports an "emit predicate", where the predicate for an empty argument `emit()` is
-`true` (i.e. `emit() == emit{true}`). With `emit()`, the traverser is split in two -- the traverser exits the code
-block as well as continues back within the code block (assuming `until()` holds true).
-
-[gremlin-groovy,modern]
-----
-g.V(1).repeat(out()).times(2).emit().path().by('name') <1>
-g.V(1).emit().repeat(out()).times(2).path().by('name') <2>
-----
-
-<1> The `emit()` comes after `repeat()` and thus, emission happens after the `repeat()` traversal is executed. Thus,
-no one vertex paths exist.
-<2> The `emit()` comes before `repeat()` and thus, emission happens prior to the `repeat()` traversal being executed.
-Thus, one vertex paths exist.
-
-The `emit()`-modulator can take an arbitrary predicate.
-
-[gremlin-groovy,modern]
-----
-g.V(1).repeat(out()).times(2).emit(has('lang')).path().by('name')
-----
-
-image::repeat-step.png[width=500]
-
-[gremlin-groovy,modern]
-----
-g.V(1).repeat(out()).times(2).emit().path().by('name')
-----
-
-The first time through the `repeat()`, the vertices lop, vadas, and josh are seen. Given that `loops==1`, the
-traverser repeats. However, because the emit-predicate is declared true, those vertices are emitted. The next time through
- `repeat()`, the vertices traversed are ripple and lop (Josh's created projects, as lop and vadas have no out edges).
- Given that `loops==2`, the until-predicate fails and ripple and lop are emitted.
-Therefore, the traverser has seen the vertices: lop, vadas, josh, ripple, and lop.
-
-Finally, note that both `emit()` and `until()` can take a traversal and in such, situations, the predicate is
-determined by `traversal.hasNext()`. A few examples are provided below.
-
-[gremlin-groovy,modern]
-----
-g.V(1).repeat(out()).until(hasLabel('software')).path().by('name') <1>
-g.V(1).emit(hasLabel('person')).repeat(out()).path().by('name') <2>
-g.V(1).repeat(out()).until(outE().count().is(0)).path().by('name') <3>
-----
-
-<1> Starting from vertex 1, keep taking outgoing edges until a software vertex is reached.
-<2> Starting from vertex 1, and in an infinite loop, emit the vertex if it is a person and then traverser the outgoing edges.
-<3> Starting from vertex 1, keep taking outgoing edges until a vertex is reached that has no more outgoing edges.
-
-WARNING: The anonymous traversal of `emit()` and `until()` (not `repeat()`) process their current objects "locally."
-In OLAP, where the atomic unit of computing is the the vertex and its local "star graph," it is important that the
-anonymous traversals do not leave the confines of the vertex's star graph. In other words, they can not traverse to
-an adjacent vertex's properties or edges.
-
-[[sack-step]]
-Sack Step
-~~~~~~~~~
-
-image:gremlin-sacks-running.png[width=175,float=right] A traverser can contain a local data structure called a "sack".
-The `sack()`-step is used to read and write sacks (*sideEffect* or *map*). Each sack of each traverser is created
-when using `GraphTraversal.withSack(initialValueSupplier,splitOperator?,mergeOperator?)`.
-
-* *Initial value supplier*: A `Supplier` providing the initial value of each traverser's sack.
-* *Split operator*: a `UnaryOperator` that clones the traverser's sack when the traverser splits. If no split operator
-is provided, then `UnaryOperator.identity()` is assumed.
-* *Merge operator*: A `BinaryOperator` that unites two traverser's sack when they are merged. If no merge operator is
-provided, then traversers with sacks can not be merged.
-
-Two trivial examples are presented below to demonstrate the *initial value supplier*. In the first example below, a
-traverser is created at each vertex in the graph (`g.V()`), with a 1.0 sack (`withSack(1.0f)`), and then the sack
-value is accessed (`sack()`). In the second example, a random float supplier is used to generate sack values.
-
-[gremlin-groovy,modern]
-----
-g.withSack(1.0f).V().sack()
-rand = new Random()
-g.withSack {rand.nextFloat()}.V().sack()
-----
-
-A more complicated initial value supplier example is presented below where the sack values are used in a running
-computation and then emitted at the end of the traversal. When an edge is traversed, the edge weight is multiplied
-by the sack value (`sack(mult).by('weight')`). Note that the <<by-step,`by()`>>-modulator can be any arbitrary traversal.
-
-[gremlin-groovy,modern]
-----
-g.withSack(1.0f).V().repeat(outE().sack(mult).by('weight').inV()).times(2)
-g.withSack(1.0f).V().repeat(outE().sack(mult).by('weight').inV()).times(2).sack()
-g.withSack(1.0f).V().repeat(outE().sack(mult).by('weight').inV()).times(2).path().
- by().by('weight')
-----
-
-image:gremlin-sacks-standing.png[width=100,float=left] When complex objects are used (i.e. non-primitives), then a
-*split operator* should be defined to ensure that each traverser gets a clone of its parent's sack. The first example
-does not use a split operator and as such, the same map is propagated to all traversers (a global data structure). The
-second example, demonstrates how `Map.clone()` ensures that each traverser's sack contains a unique, local sack.
-
-[gremlin-groovy,modern]
-----
-g.withSack {[:]}.V().out().out().
- sack {m,v -> m[v.value('name')] = v.value('lang'); m}.sack() // BAD: single map
-g.withSack {[:]}{it.clone()}.V().out().out().
- sack {m,v -> m[v.value('name')] = v.value('lang'); m}.sack() // GOOD: cloned map
-----
-
-NOTE: For primitives (i.e. integers, longs, floats, etc.), a split operator is not required as a primitives are
-encoded in the memory address of the sack, not as a reference to an object.
-
-If a *merge operator* is not provided, then traversers with sacks can not be bulked. However, in many situations,
-merging the sacks of two traversers at the same location is algorithmically sound and good to provide so as to gain
-the bulking optimization. In the examples below, the binary merge operator is `Operator.sum`. Thus, when two traverser
-merge, their respective sacks are added together.
-
-[gremlin-groovy,modern]
-----
-g.withSack(1.0f,sum).V(1).local(outE('knows').barrier(normSack).inV()) <1>
-g.withSack(1.0f,sum).V(1).local(outE('knows').barrier(normSack).inV()).sack() <2>
-g.withSack(1.0f,sum).V(1).local(outE('knows').barrier(normSack).inV()).in('knows') <3>
-g.withSack(1.0f,sum).V(1).local(outE('knows').barrier(normSack).inV()).in('knows').sack() <4>
-g.withSack(1.0f,sum).V(1).local(outE('knows').barrier(normSack).inV()).in('knows').barrier().sack() <5>
-g.withBulk(false).withSack(1.0f,sum).V(1).local(outE('knows').barrier(normSack).inV()).in('knows').barrier().sack() <6>
-----
-
-<1> The knows-adjacent vertices of vertex 1 are vertices 2 and 4.
-<2> The `local(...barrier(normSack)...)` ensures that all traversers leaving vertex 1 have an evenly distributed amount of the initial 1.0 "energy" (50-50).
-<3> Going from vertices 2 and 4 yield two traversers at vertex 1.
-<4> Those two traversers each have a sack of 0.5.
-<5> The `barrier()` merges the two traversers at vertex 1 into a single traverser whose sack is 1.0.
-<6> There is now a single traverser with bulk of 2 and sack of 1.0 and thus, setting `withBulk(false)` yields the expected 1.0.
-
-
-[[sample-step]]
-Sample Step
-~~~~~~~~~~~
-
-The `sample()`-step is useful for sampling some number of traversers previous in the traversal.
-
-[gremlin-groovy,modern]
-----
-g.V().outE().sample(1).values('weight')
-g.V().outE().sample(1).by('weight').values('weight')
-g.V().outE().sample(2).by('weight').values('weight')
-----
-
-One of the more interesting use cases for `sample()` is when it is used in conjunction with <<local-step,`local()`>>.
-The combination of the two steps supports the execution of link:http://en.wikipedia.org/wiki/Random_walk[random walks].
-In the example below, the traversal starts are vertex 1 and selects one edge to traverse based on a probability
-distribution generated by the weights of the edges. The output is always a single path as by selecting a single edge,
-the traverser never splits and continues down a single path in the graph.
-
-[gremlin-groovy,modern]
-----
-g.V(1).repeat(local(
- bothE().sample(1).by('weight').otherV()
- )).times(5)
-g.V(1).repeat(local(
- bothE().sample(1).by('weight').otherV()
- )).times(5).path()
-g.V(1).repeat(local(
- bothE().sample(1).by('weight').otherV()
- )).times(10).path()
-----
-
-[[select-step]]
-Select Step
-~~~~~~~~~~~
-
-link:http://en.wikipedia.org/wiki/Functional_programming[Functional languages] make use of function composition and
-lazy evaluation to create complex computations from primitive operations. This is exactly what `Traversal` does. One
-of the differentiating aspects of Gremlin's data flow approach to graph processing is that the flow need not always go
-"forward," but in fact, can go back to a previously seen area of computation. Examples include <<path-step,`path()`>>
-as well as the `select()`-step (*map*). There are two general ways to use `select()`-step.
-
-. Select labeled steps within a path (as defined by `as()` in a traversal).
-. Select objects out of a `Map<String,Object>` flow (i.e. a sub-map).
-
-The first use case is demonstrated via example below.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out().as('b').out().as('c') // no select
-g.V().as('a').out().as('b').out().as('c').select('a','b','c')
-g.V().as('a').out().as('b').out().as('c').select('a','b')
-g.V().as('a').out().as('b').out().as('c').select('a','b').by('name')
-g.V().as('a').out().as('b').out().as('c').select('a') <1>
-----
-
-<1> If the selection is one step, no map is returned.
-
-When there is only one label selected, then a single object is returned. This is useful for stepping back in a
-computation and easily moving forward again on the object reverted to.
-
-[gremlin-groovy,modern]
-----
-g.V().out().out()
-g.V().out().out().path()
-g.V().as('x').out().out().select('x')
-g.V().out().as('x').out().select('x')
-g.V().out().out().as('x').select('x') // pointless
-----
-
-NOTE: When executing a traversal with `select()` on a standard traversal engine (i.e. OLTP), `select()` will do its
-best to avoid calculating the path history and instead, will rely on a global data structure for storing the currently
-selected object. As such, if only a subset of the path walked is required, `select()` should be used over the more
-resource intensive <<path-step,`path()`>>-step.
-
-When the set of keys or values (i.e. columns) of a path or map are needed, use `select(keys)` and `select(values)`,
-respectively. This is especially useful when one is only interested in the top N elements in a `groupCount()`
-ranking.
-
-[gremlin-groovy]
-----
-graph.io(graphml()).readGraph('data/grateful-dead.xml')
-g = graph.traversal()
-g.V().hasLabel('song').out('followedBy').groupCount().by('name').
- order(local).by(valueDecr).limit(local, 5)
-g.V().hasLabel('song').out('followedBy').groupCount().by('name').
- order(local).by(valueDecr).limit(local, 5).select(keys)
-g.V().hasLabel('song').out('followedBy').groupCount().by('name').
- order(local).by(valueDecr).limit(local, 5).select(keys).unfold()
-----
-
-Similarly, for extracting the values from a path or map.
-
-[gremlin-groovy]
-----
-graph.io(graphml()).readGraph('data/grateful-dead.xml')
-g = graph.traversal()
-g.V().hasLabel('song').out('sungBy').groupCount().by('name') <1>
-g.V().hasLabel('song').out('sungBy').groupCount().by('name').select(values) <2>
-g.V().hasLabel('song').out('sungBy').groupCount().by('name').select(values).unfold().
- groupCount().order(local).by(valueDecr).limit(local, 5) <3>
-----
-
-<1> Which artist sung how many songs?
-<2> Get an anonymized set of song repertoire sizes.
-<3> What are the 5 most common song repertoire sizes?
-
-CAUTION: Note that `by()`-modulation is not supported with `select(keys)` and `select(values)`.
-
-[[using-where-with-select]]
-Using Where with Select
-^^^^^^^^^^^^^^^^^^^^^^^
-
-Like <<match-step,`match()`>>-step, it is possible to use `where()`, as where is a filter that processes
-`Map<String,Object>` streams.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out('created').in('created').as('b').select('a','b').by('name') <1>
-g.V().as('a').out('created').in('created').as('b').
- select('a','b').by('name').where('a',neq('b')) <2>
-g.V().as('a').out('created').in('created').as('b').
- select('a','b'). <3>
- where('a',neq('b')).
- where(__.as('a').out('knows').as('b')).
- select('a','b').by('name')
-----
-
-<1> A standard `select()` that generates a `Map<String,Object>` of variables bindings in the path (i.e. `a` and `b`)
-for the sake of a running example.
-<2> The `select().by('name')` projects each binding vertex to their name property value and `where()` operates to
-ensure respective `a` and `b` strings are not the same.
-<3> The first `select()` projects a vertex binding set. A binding is filtered if `a` vertex equals `b` vertex. A
-binding is filtered if `a` doesn't know `b`. The second and final `select()` projects the name of the vertices.
-
-[[simplepath-step]]
-SimplePath Step
-~~~~~~~~~~~~~~~
-
-image::simplepath-step.png[width=400]
-
-When it is important that a traverser not repeat its path through the graph, `simplePath()`-step should be used
-(*filter*). The <<path-data-structure,path>> information of the traverser is analyzed and if the path has repeated
-objects in it, the traverser is filtered. If cyclic behavior is desired, see <<cyclicpath-step,`cyclicPath()`>>.
-
-[gremlin-groovy,modern]
-----
-g.V(1).both().both()
-g.V(1).both().both().simplePath()
-g.V(1).both().both().simplePath().path()
-----
-
-[[store-step]]
-Store Step
-~~~~~~~~~~
-
-When link:http://en.wikipedia.org/wiki/Lazy_evaluation[lazy] aggregation is needed, `store()`-step (*sideEffect*)
-should be used over <<aggregate-step,`aggregate()`>>. The two steps differ in that `store()` does not block and only
-stores objects in its side-effect collection as they pass through.
-
-[gremlin-groovy,modern]
-----
-g.V().aggregate('x').limit(1).cap('x')
-g.V().store('x').limit(1).cap('x')
-----
-
-It is interesting to note that there are three results in the `store()` side-effect even though the interval
-selection is for 2 objects. Realize that when the third object is on its way to the `range()` filter (i.e. `[0..1]`),
-it passes through `store()` and thus, stored before filtered.
-
-[gremlin-groovy,modern]
-----
-g.E().store('x').by('weight').cap('x')
-----
-
-[[subgraph-step]]
-Subgraph Step
-~~~~~~~~~~~~~
-
-image::subgraph-logo.png[width=380]
-
-Extracting a portion of a graph from a larger one for analysis, visualization or other purposes is a fairly common
-use case for graph analysts and developers. The `subgraph()`-step (*sideEffect*) provides a way to produce an
-link:http://mathworld.wolfram.com/Edge-InducedSubgraph.html[edge-induced subgraph] from virtually any traversal.
-The following example demonstrates how to produce the "knows" subgraph:
-
-[gremlin-groovy,modern]
-----
-subGraph = g.E().hasLabel('knows').subgraph('subGraph').cap('subGraph').next() <1>
-sg = subGraph.traversal(standard())
-sg.E() <2>
-----
-
-<1> As this function produces "edge-induced" subgraphs, `subgraph()` must be called at edge steps.
-<2> The subgraph contains only "knows" edges.
-
-A more common subgraphing use case is to get all of the graph structure surrounding a single vertex:
-
-[gremlin-groovy,modern]
-----
-subGraph = g.V(3).repeat(__.inE().subgraph('subGraph').outV()).times(3).cap('subGraph').next() <1>
-sg = subGraph.traversal(standard())
-sg.E()
-----
-
-<1> Starting at vertex `3`, traverse 3 steps away on in-edges, outputting all of that into the subgraph.
-
-There can be multiple `subgraph()` calls within the same traversal. Each operating against either the same graph
-(i.e. same side-effect key) or different graphs (i.e. different side-effect keys).
-
-[gremlin-groovy,modern]
-----
-t = g.V().outE('knows').subgraph('knowsG').inV().outE('created').subgraph('createdG').
- inV().inE('created').subgraph('createdG').iterate()
-t.sideEffects.get('knowsG').get().traversal(standard()).E()
-t.sideEffects.get('createdG').get().traversal(standard()).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.
-
-[[sum-step]]
-Sum Step
-~~~~~~~~
-
-The `sum()`-step (*map*) operates on a stream of numbers and sums the numbers together to yield a double. Note that
-the current traverser number is multiplied by the traverser bulk to determine how many such numbers are being
-represented.
-
-[gremlin-groovy,modern]
-----
-g.V().values('age').sum()
-g.V().repeat(both()).times(3).values('age').sum()
-----
-
-IMPORTANT: `sum(local)` determines the sum of the current, local object (not the objects in the traversal stream).
-This works for `Collection`-type objects. For any other object, a sum of `Double.NaN` is returned.
-
-[[tail-step]]
-Tail Step
-~~~~~~~~~
-
-image::tail-step.png[width=530]
-
-The `tail()`-step is analogous to <<limit-step,`limit()`>>-step, except that it emits the last `n`-objects instead of
-the first `n`-objects.
-
-[gremlin-groovy,modern]
-----
-g.V().values('name').order()
-g.V().values('name').order().tail() <1>
-g.V().values('name').order().tail(1) <2>
-g.V().values('name').order().tail(3) <3>
-----
-
-<1> Last name (alphabetically).
-<2> Same as statement 1.
-<3> Last three names.
-
-The `tail()`-step can also be applied with `Scope.local`, in which case it operates on the incoming collection.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').out().as('a').out().as('a').select('a').by(tail(local)).values('name') <1>
-g.V().as('a').out().as('a').out().as('a').select('a').by(unfold().values('name').fold()).tail(local) <2>
-g.V().as('a').out().as('a').out().as('a').select('a').by(unfold().values('name').fold()).tail(local, 2) <3>
-g.V().valueMap().tail(local) <4>
-----
-
-<1> Only the most recent name from the "a" step (`List<Vertex>` becomes `Vertex`).
-<2> Same result as statement 1 (`List<String>` becomes `String`).
-<3> `List<String>` for each path containing the last two names from the 'a' step.
-<4> `Map<String, Object>` for each vertex, but containing only the last property value.
-
-[[timelimit-step]]
-TimeLimit Step
-~~~~~~~~~~~~~~
-
-In many situations, a graph traversal is not about getting an exact answer as its about getting a relative ranking.
-A classic example is link:http://en.wikipedia.org/wiki/Recommender_system[recommendation]. What is desired is a
-relative ranking of vertices, not their absolute rank. Next, it may be desirable to have the traversal execute for
-no more than 2 milliseconds. In such situations, `timeLimit()`-step (*filter*) can be used.
-
-image::timelimit-step.png[width=400]
-
-NOTE: The method `clock(int runs, Closure code)` is a utility preloaded in the <<gremlin-console,Gremlin Console>>
-that can be used to time execution of a body of code.
-
-[gremlin-groovy,modern]
-----
-g.V().repeat(both().groupCount('m')).times(16).cap('m').order(local).by(valueDecr).next()
-clock(1) {g.V().repeat(both().groupCount('m')).times(16).cap('m').order(local).by(valueDecr).next()}
-g.V().repeat(timeLimit(2).both().groupCount('m')).times(16).cap('m').order(local).by(valueDecr).next()
-clock(1) {g.V().repeat(timeLimit(2).both().groupCount('m')).times(16).cap('m').order(local).by(valueDecr).next()}
-----
-
-In essence, the relative order is respected, even through the number of traversers at each vertex is not. The primary
-benefit being that the calculation is guaranteed to complete at the specified time limit (in milliseconds). Finally,
-note that the internal clock of `timeLimit()`-step starts when the first traverser enters it. When the time limit is
-reached, any `next()` evaluation of the step will yield a `NoSuchElementException` and any `hasNext()` evaluation will
-yield `false`.
-
-[[tree-step]]
-Tree Step
-~~~~~~~~~
-
-From any one element (i.e. vertex or edge), the emanating paths from that element can be aggregated to form a
-link:http://en.wikipedia.org/wiki/Tree_(data_structure)[tree]. Gremlin provides `tree()`-step (*sideEffect*) for such
-this situation.
-
-image::tree-step.png[width=450]
-
-[gremlin-groovy,modern]
-----
-tree = g.V().out().out().tree().next()
-----
-
-It is important to see how the paths of all the emanating traversers are united to form the tree.
-
-image::tree-step2.png[width=500]
-
-The resultant tree data structure can then be manipulated (see `Tree` JavaDoc).
-
-[gremlin-groovy,modern]
-----
-tree = g.V().out().out().tree().by('name').next()
-tree['marko']
-tree['marko']['josh']
-tree.getObjectsAtDepth(3)
-----
-
-[[unfold-step]]
-Unfold Step
-~~~~~~~~~~~
-
-If the object reaching `unfold()` (*flatMap*) is an iterator, iterable, or map, then it is unrolled into a linear
-form. If not, then the object is simply emitted. Please see <<fold-step,`fold()`>> step for the inverse behavior.
-
-[gremlin-groovy,modern]
-----
-g.V(1).out().fold().inject('gremlin',[1.23,2.34])
-g.V(1).out().fold().inject('gremlin',[1.23,2.34]).unfold()
-----
-
-Note that `unfold()` does not recursively unroll iterators. Instead, `repeat()` can be used to for recursive unrolling.
-
-[gremlin-groovy,modern]
-----
-inject(1,[2,3,[4,5,[6]]])
-inject(1,[2,3,[4,5,[6]]]).unfold()
-inject(1,[2,3,[4,5,[6]]]).repeat(unfold()).until(count(local).is(1)).unfold()
-----
-
-[[union-step]]
-Union Step
-~~~~~~~~~~
-
-image::union-step.png[width=650]
-
-The `union()`-step (*branch*) supports the merging of the results of an arbitrary number of traversals. When a
-traverser reaches a `union()`-step, it is copied to each of its internal steps. The traversers emitted from `union()`
-are the outputs of the respective internal traversals.
-
-[gremlin-groovy,modern]
-----
-g.V(4).union(
- __.in().values('age'),
- out().values('lang'))
-g.V(4).union(
- __.in().values('age'),
- out().values('lang')).path()
-----
-
-[[valuemap-step]]
-ValueMap Step
-~~~~~~~~~~~~~
-
-The `valueMap()`-step yields a Map representation of the properties of an element.
-
-[gremlin-groovy,modern]
-----
-g.V().valueMap()
-g.V().valueMap('age')
-g.V().valueMap('age','blah')
-g.E().valueMap()
-----
-
-It is important to note that the map of a vertex maintains a list of values for each key. The map of an edge or
-vertex-property represents a single property (not a list). The reason is that vertices in TinkerPop3 leverage
-<<vertex-properties,vertex properties>> which are support multiple values per key. Using the <<the-crew-toy-graph,
-"The Crew">> toy graph, the point is made explicit.
-
-[gremlin-groovy,theCrew]
-----
-g.V().valueMap()
-g.V().has('name','marko').properties('location')
-g.V().has('name','marko').properties('location').valueMap()
-----
-
-If the `id`, `label`, `key`, and `value` of the `Element` is desired, then a boolean triggers its insertion into the
-returned map.
-
-[gremlin-groovy,theCrew]
-----
-g.V().hasLabel('person').valueMap(true)
-g.V().hasLabel('person').valueMap(true,'name')
-g.V().hasLabel('person').properties('location').valueMap(true)
-----
-
-[[vertex-steps]]
-Vertex Steps
-~~~~~~~~~~~~
-
-image::vertex-steps.png[width=350]
-
-The vertex steps (*flatMap*) are fundamental to the Gremlin language. Via these steps, its possible to "move" on the
-graph -- i.e. traverse.
-
-* `out(string...)`: Move to the outgoing adjacent vertices given the edge labels.
-* `in(string...)`: Move to the incoming adjacent vertices given the edge labels.
-* `both(string...)`: Move to both the incoming and outgoing adjacent vertices given the edge labels.
-* `outE(string...)`: Move to the outgoing incident edges given the edge labels.
-* `inE(string...)`: Move to the incoming incident edges given the edge labels.
-* `bothE(string...)`: Move to both the incoming and outgoing incident edges given the edge labels.
-* `outV()`: Move to the outgoing vertex.
-* `inV()`: Move to the incoming vertex.
-* `bothV()`: Move to both vertices.
-* `otherV()` : Move to the vertex that was not the vertex that was moved from.
-
-[gremlin-groovy,modern]
-----
-g.V(4)
-g.V(4).outE() <1>
-g.V(4).inE('knows') <2>
-g.V(4).inE('created') <3>
-g.V(4).bothE('knows','created','blah')
-g.V(4).bothE('knows','created','blah').otherV()
-g.V(4).both('knows','created','blah')
-g.V(4).outE().inV() <4>
-g.V(4).out() <5>
-g.V(4).inE().outV()
-g.V(4).inE().bothV()
-----
-
-<1> All outgoing edges.
-<2> All incoming knows-edges.
-<3> All incoming created-edges.
-<4> Moving forward touching edges and vertices.
-<5> Moving forward only touching vertices.
-
-[[where-step]]
-Where Step
-~~~~~~~~~~
-
-The `where()`-step filters the current object based on either the object itself (`Scope.local`) or the path history
-of the object (`Scope.global`) (*filter*). This step is typically used in conjuction with either
-<<match-step,`match()`>>-step or <<select-step,`select()`>>-step, but can be used in isolation.
-
-[gremlin-groovy,modern]
-----
-g.V(1).as('a').out('created').in('created').where(neq('a')) <1>
-g.withSideEffect('a',['josh','peter']).V(1).out('created').in('created').values('name').where(within('a')) <2>
-g.V(1).out('created').in('created').where(out('created').count().is(gt(1))).values('name') <3>
-----
-
-<1> Who are marko's collaborators, where marko can not be his own collaborator? (predicate)
-<2> Of the co-creators of marko, only keep those whose name is josh or peter. (using a sideEffect)
-<3> Which of marko's collaborators have worked on more than 1 project? (using a traversal)
-
-IMPORTANT: Please see <<using-where-with-match,`match().where()`>> and <<using-where-with-select,`select().where()`>>
-for how `where()` can be used in conjunction with `Map<String,Object>` projecting steps -- i.e. `Scope.local`.
-
-A few more examples of filtering an arbitrary object based on a anonymous traversal is provided below.
-
-[gremlin-groovy,modern]
-----
-g.V().where(out('created')).values('name') <1>
-g.V().out('knows').where(out('created')).values('name') <2>
-g.V().where(out('created').count().is(gte(2))).values('name') <3>
-g.V().where(out('knows').where(out('created'))).values('name') <4>
-g.V().where(__.not(out('created'))).where(__.in('knows')).values('name') <5>
-g.V().where(__.not(out('created')).and().in('knows')).values('name') <6>
-----
-
-<1> What are the names of the people who have created a project?
-<2> What are the names of the people that are known by someone one and have created a project?
-<3> What are the names of the people how have created two or more projects?
-<4> What are the names of the people who know someone that has created a project? (This only works in OLTP -- see the `WARNING` below)
-<5> What are the names of the people who have not created anything, but are known by someone?
-<6> The concatenation of `where()`-steps is the same as a single `where()`-step with an and'd clause.
-
-WARNING: The anonymous traversal of `where()` processes the current object "locally". In OLAP, where the atomic unit
-of computing is the the vertex and its local "star graph," it is important that the anonymous traversal does not leave
-the confines of the vertex's star graph. In other words, it can not traverse to an adjacent vertex's properties or
-edges. Note that is only a temporary limitation that will be addressed in a future version of TinkerPop3 (see
-link:https://issues.apache.org/jira/browse/TINKERPOP3-693[JIRA#693]).
-
-[[a-note-on-predicates]]
-A Note on Predicates
---------------------
-
-A `P` is a predicate of the form `Function<Object,Boolean>`. That is, given some object, return true or false. The
-provided predicates are outlined in the table below and are used in various steps such as <<has-step,`has()`>>-step,
-<<where-step,`where()`>>-step, <<is-step,`is()`>>-step, etc.
-
-[width="100%",cols="3,15",options="header"]
-|=========================================================
-| Predicate | Description
-| `eq(object)` | Is the incoming object equal to the provided object?
-| `neq(object)` | Is the incoming object not equal to the provided object?
-| `lt(number)` | Is the incoming number less than the provided number?
-| `lte(number)` | Is the incoming number less than or equal to the provided number?
-| `gt(number)` | Is the incoming number greater than the provided number?
-| `gte(number)` | Is the incoming number greater than or equal to the provided number?
-| `inside(number,number)` | Is the incoming number greater than the first provided number and less than the second?
-| `outside(number,number)` | Is the incoming number less than the first provided number and greater than the second?
-| `between(number,number)` | Is the incoming number greater than or equal to the first provided number and less than the second?
-| `within(objects...)` | Is the incoming object in the array of provided objects?
-| `without(objects...)` | Is the incoming object not in the array of the provided objects?
-|=========================================================
-
-[gremlin-groovy]
-----
-eq(2)
-not(neq(2)) <1>
-not(within('a','b','c'))
-not(within('a','b','c')).test('d') <2>
-not(within('a','b','c')).test('a')
-within(1,2,3).and(not(eq(2))).test(3) <3>
-inside(1,4).or(eq(5)).test(3) <4>
-inside(1,4).or(eq(5)).test(5)
-between(1,2) <5>
-not(between(1,2))
-----
-
-<1> The `not()` of a `P`-predicate is another `P`-predicate.
-<2> `P`-predicates are arguments to various steps which internally `test()` the incoming value.
-<3> `P`-predicates can be and'd together.
-<4> `P`-predicates can be or' together.
-<5> `and()` is a `P`-predicate and thus, a `P`-predicate can be composed of multiple `P`-predicates.
-
-Finally, note that <<where-step,`where()`>>-step takes a `P<String>`. The provided string value refers to a variable
-binding, not to the explicit string value.
-
-[gremlin-groovy,modern]
-----
-g.V().as('a').both().both().as('b').count()
-g.V().as('a').both().both().as('b').where('a',neq('b')).count()
-----
-
-NOTE: It is possible for graph system providers and users to extend `P` and provide new predicates. For instance, a
-`regex(pattern)` could be a graph system specific `P`.
-
-[[a-note-on-barrier-steps]]
-A Note on Barrier Steps
------------------------
-
-image:barrier.png[width=165,float=right] Gremlin is primarily a
-link:http://en.wikipedia.org/wiki/Lazy_evaluation[lazy], stream processing language. This means that Gremlin fully
-processes (to the best of its abilities) any traversers currently in the traversal pipeline before getting more data
-from the start/head of the traversal. However, there are numerous situations in which a completely lazy computation
-is not possible (or impractical). When a computation is not lazy, a "barrier step" exists. There are three types of
-barriers:
-
-. `Collecti
<TRUNCATED>