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 it 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 it remains a lot of fun!

Kelvin R. Lawrence
First draft (first edition): October 5th, 2017
Final draft (first edition): May 4th, 2022
First draft (second edition): January 1, 2026 Current draft (second edition): 2026-02-26 16:36:54 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-002-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 server 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.

Except for this section, references to "I" in this book refer to the book’s original author, Kelvin Lawrence. As the editor and co-author of the Second Edition, I didn’t feel as though "I" should become "We" anywhere, as I believe that much of the appeal of this book lies in Kelvin relating his personal discoveries on his journey with Gremlin. I’ve tried to preserve that feeling and voice as much as possible in my many additions and edits.

As I write this section, I realize that I’ve authored many lines of TinkerPop’s Reference Documentation, Tutorials, and Recipes over the years and, as a result, I tend to think there is a certain completeness to the documentation that is officially offered. I think that’s a valuable aspect of the TinkerPop project, yet I’ve also always recognized the importance and impact of this book as a resource for Gremlin users. My personal opinion is that its approach and organization is what allows it to make that helpful impact. Where TinkerPop Documentation has its completeness presented all at once, this book gives you a clear, ramped process to learning Gremlin so that you can make use of that completeness in the official documentation.

In 2023, TinkerPop was in the midst of releasing 3.6.x and 3.7.x release lines which had introduced a number of important new features. Kelvin and I started realizing that Practical Gremlin was falling behind TinkerPop’s continued evolution significantly. With even bigger sets of changes expected on the horizon with 4.0, it felt as though it was time to make an organized effort to produce an updated Second Edition.

We officially announced that work had started on it in September 2023 and with the big release of 3.8.0 in November 2025, we believed it time to polish up the draft and make an official publication of the new edition. As with the First Edition, we expect the book to continue to be a work-in-progress and will make minor publications as new TinkerPop releases appear.

As you read this edition, please keep in mind that it reflects the state of Gremlin and TinkerPop at a particular point in time, but it is also part of an ongoing conversation with the community. Your questions, suggestions, and examples help shape where the book goes next. If you find places where it could be clearer, more helpful, or more complete, your feedback is welcome and will help guide future updates.

Stephen Mallette
Second edition editor and co-author

This book is about learning to think in Gremlin by working through practical examples. It focuses on how to express real graph questions as traversals, how to read and reason about Gremlin code, and how to apply common patterns to your own graphs. As the book evolves, new examples and refinements continue to be added, but the core goal remains the same: to help you build an intuitive understanding of how Gremlin works.

In this book you will find 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,504 airports, including 50,637 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 "Download, install, and launch the Gremlin 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 writing standalone applications in other programming languages such as Java, Groovy, and Python.

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,504 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 in 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 2015, with the project being promoted to Apache’s "top-level" status the following year. After a decade of continuous releases for TinkerPop 3.0, the project released a beta version of 4.0 in January 2025 for early evaluation.

We focus this second edition of the book on the semantics of Gremlin as of TinkerPop release 3.8.0.

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 3.8.0 release. As appropriate, notes and examples have been added that show other ways to perform tasks that new features may simplify. 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, 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 following question: "who does Kelvin know that likes cats?"

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

So getting back to the question of "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 "using 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 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 have 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 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 recent 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 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 11+ is installed, be up and running with zero configuration (other than unzipping 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. This book will prefer the term 'vertex' and 'vertices' as the Apache TinkerPop documentation almost exclusively uses it when discussing Gremlin queries and other concepts. We will only see a shade of the term 'node' when we refer to "supernodes", relating to vertices of an especially high degree, as this term has wide acceptance independently of TinkerPop. By the same token, this book will be consistent with the official TinkerPop documentation when discussing the connections between vertices, where we will 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: https://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#. These bindings help make Gremlin feel comfortable to you as you can work with Gremlin in the idioms of the programming language that you are most familiar with.

Even though this book focuses on Gremlin written with Groovy, you should remember that whatever examples you see in Groovy can easily be converted to any other supported programming language. You need to understand the idioms of the language you are using, and converting should be straightforward. For example, Python prefers snake case compared to Groovy preferring camel-case formatting. Therefore, a Groovy query of 'g.addV("person")' just converts to 'g.add_v("person")' in Python. You will read more about Gremlin translation in the "Translating Gremlin to different programming languages" section.

The queries used as examples in this book have been tested with Apache TinkerPop version 3.8.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 an interactive shell for running Gremlin traversals against a graph. In this book it serves as the main workspace for experimenting with the air-routes graph, trying out examples, and exploring variations of your own. It is based on the Groovy Shell, 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 a low barrier to entry as a 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 console should always be installed on your machine!

TinkerGraph is the in-memory reference implementation that ships with Apache TinkerPop and is included with the Gremlin Console download. It runs inside a single JVM process, stores its data in memory, and is designed primarily for learning, experimentation, and small test graphs, but does have use cases for production workloads in some scenarios.

This book was mostly developed using TinkerGraph 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 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 invaluable 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 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 an advanced transaction system, (though it does have basic transactions that are helpful to certain use cases as of 3.7.0) and external indexes. One other thing worth noting in the list above is that the 'UserSuppliedIds' option 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 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

The shorthand is helpful to save a bit of typing, but you lose reference to the graph instance, which might be helpful when accessing 'graph.features()', creating indices, or initiating close operations on the graph itself. The longer form generally tends to be preferable for this reason. You will read more about this in the "Deep dive on traversal terminology" section.

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.

The examples in this book use a sample dataset called the air-routes graph. It models airports as vertices, flight routes as edges, and includes properties such as airport codes, city and country names, geographic coordinates, and distances between airports. This graph is large enough to be interesting but still small enough to explore comfortably from the Gremlin Console.

While the air-routes graph was built from actual real-world data, 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 modeled 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 parentheses 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 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.

The easiest way to load the air-routes graph is to use the prepackaged version of the dataset that comes with TinkerGraph. We can demonstrate this in the Gremlin Console as follows.

That’s it! The graph is now loaded with the 1.0 version of the dataset. These two lines simplify a longer set of manual steps which we will go through as an explanatory next step so that you can understand the details.

The following code loads the air-routes graph using the 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 set up the console environment, create a TinkerGraph, 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 set up 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.

Once you have the 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 it 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.

Before going much further, it is worth briefly mentioning indexes and schemas. For now, you will be working with TinkerGraph, which does not enforce a formal schema and offers only simple in-memory indexing. That is sufficient for the examples in this chapter, but later chapters will return to these topics in more detail and show how indexes and schemas can have a big impact on query performance and data quality.

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

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 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 examples are enough to get us started.

You can refer to the official Apache TinkerPop documentation for full details on all 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 queries 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 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 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 straightforward 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.

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 labeled with a '*' 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.