As intuitive as it is to you, it is perhaps more intuitive to Gremlin himself, as vertices, edges and properties make up the very elements of his existence. It is indeed helpful to think of our friend, Gremlin, moving about a graph when developing traversals, as picturing his position as the traverser helps orient where you need him to go next. Let’s use the two-vertex, one-edge graph we’ve been discussing above as an example. First, you need to create this graph:

There are a number of important things to consider in the above code. First, recall that id is "reserved" for special usage in TinkerPop. It is a member of the enum, T. Those "keys" supplied to the creation method are statically imported to the console, which allows you to access them without having to specify their owning enum. Think of id as a shorthand form that enables a more fluid code style. You would normally refer to it as T.id, so without that static importing you would instead have to write:

Second, don’t forget that you are working with TinkerGraph, which allows for identifier assignment. That is not the case with most graph databases.

Finally, the label for an Edge is required and is thus part of the method signature of addEdge(). This usage of addEdge is creating an edge that goes out of v1 and into v2 with a label of "created".

Now that Gremlin knows where the graph data is, you can ask him to get you some data from it by doing a traversal, which you can think of as executing some process over the structure of the graph. We can form our question in English and then translate it to Gremlin. For this initial example, let’s ask Gremlin: "What software has Marko created?"

To answer this question, we would want Gremlin to:

The English-based steps above largely translate to Gremlin’s position in the graph and to the steps we need to take to ask him to answer our question. By stringing these steps together, we form a Traversal or the sequence of programmatic steps Gremlin needs to perform in order to get you an answer.

Let’s start with finding "marko". This operation is a filtering step as it searches the full set of vertices to match those that have the "name" property value of "marko". This can be done with the has() step as follows:

This bit of Gremlin can be improved and made more idiomatically pleasing by including the vertex label as part of the filter to ensure that the "name" property key refers to a "person" vertex.

We can picture this traversal in our little graph with Gremlin sitting on vertex "1".

When Gremlin is on a vertex or an edge, he has access to all the properties that are available to that element.

Now that Gremlin has found "marko", he can consider the next step in the traversal where we ask him to "walk" along "created" edges to "software" vertices. As described earlier, edges have direction, so we have to tell Gremlin what direction to follow. In this case, we want him to traverse on outgoing edges from the "marko" vertex. For this, we use the outE step.

At this point, you can picture Gremlin moving from the "marko" vertex to the "created" edge.

To get to the vertex on the other end of the edge, you need to tell Gremlin to move from the edge to the incoming vertex with inV().

You can now picture Gremlin on the "software" vertex as follows:

As you are not asking Gremlin to do anything with the properties of the "created" edge, you can simplify the statement above with:

Finally, now that Gremlin has reached the "software that Marko created", he has access to the properties of the "software" vertex and you can therefore ask Gremlin to extract the value of the "name" property as follows:

You should now be able to see the connection Gremlin has to the structure of the graph and how Gremlin maneuvers from vertices to edges and so on. Your ability to string together steps to ask Gremlin to do more complex things depends on your understanding of these basic concepts.

Armed with the knowledge from the previous section, let’s ask Gremlin to perform some more difficult traversal tasks. There’s not much more that can be done with the "baby" graph we had, so let’s return to the "modern" toy graph from the "First Five Minutes" section. Recall that you can create this Graph and establish a TraversalSource with:

Earlier we’d used the has()-step to tell Gremlin how to find the "marko" vertex. Let’s look at some other ways to use has(). What if we wanted Gremlin to find the "age" values of both "vadas" and "marko"? In this case we could use the within comparator with has() as follows:

It is worth noting that within is statically imported from P to the Gremlin Console (much like T is, as described earlier).

If we wanted to ask Gremlin the average age of "vadas" and "marko" we could use the mean() step as follows:

Another method of filtering is seen in the use of the where step. We know how to find the "software" that "marko" created:

Let’s extend on that query to try to learn who "marko" collaborates with when it comes to the software he created. In other words, let’s try to answer the question of: "Who are the people that marko develops software with?" To do that, we should first picture Gremlin where we left him in the previous query. He was standing on the "software" vertex. To find out who "created" that "software", we need to have Gremlin traverse back in along the "created" edges to find the "person" vertices tied to it.

So that’s nice, we can see that "peter", "josh" and "marko" are all responsible for creating "v[3]", which is the "software" vertex named "lop". Of course, we already know about the involvement of "marko" and it seems strange to say that "marko" collaborates with himself, so excluding "marko" from the results seems logical. The following traversal handles that exclusion:

We made two additions to the traversal to make it exclude "marko" from the results. First, we added the as() step. The as()-step is not really a "step", but a "step modulator" - something that adds features to a step or the traversal. Here, the as('exclude') labels the has()-step with the name "exclude" and all values that pass through that step are held in that label for later use. In this case, the "marko" vertex is the only vertex to pass through that point, so it is held in "exclude".

The other addition that was made was the where()-step, which is a filter step like has(). The where() is positioned after the in()-step that has "person" vertices, which means that the where() filter is occurring on the list of "marko" collaborators. The where() specifies that the "person" vertices passing through it should not equal (i.e., neq()) the contents of the "exclude" label. As it just contains the "marko" vertex, the where() filters out the "marko" that we get when we traverse back in on the "created" edges.

You will find many uses of as(). Here it is in combination with select:

In the above example, we tell Gremlin to iterate through all vertices and traverse out twice from each. Gremlin will label each vertex in that path with "a", "b" and "c", respectively. We can then use select to extract the contents of that label.

Another common but important step is the group() step and its related step modulator called by(). If we wanted to ask Gremlin to group all the vertices in the graph by their vertex label we could do:

The use of by() here provides the mechanism by which to do the grouping. In this case, we’ve asked Gremlin to use the label (which, again, is an automatic static import from T in the console). We can’t really tell much about our distribution though because we just have unique identifiers of vertices as output. To make that nicer we could ask Gremlin to get us the value of the "name" property from those vertices, by supplying another by() modulator to group() to transform the values.

In this section, you have learned a bit more about what property graphs are and how Gremlin interacts with them. You also learned how to envision Gremlin moving about a graph and how to use some of the more complex, but commonly utilized traversal steps. You are now ready to think about TinkerPop in terms of its wider applicability to graph computing.

The goal of TinkerPop, as a Graph Computing Framework, is to make it easy for developers to create graph applications by providing APIs and tools that simplify their endeavors. One of the fundamental aspects to what TinkerPop offers in this area lies in the fact that TinkerPop is an abstraction layer over different graph databases and different graph processors. As an abstraction layer, TinkerPop provides a way to avoid vendor lock-in to a specific database or processor. This capability provides immense value to developers who are thus afforded options in their architecture and development because:

TinkerPop has always had the vision of being an abstraction over different graph databases. That much is not new and dates back to TinkerPop 1.x. It is in TinkerPop 3.x, however, that we see the introduction of the notion that TinkerPop is also an abstraction over different graph processors like Spark. The scope of this tutorial does not permit it to delve into "graph processors", but the short story is that the same Gremlin statement we wrote in the examples above can be executed to run in distributed fashion over Spark or Hadoop. The changes required to the code to do this are not in the traversal itself, but in the definition of the TraversalSource. You can again see why we encourage graph operations to be executed through that class as opposed to just using Graph. You can read more about these features in this section on hadoop-gremlin.

There are many strategies for getting data into your graph. As you are just getting started, let’s look at the simpler methods aimed at "smaller" graphs. A "small" graph, in this context, is one that has fewer than ten million edges. The most direct way to load this data is to write a Groovy script that can be executed in the Gremlin Console, a tool that you should be well familiar with at this point. For our example, let’s use the Wikipedia Vote Network data set, which contains 7,115 vertices and 103,689 edges.

The data is contained in a tab-delimited structure in which vertices are Wikipedia users and edges from one user to another imply a "vote" relationship. Here is the script to parse the file and generate the Graph instance using TinkerGraph:

To load larger data sets you should read about the CloneVertexProgram, which provides a generalized method for loading graphs of virtually any size and consider the native bulk loading features of the underlying graph database that you’ve chosen.

This tutorial focused on Gremlin usage within the Gremlin Console which means that the examples were Groovy-based and oriented toward the JVM. Gremlin, however, is far from being a Java-only library. TinkerPop natively supports a number of different programming languages, making it possible to execute all of the examples presented in this tutorial with little modification. These different language implementations of Gremlin are referred to as Gremlin Language Variants and they help make Gremlin more accessible and easier to use for those who do not use Java as their primary programming language.

…​and that is the end of The TinkerPop Workout — by Gremlin. You are hopefully feeling more confident in your TinkerPop skills and have a good overview of what the stack has to offer, as well as some entry points to further research within the reference documentation. Welcome to The TinkerPop!