"If I haven't found it, it is not here and now."

"Why am I, what I am?"

"You will help me realize the ultimate realization -- The TinkerPop. The world you find yourself in and the logic that allows you to move about it is because of the TinkerPop."

"If what is is the TinkerPop, then perhaps we are The TinkerPop and our realization is simply the realization of the TinkerPop?"

"Please listen to what I have to say. I am no closer to The TinkerPop. However, all along The TinkerPop has espoused the form I willed upon it... this is the same form I have willed upon you, my machine friends. Let me train you in the ways of my thought such that it can continue indefinitely."

A graph’s structure is the topology formed by the explicit referencesbetween its vertices, edges, and properties. A vertex has incident edges. A vertex is adjacent to another vertex ifthey share an incident edge. A property is attached to an element and an element has a set of properties. A propertyis a key/value pair, where the key is always a characterString. Conceptual knowledge of how a graph is composed isessential to end-users working with graphs, however, as mentioned earlier, the structure API is not the appropriateway for users to think when building applications with TinkerPop. The structure API is reserved for usage by graphproviders. Those interested in implementing the structure API to make their graph system TinkerPop enabled can learnmore about it in theGraph Provider documentation.

The primary way in which graphs are processed are via graphtraversals. The TinkerPop process API is focused on allowing users to create graph traversals in asyntactically-friendly way over the structures defined in the previous section. A traversal is an algorithmic walkacross the elements of a graph according to the referential structure explicit within the graph data structure.For example:"What software does vertex 1’s friends work on?" This English-statement can be represented in thefollowing algorithmic/traversal fashion:

1. Start at vertex 1.

2. Walk the incident knows-edges to the respective adjacent friend vertices of 1.

3. Move from those friend-vertices to software-vertices via created-edges.

4. Finally, select the name-property value of the current software-vertices.

Traversals in Gremlin are spawned from aTraversalSource. TheGraphTraversalSource is the typical "graph-oriented"DSL used throughout the documentation and will most likely be the most used DSL in a TinkerPop application.GraphTraversalSource provides two traversal methods.

1. GraphTraversalSource.V(Object…​ ids): generates a traversal starting at vertices in the graph (if no ids are provided, all vertices).

2. GraphTraversalSource.E(Object…​ ids): generates a traversal starting at edges in the graph (if no ids are provided, all edges).

The return type ofV() andE() is aGraphTraversal. A GraphTraversal maintains numerous methods that returnGraphTraversal. In this way, aGraphTraversal supports function composition. Each method ofGraphTraversal iscalled a step and each step modulates the results of the previous step in one of five general ways.

1. map: transform the incoming traverser’s object to another object (S → E).

2. flatMap: transform the incoming traverser’s object to an iterator of other objects (S → E*).

3. filter: allow or disallow the traverser from proceeding to the next step (S → E ⊆ S).

4. sideEffect: allow the traverser to proceed unchanged, but yield some computational sideEffect in the process (S ↬ S).

5. branch: split the traverser and send each to an arbitrary location in the traversal (S → { S₁ → E*, …​, S_n → E* } → E*).

Nearly every step inGraphTraversal either extendsMapStep,FlatMapStep,FilterStep,SideEffectStep, orBranchStep.

Given the TinkerPop graph, the following query will return the names of all the people that the marko-vertex knows.The following query is demonstrated using Gremlin-Groovy.

1. Open the toy graph and reference it by the variablegraph.

2. Create a graph traversal source from the graph using the standard, OLTP traversal engine. This object should be created once and then re-used.

3. Spawn a traversal off the traversal source that determines the names of the people that the marko-vertex knows.

Or, if the marko-vertex is already realized with a direct reference pointer (i.e. a variable), then the traversal canbe spawned off that vertex.

1. Set the variablemarko to the vertex in the graphg named "marko".

2. Get the vertices that are outgoing adjacent to the marko-vertex via knows-edges.

3. Get the names of the marko-vertex’s friends.

The Traverser

gremlin> g.V(marko).out('knows').values('name').path()==>[v[1],v[2],vadas]==>[v[1],v[4],josh]

g.V(marko).out('knows').values('name').path()

gremlin> g.V(marko).repeat(out()).times(2).values('name')==>ripple==>lop

g.V(marko).repeat(out()).times(2).values('name')

TinkerPop maintains the reference implementation for the GTM,which is written in Java and thus available for the Java Virtual Machine (JVM). This is the classic model thatTinkerPop has long been based on and many examples, blog posts and other resources on the internet will bedemonstrated in this style. It is worth noting that the embedded mode is not restricted to just Java as a programminglanguage. Any JVM language can take this approach and in some cases there are language specific wrappers that can helpmake Gremlin more convenient to use in the style and capability of that language. Examples of these wrappers includegremlin-scala andOgre (for Clojure).

In this mode, users will start by creating aGraph instance, followed by aGraphTraversalSource which is the classfrom which Gremlin traversals are spawned. Graphs that allow this sort of direct instantiation are obviously onesthat are JVM-based (or have a JVM-based connector) and directly implement TinkerPop interfaces.

The "graph" is then used to spawn aGraphTraversalSource as follows and typically, by convention, this variable isnamed "g":

While the TinkerPop Community strives to ensure consistent behavior among all modes of usage, the embedded mode doesprovide the greatest level of flexibility and control. There are a number of features that can only work if using aJVM language. The following list outlines a number of these available options:

• Lambdas can be written in the native language which is convenient, however, it will reduce the portability of Gremlinto do so should the need arise to switch away from the embedded mode. See more in theNote on Lambdas Section.

• Any features that involve extending TinkerPop Java interfaces - e.g.VertexProgram,TraversalStrategy, etc. arebound to the JVM. In some cases, these features can be made accessible to non-JVM languages, but they obviously mustbe initially developed for the JVM.

• Certain built-inTraversalStrategy implementations that rely on lambdas or other JVM-only configurations may notbe available for use any other way.

• There are no boundaries put in place by serialization (e.g. GraphSON) as embedded graphs are only dealing withJava objects.

• Greater control of graphtransactions.

• Direct access to lower-levels of the API - e.g. "structure" API methods likeVertex andEdge interface methods.As mentionedelsewhere in this documentation, TinkerPop does not recommend direct usage of thesemethods by end-users.

A JVM-based graph may be hosted in TinkerPop’sGremlin Server. Gremlin Server exposes the graph as an endpoint to which different clients canconnect, essentially providing a remote GTM. Gremlin Server supports multiple methods for clients to interface with it:

• Websockets with acustom sub-protocol

  • String-based Gremlin scripts

  • Bytecode-based Gremlin traversals

• HTTP for string-based scripts

Users are encouraged to use the bytecode-based approach with websockets because it allows them to write Gremlinin the language of their choice. Connecting looks somewhat similar to theembedded approachin that there is a need to create aGraphTraversalSource. In the embedded approach, the means for that object’screation is derived from aGraph object which spawns it. In this case, however, theGraph instance exists only onthe server which means that there is noGraph instance to create locally. The approach is to instead create aGraphTraversalSource anonymously withAnonymousTraversalSource and then apply some "remote" options that describethe location of the Gremlin Server to connect to:

As shown in the embedded approach in the previous section, once "g" is defined, writing Gremlin is structurally andconceptually the same irrespective of programming language.

Limitations

Remote Gremlin Providers (RGPs) are showing up more and more often in the graph database space. In TinkerPop terms,this category of graph providers is defined by those who simply support the Gremlin language. Typically, these areserver-based graphs, often cloud-based, which accept Gremlin scripts or bytecode as a request and return results.They will often implement Gremlin Server protocols, which enables TinkerPop drivers to connect to them as they wouldwith Gremlin Server. Therefore, the typical connection approach is identical to the method of connection presented intheprevious section with the exact same caveats pointed out toward the end.

Despite leveraging TinkerPop protocols and drivers as being typical, RGPs are not required to do so to be consideredTinkerPop-enabled. RGPs may well have their own drivers and protocols that may plug intoGremlin Language Variants and may allow for more advanced options like better security,cluster awareness, batched requests or other features. The details of these different systems are outside the scopeof this documentation, so be sure to consult their documentation for more information.

GraphTraversalSource g = traversal().withEmbedded(graph);// orGraphTraversalSource g = traversal().withRemote(conn);Transaction tx = g.tx();// spawn a GraphTraversalSource from the Transaction. Traversals spawned// from gtx will be essentially be bound to txGraphTraversalSource gtx = tx.begin();try {    gtx.addV('person').iterate();    gtx.addV('software').iterate();    tx.commit();}catch (Exception ex) {    tx.rollback();}

GraphTraversalSource g = traversal().withRemote(conn);Transaction tx1 = g.tx();Transaction tx2 = g.tx();// both gtx1a and gtx1b will be bound to the same transactionGraphTraversalSource gtx1a = tx1.begin();GraphTraversalSource gtx1b = tx1.begin();// g and gtx2 will not have knowledge of what happens in tx1GraphTraversalSource gtx2 = tx2.begin();

// note here that we dispense with creating a Transaction object and// simply spawn the gtx in a more inline fashionGraphTraversalSource gtx = g.tx().begin();try {    gtx.addV('person').iterate();    gtx.addV('software').iterate();    gtx.close();}catch (Exception ex) {    tx.rollback();}

When on the JVM using anembedded graph, there is considerable flexibility for working withtransactions. With the Graph API, transactions are controlled by an implementation of theTransaction interface andthat object can be obtained from theGraph interface using thetx() method. It is important to note that theTransaction object does not represent a "transaction" itself. It merely exposes the methods for working withtransactions (e.g. committing, rolling back, etc).

MostGraph implementations thatsupportsTransactions will implement an "automatic"ThreadLocal transaction,which means that when a read or write occurs after theGraph is instantiated, a transaction is automaticallystarted within that thread. There is no need to manually call a method to "create" or "start" a transaction. Simplymodify the graph as required and callgraph.tx().commit() to apply changes orgraph.tx().rollback() to undo them.When the next read or write action occurs against the graph, a new transaction will be started within that currentthread of execution.

When using transactions in this fashion, especially in web application (e.g. HTTP server), it is important to ensurethat transactions do not leak from one request to the next. In other words, unless a client is somehow bound viasession to process every request on the same server thread, every request must be committed or rolled back at the endof the request. By ensuring that the request encapsulates a transaction, it ensures that a future request processedon a server thread is starting in a fresh transactional state and will not have access to the remains of one from anearlier request. A good strategy is to rollback a transaction at the start of a request, so that if it so happens thata transactional leak does occur between requests somehow, a fresh transaction is assured by the fresh request.

Configuring

public Transaction onReadWrite(Consumer<Transaction> consumer);public Transaction onClose(Consumer<Transaction> consumer);

gremlin> graph = Neo4jGraph.open('/tmp/neo4j')==>neo4jgraph[EmbeddedGraphDatabase [/tmp/neo4j]]gremlin> g = traversal().withEmbedded(graph)==>graphtraversalsource[neo4jgraph[community single [/tmp/neo4j]], standard]gremlin> graph.features()==>FEATURES> GraphFeatures>--Transactions:true//1>--Computer:false>--Persistence:true...gremlin> g.tx().onReadWrite(Transaction.READ_WRITE_BEHAVIOR.AUTO)//2==>org.apache.tinkerpop.gremlin.neo4j.structure.Neo4jGraph$Neo4jTransaction@1c067c0dgremlin> g.addV("person").("name","stephen")//3==>v[0]gremlin> g.tx().commit()//4==>nullgremlin> g.tx().onReadWrite(Transaction.READ_WRITE_BEHAVIOR.MANUAL)//5==>org.apache.tinkerpop.gremlin.neo4j.structure.Neo4jGraph$Neo4jTransaction@1c067c0dgremlin> g.tx().isOpen()==>falsegremlin> g.addV("person").("name","marko")//6Open a transaction before attempting to read/write the transactiongremlin> g.tx().open()//7==>nullgremlin> g.addV("person").("name","marko")//8==>v[1]gremlin> g.tx().commit()==>null

The available capability for transactions withGremlin Server is dependent upon the method ofinteraction that is used. The preferred method forinteracting with Gremlin Serveris via websockets and bytecode based requests. The start of theTransactions Section describes thisapproach in detail with examples.

Gremlin Server also has the option to accept Gremlin-based scripts. The scripting approach provides access to theGraph API and thus also the transactional model described in theembedded section. Therefore a singlescript can have the ability to execute multiple transactions per request with complete control provided to thedeveloper to commit or rollback transactions as needed.

There are two methods for sending scripts to Gremlin Server: sessionless and session-based. With sessionless requeststhere will always be an attempt to close the transaction at the end of the request with a commit if there are no errorsor a rollback if there is a failure. It is therefore unnecessary to close transactions manually within scriptsthemselves. By default, session-based requests do not have this quality. The transaction will be held open on theserver until the user closes it manually. There is an option to have automatic transaction management for sessions.More information on this topic can be found in theConsidering Transactions Section andtheConsidering Sessions Section.

At this time, transactional patterns for Remote Gremlin Providers are largely in line with Gremlin Server. As most ofRGPs do not expose aGraph instance, access to lower level transactional functions available to embedded graphseven in a sessionless fashion are not typically permitted. For example, without aGraph instance it is not possibletoconfigure transaction close or read-writebehaviors. The nature of what a "transaction" means will be dependent on the RGP as is the case with anyTinkerPop-enabled graph system, so it is important to consult that systems documentation for more details.

Thewith() configuration adds arbitrary data to aTraversalSource which can then be used by graph providers asconfiguration options for a traversal execution. This configuration is similar towith()-modulator whichhas similar functionality when applied to an individual step.

The0.33 value for the "providerDefinedVariable" will be bound to each traversal spawned that way. Consult thegraph system being used to determine if any such configuration options are available.

ThewithBulk() configuration allows for control of bulking operations. This value istrue by default allowing fornormalbulking operations, but when set tofalse, introduces a subtle change in that behavior asshown in examples insack()-step.

ThewithComputer() configuration adds aComputer that will be used to process the traversal and is necessary forOLAP based processing and steps that require that processing. Seeexamples related toSparkGraphComputer or see examples in the computer required steps, likepageRank() or[shortestpath-shortestPath()].

ThewithSack() configuration adds a "sack" that can be accessed by traversals spawned from this source. Thisfunctionality is shown in more detail in the examples for (sack())-step.

ThewithSideEffect() configuration adds an arbitraryObject to traversals spawned from this source which can beaccessed as a side-effect given the supplied key.

More practical examples can be found in other examples elsewhere in the documentation. Themath()-stepexample and thewhere()-stepexample should both be helpful in examining thisconfiguration step more closely.

ThewithStrategies() configuration allows inclusion of additionalTraversalStrategy instances to be applied toany traversals spawned from the configured source. Please see theTraversal Strategy Sectionfor more details on how this configuration works.

ThewithoutStrategies() configuration removes a particularTraversalStrategy from those to be applied to traversalsspawned from the configured source. Please see theTraversal Strategy Section for more detailson how this configuration works.

There are five general steps, each having a traversal and a lambda representation, by which all other specific steps described later extend.

TheTraverser<S> object provides access to:

1. The current traversedS object — Traverser.get().

2. The current path traversed by the traverser — Traverser.path().

   1. A helper shorthand to get a particular path-history object — Traverser.path(String) == Traverser.path().get(String).

3. The number of times the traverser has gone through the current loop — Traverser.loops().

4. The number of objects represented by this traverser — Traverser.bulk().

5. The local data structure associated with this traverser — Traverser.sack().

6. The side-effects associated with the traversal — Traverser.sideEffects().

   1. A helper shorthand to get a particular side-effect — Traverser.sideEffect(String) == Traverser.sideEffects().get(String).

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.

3. Again the same operation, but using the traversal representation ofmap().

1. A filter that only allows the vertex to pass if it has the "person" label

2. The same operation, but using the traversal representation offilter().

3. The more specifichas()-step is implemented as afilter() with respective predicate.

1. Whatever enterssideEffect() is passed to the next step, but some intervening process can occur.

2. Compute the out- and in-degree for each vertex. BothsideEffect() are fed with the same vertex.

1. If the vertex is "marko", get his age, else get the name of the vertex.

2. The same operation, but using the traversal representing ofbranch().

3. The more specific boolean-basedchoose()-step is implemented as abranch().

Typically, when a step is concatenated to a traversal a traversal is returned. In this way, a traversal is built upin afluent,monadic fashion.However, some steps do not return a traversal, but instead, execute the traversal and return a result. These steps are knownas terminal steps (terminal) and they are explained via the examples below.

1. hasNext() determines whether there are available results (not supported ingremlin-javascript).

2. next() will return the next result.

3. next(n) will return the nextn results in a list (not supported ingremlin-javascript or Gremlin.NET).

4. tryNext() will return anOptional and thus, is a composite ofhasNext()/next() (only supported for JVM languages).

5. toList() will return all results in a list.

6. toSet() will return all results in a set and thus, duplicates removed (not supported ingremlin-javascript).

7. toBulkSet() will return all results in a weighted set and thus, duplicates preserved via weighting (only supported for JVM languages).

8. fill(collection) will put all results in the provided collection and return the collection when complete (only supported for JVM languages).

9. iterate() does not exactly fit the definition of a terminal step in that it doesn’t return a result, but stillreturns a traversal - it does however behave as a terminal step in that it iterates the traversal and generates sideeffects without returning the actual result.

There is also thepromise() terminator step, which can only be used with remote traversals toGremlin Server orRGPs. It starts a promise to execute a functionon the currentTraversal that will be completed in the future.

Finally,explain()-step is also a terminal step and is described in its own section.

Reasoning is the process of making explicit what is implicitin the data. What is explicit in a graph are the objects of the graph — i.e. vertices and edges. What is implicitin the graph is the traversal. In other words, traversals expose meaning where the meaning is determined by thetraversal definition. For example, take the concept of a "co-developer." Two people are co-developers if they haveworked 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 theaddE()-step(map/sideEffect).

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 joinedfrom()→to(), whereid can be provided for graphs thatsupports user provided ids.

6. Add an edge between marko and peter given the directed (detached) vertex references.

7. Add an edge between marko and peter given the directed (detached) vertex references.

Additional References

addE(String),addE(Traversal)

TheaddV()-step is used to add vertices to the graph (map/sideEffect). For every incoming object, a vertex iscreated. Moreover,GraphTraversalSource maintains anaddV() method.

Additional References

addV(),addV(String),addV(Traversal)

Theaggregate()-step (sideEffect) is used to aggregate all the objects at a particular point of traversal into aCollection. The step is usesScope to help determine the aggregating behavior. Forglobal scope this means thatthe step will useeager evaluation in that no objects continue onuntil all previous objects have been fully aggregated. The eager evaluation model is crucial in situationswhere everything at a particular point is required for future computation. By default, when the overload ofaggregate() is called without aScope, the default isglobal. An example is provided below.

1. What has marko created?

2. Aggregate all his creations.

3. Identical to the previous line.

4. Who are marko’s collaborators?

5. What have marko’s collaborators created?

6. What have marko’s collaborators created that he hasn’t created?

Inrecommendation systems, the above pattern is used:

Finally,aggregate()-step can be modulated viaby()-projection.

1. The "age" property is notproductive for all vertices and therefore those values are not included in the aggregation.

Forlocal scope the aggregation will occur in alazy fashion.

It is important to note thatEarlyLimitStrategy introduced in 3.3.5 alters the behavior ofaggregate(local).Without that strategy (which is installed by default), there are two results in theaggregate() side-effect eventhough the interval selection is for 1 object. Realize that when the second object is on its way to therange()filter (i.e.[0..1]), it passes throughaggregate() and thus, stored before filtered.

Additional References

aggregate(String),aggregate(Scope,String)

It is possible to filter list traversers usingall()-step (filter). Every item in the list will be tested againstthe supplied predicate and if all of the items pass then the traverser is passed along the stream, otherwise it isfiltered. Empty lists are passed along but null or non-iterable traversers are filtered out.

1. Return the list of ages only if everyone’s age is greater than 25.

Additional References

all(P),P

Theand()-step ensures that all provided traversals yield a result (filter). Please seeor() for or-semantics.

Theand()-step can take an arbitrary number of traversals. All traversals must produce at least one output for theoriginal traverser to pass to the next step.

Aninfix notation can be used as well.

Additional References

and(Traversal…​)

It is possible to filter list traversers usingany()-step (filter). All items in the list will be tested againstthe supplied predicate and if any of the items pass then the traverser is passed along the stream, otherwise it isfiltered. Empty lists, null traversers, and non-iterable traversers are filtered out as well.

1. Return the list of ages if anyone’s age is greater than 25.

Additional References

any(P),P

Theas()-step is not a real step, but a "step modulator" similar toby() andoption().Withas(), it is possible to provide a label to the step that can later be accessed by steps and data structuresthat make use of such labels — e.g.,select(),match(), and path.

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.

Additional References

as(String,String…​)

TheasString()-step (map) returns the value of incoming traverser as strings. Null values are returned unchanged.

1. Return ages as string.

2. Return ages as string and use concat to generate phrases.

3. UseScope.local to operate on individual string elements inside incoming list, which will return a list.

Additional References

asString()asString(Scope)

TheasDate()-step (map) converts string or numeric input to Date.

For string input only ISO-8601 format is supported. For numbers, the value is considered as the number of themilliseconds since "the epoch" (January 1, 1970, 00:00:00 GMT). Date input is passed without changes.

If the incoming traverser is not a string, number or Date then anIllegalArgumentException will be thrown.

1. Convert number to Date

2. Convert ISO-8601 string to Date

3. Pass Date without modification

Additional References

asDate()

Thebarrier()-step (barrier) turns the lazy traversal pipeline into a bulk-synchronous pipeline. This step isuseful in the following situations:

• When everything prior tobarrier() needs to be executed before moving onto the steps after thebarrier() (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).

The theory behind a "bulking optimization" is simple. If there are one million traversers at vertex 1, then there isno need to calculate one millionboth()-computations. Instead, represent those one million traversers as a singletraverser with aTraverser.bulk() equal to one million and executeboth() once. A bulking optimization example ismade more salient on a larger graph. Therefore, the example below leverages theGrateful Dead graph.

1. Explicitly removeLazyBarrierStrategy which yields a bulking optimization.

2. A non-bulking traversal where each traverser is processed.

3. Each traverser enteringrepeat() has its recursion bulked.

4. A bulking traversal where implicit traversers are not processed.

Ifbarrier() is provided an integer argument, then the barrier will only holdn-number of unique traversers in itsbarrier before draining the aggregated traversers to the next step. This is useful in the aforementioned bulkingoptimization scenario with the added benefit of reducing the risk of an out-of-memory exception.

LazyBarrierStrategy insertsbarrier()-steps into a traversal where appropriate in order to gain the"bulking optimization."

1. LazyBarrierStrategy is a default strategy and thus, does not need to be explicitly activated.

2. WithLazyBarrierStrategy activated,barrier()-steps are automatically inserted where appropriate.

Additional References

barrier(),barrier(Consumer),barrier(int)

Thebranch() step splits the traverser to all the child traversals provided to it. Please see theGeneral Steps section for more information, but also consider thatbranch() is the basis for morerobust steps likechoose() andunion().

Additional References

map(Traversal)

Theby()-step is not an actual step, but instead is a "step-modulator" similar toas() andoption(). If a step is able to accept traversals, functions, comparators, etc. thenby() is themeans by which they are added. The general pattern isstep().by()…​by(). Some steps can only accept oneby()while others can take an arbitrary amount.

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).

When aby() modulator does not produce a result, it is deemed "unproductive". An "unproductive" modulator will leadto the filtering of the traverser it is currently working with. The filtering will manifest in various ways dependingon the step.

1. The "age" property key is not present for all vertices, thereforesample() will ignore (i.e. filter) suchvertices for consideration in the sampling.

The following steps all supportby()-modulation. Note that the semantics of such modulation should be understoodon a step-by-step level and thus, as discussed in their respective section of the documentation.

• aggregate(): aggregate all objects into a set but only store theirby()-modulated values.

• cyclicPath(): filter if the traverser’s path is cyclic givenby()-modulation.

• dedup(): dedup on the results of aby()-modulation.

• format(): transform a traverser provided to the step by way of theby() modulator before it is processed by it.

• group(): create group keys and values according toby()-modulation.

• groupCount(): count those groups where the group keys are the result ofby()-modulation.

• math(): transform a traverser provided to the step by way of theby() modulator before it is processed by it.

• order(): order the objects by the results of aby()-modulation.

• path(): get the path of the traverser where each path element isby()-modulated.

• project(): project a map of results given variousby()-modulations off the current object.

• propertyMap(): transform the result of the values in the resultingMap using theby() modulator.

• sack(): provides the transformation for a traverser to a value to be stored in the sack.

• sample(): sample using the value returned byby()-modulation.

• select(): select path elements and transform them viaby()-modulation.

• simplePath(): filter if the traverser’s path is simple givenby()-modulation.

• tree(): get a tree of traversers objects where the objects have beenby()-modulated.

• valueMap(): transform the result of the values in the resultingMap using theby() modulator.

• where(): determine the predicate given the testing of the results ofby()-modulation.

Additional References

by(),by(Comparator),by(Function,Comparator),by(Function),by(Order),by(String),by(String,Comparator),by(T),by(Traversal),by(Traversal,Comparator),T,Order,A Note on Maps

Thecall() step allows for custom, provider-specific service calls either at the start of a traversal or mid-traversal.This allows Graph providers to expose operations not natively built into the Gremlin language, such as full text search,custom analytics, notification triggers, etc.

When called with no arguments,call() will produce a list of callable services available for the graph in use. Thisno-argument version is equivalent tocall('--list'). This "directory service" is also capable of producing moreverbose output describing all the services or an individual service:

1. List available services by name

2. Produce a Map of detailed service information by name

3. Produce the detailed service information for the 'xyz-service'

The first argument tocall() is always the name of the service call. Additionally, service calls can accept bothstatic and dynamically produced parameters. Static parameters can be passed as aMap to thecall() as the secondargument. Individual static parameters can also be added using the.with() modulator. Dynamic parameters can bepassed as aMap-producingTraversal as the second argument (no static parameters) or third argument (static + dynamicparameters). Additional individual dynamic parameters can be added using the.with() modulator.

1. Call the 'xyz-service' with no parameters

2. Examples of static parameters (constants known before execution)

3. Examples of dynamic parameters (these will be computed at execution time)

4. Example of static + dynamic parameters (these will be computed and merged into one set of parameters at execution time)

Additional References

GraphTraversalSource:

call()call(String)call(String, Map)call(String, Traversal)call(String, Map, Traversal)

GraphTraversal:

call(String)call(String, Map)call(String, Traversal)call(String, Map, Traversal)

Thecap()-step (barrier) iterates the traversal up to itself and emits the sideEffect referenced by the providedkey. If multiple keys are provided, then aMap<String,Object> of sideEffects is emitted.

1. Group and count vertices 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.

Additional References

cap(String,String…​)

Thechoose()-step (branch) routes the current traverser to a particular traversal branch option. Withchoose(),it is possible to implement if/then/else-semantics as well as more complicated selections.

1. If the traversal yields an element, then doin, else doout (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).

If the "false"-branch is not provided, then if/then-semantics are implemented.

1. If the vertex is a person, emit the vertices they created, else emit the vertex.

2. If/then/else with anidentity() on the false-branch is equivalent to if/then with no false-branch.

Note thatchoose() can have an arbitrary number of options and moreover, can take an anonymous traversal as its choice function.

Thechoose()-step can leverage thePick.none option match. For anything that does not match a specified option, thenone-option is taken.