PRACTICAL GREMLIN:
An Apache TinkerPop Tutorial

Practical Gremlin was first published in 2017. In the years that followed, the Apache TinkerPop graph computing framework has continued to evolve. While it was possible to keep the first edition mostly up to date, and to publish periodic updates, there comes a time when so much has changed that it makes more sense to take a step back, and release a second edition. The book has been updated to include the most recent new features added to the Gremlin query language and related technologies. Material such as discussions of migrating from old versions of Gremlin, and discussions of how to work around features then lacking, but since added, have been removed. The following paragraph was used to introduce the first edition. It remains as true today as it was then.

As with the first edition, I have resisted the urge to cover every single feature of TinkerPop one after the other in a reference manual fashion. Instead, what I have tried to do is capture the learning process that I myself have gone through using what I hope is a sensible flow from getting started to more advanced topics. To get the most from this book I recommend having the Gremlin console open, with the air route sample data loaded, as you follow along. I have not assumed that anyone reading this book has any prior knowledge of Apache TinkerPop, the Gremlin query language or related tools. Everything you need to get started is introduced in Chapter 2.

I hope people continue to find what follows useful. It definitely remains a work in progress as the Apache TinkerPop framework, and in particular, the Gremlin query language, continues to evolve.

The book is available in multiple formats including PDF, HTML, ePub and MOBI. Those versions, along with sample code and data, can be found at the project’s home on GitHub. You will find a summary of everything that is available in the "Introducing the book sources, sample programs and data" section.

I forget exactly when, but sometime early in 2016 I started compiling a list of notes, hints and tips, initially for my own benefit. My notes were full of things I had found poorly explained elsewhere while using graph databases and especially while using Apache TinkerPop, Gremlin and JanusGraph. Over time that document continued to grow and had effectively become a book in all but name. After some encouragement from colleagues I decided to release my notes as a living book in an open source venue so that anyone who is interested can read it. It is definitely aimed at programmers and data scientists but I hope is also consumable by anyone using the Gremlin graph query and traversal language to work with graph databases.

I have included a large number of code examples and sample queries along with discussions of best practices and more than a few lessons I learned the hard way, that I hope you will find informative. I call it a living book as my goal is to regularly make updates as I discover things that need adding while also trying to keep the content as up to date as possible as Apache TinkerPop itself evolves.

I remain extremely grateful to all those who have encouraged me to keep going with this adventure. Keeping up with a moving target requires a fair bit of work, but remains a lot of fun!

Kelvin R. Lawrence
First draft (first edition): October 5th, 2017
Current draft (second edition): 2024-08-15 21:43:16 UTC

Please let me know about any mistakes you find in this material, and also please feel free to provide feedback of any sort. Suggested improvements are especially welcome. A good way to provide feedback is by opening an issue in the GitHub repository located at https://github.com/krlawrence/graph. You are currently reading revision v2-001-preview of the book.

I am grateful to those who have already taken the time to review the manuscript and open issues or submit pull requests.

No open source project can succeed without dedicated contributors, and equally dedicated users. Apache TinkerPop continues to be not just a technology, but a vibrant community as well. This book would have no audience but for the continued hard work, and interest, of that community.

As always, Special thanks should go to , Marko Rodriguez, Daniel Kuppitz, Stephen Mallette and others, who created TinkerPop and Gremlin, and drove its evolution for many years. I’m also grateful to Stephen for his help in putting this second edition of the book together.

Inspiration as to what topics people are interested in often comes from seeing the active discussions on-line at venues such as StackOverflow and the Gremlin Users Google Group. Since the first edition of this book was released, Apache TinkerPop now also has an active Discord channel where many exciting topics get discussed daily.

I continue to be grateful for the contributions of my former colleagues, Graham Wallis, Jason Plurad and Adam Holley who helped refine and improve several of the example queries contained in the first edition of this book. Gremlin is definitely a bit of a team sport. We spent many fun hours discussing the best way to handle different types of queries and traversals!

Lastly, I would like to thank everyone who has submitted feedback and ideas via e-mail or GitHub issues, and pull requests. That is the best part about this being a living book we can continue to improve and evolve it just as the technology it is about continues to evolve. Your help and support is very much appreciated.

This book introduces the Apache TinkerPop Gremlin graph query and traversal language via real examples featuring real-world graph data. That data along with sample code and example applications is available for download from the GitHub project as well as many other items. The graph, air-routes, is a model of the world airline route network between 3,373 airports including 43,400 routes. The examples presented will work unmodified with the air-routes.graphml file loaded into the Gremlin console running with a TinkerGraph. How to set that environment up is covered in the "Downloading, installing and launching the console" section below.

TinkerGraph is an in-memory graph, meaning nothing gets saved to disk automatically. It is included as part of the Apache TinkerPop download. The goal of this tutorial is to allow someone with little to no prior knowledge, to get up and going quickly using the Gremlin Console and the air-routes graph. Later in the book we discuss using additional technologies such as JanusGraph, Apache Cassandra, Gremlin Server and Elastic Search. These capabilities enable the creation of scalable and persisted graph stores that can still be explored using Gremlin queries. Writing standalone applications in languages such as Java, Groovy, and Python is also covered in the later chapters.

All work related to this project is being done in the open at GitHub. A list of where to find the key components is provided below. The examples in this book make use of a sample graph called air-routes which contains a graph based on the world airline route network between over 3,370 airports. The sample graph data, quite a bit of sample code and some larger demo applications can all be found at the same GitHub location that hosts the book manuscript. You will also find releases of the book in various formats (HTML, PDF, DocBook/XML, MOBI and EPUB) at the same GitHub location. The sample programs include standalone Java, Groovy, Python and Ruby examples as well as many examples that can be run from the Gremlin Console. There are some differences between using Gremlin from a standalone program and from the Gremlin Console. The sample programs demonstrate several of these differences. The sample applications area contains a full example HTML and JavaScript application that lets you explore the air-routes graph visually. The home page for the GitHub project includes a README.md file to help you navigate the site. Below are some links to various resources included with this book.

Over the last 15 years, TinkerPop, and especially Gremlin, have evolved substantially from their earliest versions. What we now know as Apache TinkerPop is the result of an open source project created in 2009 and moved to the Apache Software Foundation (ASF) in 2015, after the final release of TinkerPop version 2. The first official release of Apache TinkerPop 3.0 came in July of 2015, with the project being promoted to Apache’s "top-level" status the following year.

If you are new to TinkerPop and Gremlin, you can probably skip the next few sections. They appeared in a slightly modified form, as part of the first edition, and provided a way to highlight the arrival of key new features. These notes have been left in the second edition as there are still people using older versions of Gremlin, and it can be useful to have a list like this to cross reference.

Graph database engines that support Apache TinkerPop often take a while to move up to new releases, and it’s always a good idea to verify the exact level the database you are using supports.

This version of the book covers features of Gremlin available as part of the TinkerPop 4.0.0 release. As appropriate, notes and examples have been added, that show other ways to perform tasks that new features may make simpler. In some cases, notes have been added to point out when more recent features first appeared.

This book is mainly intended to be a tutorial in working with graph databases and related technology using the Gremlin query language. However, it is worth spending just a few moments to summarize why it is important to understand what a graph database is, what some good use cases for graphs are and why you should care in a world that is already full of all kinds of SQL and NoSQL databases. In this book we are going to be discussing directed property graphs. At the conceptual level these types of graphs are quite simple to understand. You have three basic building blocks. Vertices (often referred to as nodes), edges and properties. Vertices represent "things" such as people or places. Edges represent connections between those vertices, and properties are information added to the vertices and edges as needed. The directed part of the name means that any edge has a direction. It goes out from one vertex and in to another. You will sometimes hear people use the word digraph as shorthand for directed graph. Consider the relationship "Kelvin knows Jack". This could be modeled as a vertex for each of the people and an edge for the relationship as follows.

Note the arrow which implies the direction of the relationship. If we wanted to record the fact that Jack also admits to knowing Kelvin we would need to add a second edge from Jack to Kelvin. Properties could be added to each person to give more information about them. For example, my age might be a property on my vertex.

It turns out that Jack really likes cats. We might want to store that in our graph as well so we could create the relationship:

Now that we have a bit more in our graph we could answer the question "who does Kelvin know that likes cats?"

This is a simple example but hopefully you can already see that we are modelling our data the way we think about it in the real world. Armed with this knowledge you now have all of the basic building blocks you need in order to start thinking about how you might model things you are familiar with as a graph.

So getting back to the question "why should I care?", well, if something looks like a graph, then wouldn’t it be great if we could model it that way. Many things in our everyday lives center around things that can very nicely be represented in a graph. Things such as your social and business networks, the route you take to get to work, the phone network, airline route choices for trips you need to take are all great candidates. There are also many great business applications for graph databases and algorithms. These include recommendation systems, crime prevention and fraud detection to name but three.

The reverse is also true. If something does not feel like a graph then don’t try to force it to be. Your videos are probably doing quite nicely living in the object store where you currently have them. A sales ledger system built using a relational database is probably doing just fine where it is and likewise a document store is quite possibly just the right place to be storing your documents. So "use the right tool for the job" remains as valid a phrase here as elsewhere. Where graph databases come into their own is when the data you are storing is intrinsically linked by its very nature, the air routes network used as the basis for all of the examples in this book being a perfect example of such a situation.

Those of you that looked at graphs as part of a computer science course are correct if your reaction was "Surely graphs have been around for ages, why is this considered new?". Indeed, Leonard Euler is credited with demonstrating the first graph problem and inventing the whole concept of "Graph Theory" all the way back in 1763 when he investigated the now famous "Seven Bridges of Koenigsberg" problem.

If you want to read a bit more about graph theory and its present-day application, you can find a lot of good information online. Here’s a Wikipedia link to get you started: https://en.wikipedia.org/wiki/Graph_theory

So, given Graph Theory is anything but a new idea, why is it that only recently we are seeing a massive growth in the building and deployment of graph database systems and applications? At least part of the answer is that computer hardware and software has reached the point where you can build large big data systems that scale well for a reasonable price. In fact, it’s even easier than ever to build the large systems because you don’t have to buy the hardware that your system will run on when you use the cloud.

While you can certainly run a graph database on your laptop—​I do just that every day—​the reality is that in production, at scale, they are big data systems. Large graphs commonly have many billions of vertices and edges in them, taking up petabytes of data on disk. Graph algorithms can be both compute- and memory-intensive, and it is only fairly recently that deploying the necessary resources for such big data systems has made financial sense for more everyday uses in business, and not just in government or academia. Graph databases are becoming much more broadly adopted across the spectrum, from high-end scientific research to financial networks and beyond.

Another factor that has really helped start this graph database revolution is the availability of high-quality open source technology. There are a lot of great open source projects addressing everything from the databases you need to store the graph data, to the query languages used to traverse them, all the way up to visually displaying graphs as part of the user interface layer. In particular, it is so-called property graphs where we are seeing the broadest development and uptake. In a property graph, both vertices and edges can have properties (effectively, key-value pairs) associated with them. There are many styles of graph that you may end up building and there have been whole books written on these various design patterns, but the property graph technology we will focus on in this book can support all of the most common usage patterns. If you hear phrases such as directed graph and undirected graph, or cyclic and acyclic graph, and many more as you work with graph databases, a quick online search will get you to a place where you can get familiar with that terminology. A deep discussion of these patterns is beyond the scope of this book, and it’s in no way essential to have a full background in graph theory to get productive quickly.

A third, and equally important, factor in the growth we are seeing in graph database adoption is the low barrier of entry for programmers. As you will see from the examples in this book, someone wanting to experiment with graph technology can download the Apache TinkerPop package and as long as Java 8 is installed, be up and running with zero configuration (other than doing an unzip of the files), in as little as five minutes. Graph databases do not force you to define schemas or specify the layout of tables and columns before you can get going and start building a graph. Programmers also seem to find the graph style of programming quite intuitive as it closely models the way they think of the world.

Graph database technology should not be viewed as a "rip and replace" technology, but as very much complementary to other databases that you may already have deployed. One common use case is for the graph to be used as a form of smart index into other data stores. This is sometimes called having a polyglot data architecture.

The words node and vertex are synonymous when discussing a graph. Throughout this book you may find both words used. However, as the Apache TinkerPop documentation almost exclusively uses the word vertex, as much as possible when discussing Gremlin queries and other concepts, I endeavor to stick to the word vertex or the plural form vertices. As this book has evolved, I realized my use of these terms had become inconsistent and as I continue to make updates, I plan, with a few exceptions, such as when discussing binary trees, to standardize on vertex rather than node. In that way, this book will be consistent with the official TinkerPop documentation. Similarly, when discussing the connections between vertices I use the term edge or the plural form, edges. In other books and articles you may also see terms like relationship or arc used. Again these terms are synonymous in the context of graphs.

Apache TinkerPop is a graph computing framework and top level project hosted by the Apache Software Foundation. The homepage for the project is located at this URL: http://tinkerpop.apache.org/

The programming interfaces allow providers of graph databases to build systems that are TinkerPop enabled and allow application programmers to write programs that talk to those systems.

Any TinkerPop enabled graph databases can be accessed using the Gremlin query language and corresponding API. We can also use the TinkerPop API to write client code, in languages like Java, that can talk to a TinkerPop enabled graph. For most of this book we will be working within the Gremlin console with a local graph. However in Chapters 7 and 8 we take a look at Gremlin Server and some other TinkerPop enabled environments. Most of Apache TinkerPop has been developed using Java but there are also bindings available for many other programming languages such as Groovy, Python, Go, Javascript, and C#. Parts of TinkerPop are themselves developed in Groovy, most notably the Gremlin Console. The nice thing about that is that we can use Groovy syntax along with Gremlin when entering queries into the Console or sending them via REST API to a Gremlin Server. All of these topics are covered in detail.

The queries used as examples in this book have been tested with Apache TinkerPop version 4.0.0 as well as some prior releases where appropriate. Tests were performed using the TinkerGraph in memory graph and the Gremlin console, as well as other TinkerPop enabled graph stores.

The Gremlin Console is a fairly standard REPL (Read Eval Print Loop) shell. It is based on the Groovy console and if you have used any of the other console environments such as those found with Scala, Python and Ruby you will feel right at home here. The Console offers a low overhead (you can set it up in seconds) and low barrier of entry way to start to play with graphs on your local computer. The console can actually work with graphs that are running locally or remotely but for the majority of this book we will keep things simple and focus on local graphs.

To follow along with this tutorial you will need to have installed the Gremlin console or have access to a TinkerPop/Gremlin enabled graph store such as TinkerGraph or JanusGraph.

Regardless of the environment you use, if you work with Apache TinkerPop enabled graphs, the Gremlin console should always be installed on your machine!

As well as the Gremlin Console, the TinkerPop download includes an implementation of an in-memory graph store called TinkerGraph. This book was mostly developed using TinkerGraph but we also tested everything using JanusGraph. We will introduce JanusGraph later in the "Getting started with JanusGraph" section. The nice thing about TinkerGraph is that for learning and testing things you can run everything you need on your laptop or desktop computer and be up and running very quickly. We will also explain how to get started with the Gremlin Console and TinkerGraph a bit later in this section.

TinkerPop defines a number of capabilities that a graph store should support. Some are optional others are not. If supported, you can query any TinkerPop enabled graph store to see which features are supported using a command such as graph.features() once you have established the graph object. We will look at how to do that soon. The following list shows the features supported by TinkerGraph. This is what you would get back should you call the features method provided by TinkerGraph. We have arranged the list in two columns to aid readability. Don’t worry if not all of these terms make sense right away - we’ll get there soon!

TinkerGraph is really useful while learning to work with Gremlin and great for testing things out. One common use case where TinkerGraph can be very useful is to create a sub-graph of a large graph and work with it locally. TinkerGraph can even be used in production deployments if an all in memory graph fits the bill. Typically, TinkerGraph is used to explore static (unchanging) graphs but you can also use it from a programming language like Java and mutate its contents if you want to. However, TinkerGraph does not support some of the more advanced features you will find in implementations like JanusGraph such as transactions and external indexes. We will cover these topics as part of the discussion of JanusGraph in the "Getting started with JanusGraph" section later on. One other thing worth noting in the list above is that UserSuppliedIds is set to true for vertex and edge ID values. This means that if you load a graph file, such as a GraphML format file, that specifies ID values for vertices and edges then TinkerGraph will honor those IDs and use them. As we shall see later this is not the case with some other graph database systems.

When running in the Gremlin Console, support for TinkerGraph should be on by default. If for any reason you find it to be off you, can enable it by issuing the following command.

Once the TinkerGraph plugin is enabled you will need to close and re-load the Gremlin console. After doing that, you can create a new TinkerGraph instance from the console as follows

which is shorthand for

In general you will not need access to the graph object, and most operations can be performed using graph traversals spawned from the g object. One exception to this is when you want to ask a graph like TinkerGraph what features it supports. In such cases you still need to use

In some cases you will want to pass parameters to the open method providing more information on how the graph is to be configured. We will explore those options later on. The variable called g created above is known as a graph traversal source and will be used throughout the book at the start of each query we write.

Along with this book we have provided what is, in big data terms, a very small, but nonetheless real-world graph that is stored in GraphML, a standard XML format for describing graphs that can be used to move graphs between applications. The graph, air-routes is a model we built of the world airline route network that is fairly accurate.

Of course, in the real world, routes are added and deleted by airlines all the time so please don’t use this graph to plan your next vacation or business trip! However, as a learning tool we hope you will find it useful and easy to relate to. If you feel so inclined you can load the file into a text editor and examine how it is laid out. As you work with graphs you will want to become familiar with popular graph serialization formats. Two common ones are GraphML and GraphSON. The latter is a JSON format that is defined by Apache TinkerPop and heavily used in that environment. GraphML is widely recognized by TinkerPop and many other tools as well such as Gephi, a popular open source tool for visualizing graph data. A lot of graph ingestion tools also still use comma separated values (CSV) format files.

We will briefly look at loading and saving graph data in Sections 2 and 4. We take a look at different ways to work with graph data stored in text format files including importing and exporting graph data in the "COMMON GRAPH SERIALIZATION FORMATS" section towards the end of the book.

The air-routes graph contains several vertex types that are specified using labels. The most common ones being airport and country. There are also vertices for each of the seven continents (continent) and a single version vertex that we provided as a way to test which version of the graph you are using.

Routes between airports are modeled as edges. These edges carry the route label and include the distance between the two connected airport vertices as a property called dist. Connections between countries and airports are modelled using an edge with a contains label.

Each airport vertex has many properties associated with it giving various details about that airport including its IATA and ICAO codes, its description, the city it is in and its geographic location.

Specifically, each airport vertex has a unique ID, a label of airport and contains the following properties. The word in parenthesis indicates the type of the property.

We can use Gremlin once the air route graph is loaded to show us what properties an airport vertex has. As an example here is what the Austin airport vertex looks like. We will explain the steps that make up the Gremlin query shortly. First we need to dig a little bit into how to load the data and configure a few preferences.

Even though the airport vertex label is airport we chose to also have a property called type that also contains the string airport. This was done to aid with indexing when working with other graph database systems and is explained in more detail later in this book.

You may have noticed that the values for each property are represented as lists (or arrays if you prefer), even though each list only contains one element. The reasons for this will be explored later in this book but the quick explanation is that this is because TinkerPop allows us to associate a list of values with any vertex property. We will explore ways that you can take advantage of this capability in the "Attaching multiple values (lists or sets) to a single property" section.

The full details of all the features contained in the air-routes graph can be learned by reading the comments at the start of the air-routes.graphml file or reading the README.txt file.

The graph currently contains a total of 3,619 vertices and 50,148 edges. Of these 3,374 vertices are airports, and 43,400 of the edges represent routes. While in big data terms this is really a tiny graph, it is plenty big enough for us to build up and experiment with some very interesting Gremlin queries.

Lastly, here are some statistics and facts about the air-routes graph. If you want to see a lot more statistics check the README.txt file that is included with the air-routes graph.

Here are the Top 15 airports sorted by overall number of routes (in and out). In graph terminology this is often called the degree of the vertex or just vertex degree.

Throughout this book you will find Gremlin queries that can be used to generate many of these statistics.

Here is some code you can load the air routes graph using the Gremlin Console by putting it into a file and using :load to load and run it or by entering each line into the console manually. These commands will setup the console environment, create a TinkerGraph graph and load the air-routes.graphml file into it. Some extra console features are also enabled.

These commands create an in-memory TinkerGraph which will use LONG values for the vertex, edge and vertex property IDs. As part of loading a graph we need to setup a graph traversal source object called g which we will then refer to in our subsequent queries of the graph. We discussed the :set max-iteration command in Setting up console preferences.

If you are using a different graph environment and GraphML import is supported, you can still load the air-routes.graphml file by following the instructions specific to that system. Once loaded, the queries below should still work either unchanged or with minor modifications.

If you download the load-air-routes-graph34.groovy file, once the console is up and running you can load that file by entering the command below. Doing this will save you a fair bit of time as each time you restart the console you can just reload your configuration file and the environment will be configured and the graph loaded and you can get straight to writing queries.

Once you have the Gremlin Console up and running and have the graph loaded, if you feel like it you can cut and paste queries from this book directly into the console to see them run.

Once the air-routes graph is loaded you can enter the following command and you will get back information about the graph. In the case of a TinkerGraph you will get back a useful message telling you how many vertices and edges the graph contains. Note that the contents of this message will vary from one graph system to another and should not be relied upon as a way to keep track of vertex and edge counts. We will look at some other ways of counting things a bit later.

When using TinkerGraph, the message you get back will look something like this.

Sometimes, especially when assigning a result to a variable and you are not interested in seeing all the steps that Gremlin took to get there, the Gremlin console displays more output than is desirable. An easy way to prevent this is to just add an empty list ";[]" to the end of your query as follows.

Some graph implementations have strict requirements on the use of an index. This means that a schema and an index must be in place before you can work with a graph and that you can only begin a traversal by referencing a property in the graph that is included in the index. While that is, for the most part, outside the scope of this book, it should be pointed out that some of the queries included in this material will not work on any graph system that requires all queries to be backed by an index. Such graph stores tend not to allow what are sometimes called full graph searches for cases where a particular item in a graph is not backed by an index. One example of this is vertex and edge labels which are typically not indexed but are sometimes very useful items to specify at the start of a query.

As most of the examples in this book are intended to work just fine with only a basic TinkerGraph the subject of indexes is not covered in detail until Chapter 6 "MOVING BEYOND THE GREMLIN CONSOLE" . However, as TinkerGraph does have some indexing capability we have also included some discussion of it in the "Introducing TinkerGraph indexes" section. In Chapter 7, where JanusGraph is introduced, we have included a more in depth discussion of indexing as part of that coverage. You should always refer to the specific documentation for the graph system you are using to decide what you need to do about creating an index and schema for your graph.

We won’t be discussing the creation of an explicit schema again until Chapter 7 "Getting started with JanusGraph". When working with TinkerGraph there is no need to define a schema ahead of time. The types of each property are derived at creation time. This is a really convenient feature and allows us to get productive and do some experimenting really quickly.

Gremlin is the name of the graph traversal and query language that TinkerPop provides for working with property graphs. Gremlin can be used with any graph store that is Apache TinkerPop enabled. Gremlin is a fairly imperative language but also has some more declarative constructs as well. Using Gremlin we can traverse a graph looking for values, patterns and relationships, we can add or delete vertices and edges, we can create sub-graphs, and lots more.

A graph query is often referred to as a traversal as that is what we are in fact doing. We are traversing the graph from a starting point to an ending point. Traversals consist of one or more steps (essentially methods) that are chained together.

As we start to look at some simple traversals here are a few steps that you will see used a lot. Firstly, you will notice that almost all traversals start with either a g.V() or a g.E(). Sometimes there will be parameters specified along with those steps but we will get into that a little later. You may remember from when we looked at how to load the air-routes graph in Section 2 we used the following instruction to create a graph traversal source object for our loaded graph.

Once we have a graph traversal source object we can use it to start exploring the graph. The V step returns vertices and the E step returns edges. You can also use a V step in the middle of a traversal as well as at the start but we will examine those uses a little later. The V and E steps can also take parameters indicating which set of vertices or edges we are interested in. That usage is explained in the "Working with IDs" section.

The other steps we need to introduce are the has and hasLabel steps. They can be used to test for a certain label or property having a certain value. We will encounter a lot of different Gremlin steps as we explore various Gremlin queries throughout the book, including many other forms of the has step, but these few are enough to get us started.

You can refer to the official Apache TinkerPop documentation for full details on all of the graph traversal steps that are used in this tutorial. With this tutorial we have not tried to teach every possible usage of every Gremlin step and method, rather, We have tried to provide a good and approachable foundation in writing many different types of Gremlin query using an interesting and real-world graph.

Below are some simple queries against the air-routes graph to get us started. It is assumed that the air-routes graph has been loaded already per the instructions above. The query below will return any vertices (nodes) that have the airport label.

This query will return the vertex that represents the Dallas Fort Worth (DFW) airport.

The next two queries combine the previous two into a single query. The first one just chains the queries together. The second shows a form of the has step that we have not looked at before that takes an additional label value as its first parameter.

Here is what we get back from the query. Notice that this is the Gremlin Console’s way of telling us we got back the Vertex with an ID of 8.

So, what we actually got back from these queries was a TinkerPop Vertex data structure. Later in this book we will look at ways to store that value into a variable for additional processing. Remember that even though we are working with a Groovy environment while inside the Gremlin Console, everything we are working with here, at its core, is Java code. So we can use the getClass method from Java to introspect the object. Note the call to next which turns the result of the traversal into an object we can work with further.

The next step that we used above is one of a series of steps that the TinkerPop documentation describes as terminal steps. We will see more of these terminal steps in use throughout this book. As mentioned above, a terminal step essentially ends the graph traversal and returns a concrete object that you can work with further in your application. We will see next and other related steps used in this way when we start to look at using Gremlin from a standalone program a bit later on. We could even add a call to getMethods() at the end of the query above to get back a list of all the methods and their types supported by the TinkerVertex class. If you’d like to jump ahead to learn more about terminal steps you can see more examples in the "Assigning query results to a variable with a terminal step" section.

So far we have mostly just explored queries that look at properties on a vertex or count how many things we can find of a certain type. Where the power of a graph really comes into play is when we start to walk or traverse the graph by looking at the connections (edges) between vertices. The term walking the graph is used to describe moving from one vertex to another vertex via an edge. Typically when using the phrase walking a graph the intent is to describe starting at a vertex traversing one or more vertices and edges and ending up at a different vertex or sometimes, back where you started in the case of a circular walk. It is very easy to traverse a graph in this way using Gremlin. The journey we took while on our walk is often referred to as our path. There are also cases when all you want to do is return edges or some combination of vertices and edges as the result of a query and Gremlin allows this as well. We will explore a lot of ways to modify the way a graph is traversed in the upcoming sections.

The table below gives a brief summary of all the steps that can be used to walk or traverse a graph using Gremlin. You will find all of these steps used in various ways throughout the book. Think of a graph traversal as moving through the graph from one place to one or more other places. These steps tell Gremlin which places to move to next as it traverses a graph for you.

In order to better understand these steps it is worth defining some terminology. One vertex is considered to be adjacent to another vertex if there is an edge connecting them. A vertex and an edge are considered incident if they are connected to each other.

Note that the steps labelled with an * can optionally take the name of one or more edge labels as a parameter. If omitted, all relevant edges will be traversed.

It is sometimes useful, especially when dealing with large graphs, to limit the amount of data that is returned from a query. As shown in the examples below, this can be done using the limit and tail steps. A little later in this book we also introduce the coin step that allows a pseudo random sample of the data to be returned.

Depending upon the implementation, it is probably more efficient to write the query like this, with limit coming before values to guarantee fewer airports are initially returned but it is also possible that an implementation would optimize both the same way.

Note that limit provides a shorthand alternative to range. The first of the two examples above could have been written as follows.

We can also limit a traversal by specifying a maximum amount of time that it is allowed to run for. The following query is restricted to a maximum limit of ten milliseconds. The query looks for routes from Austin (AUS) to London Heathrow (LHR). All the parts of this query are explained in detail later on in this book but we think what they do is fairly clear. The repeat step is explained in detail in the "Shortest paths (between airports) - introducing repeat" section.

Here is what the query above returned when run on our laptop.

If we give the query another 10 milliseconds to run, so 20 in total, you can see that a few more routes were found.

A call to valueMap will return all of the properties of a vertex or edge as an array of key:value pairs. Basically what in Java terms is called a HashMap. You can also select which properties you want valueMap to return if you do not want them all. Each element in the map can be addressed using the name of the key. By default the ID and label are not included in the map unless a parameter of true is provided.

The query below will return the keys and values for all properties associated with the Austin airport vertex.

If you are using the Gremlin console, the output from running the previous command should look something like this. The unfold step at the end of the query is used to make the results easier to read.

Here are some more examples of how valueMap can be used. If a parameter of true is provided, then the results returned will include the ID and label of the element being examined.

You can also mix use of true along with requesting the map for specific properties. The next example will just return the ID, label and region property.