Apache TinkerPop is an open-source graph computing framework designed to support the modeling, traversal, and analysis of graph-structured data. Rather than being a single product or database, TinkerPop is best understood as a foundational technology stack for graph systems. It defines common abstractions, APIs, and traversal semantics that enable developers to work consistently across a wide range of graph implementations/databases.
At its core, TinkerPop provides a set of well-defined interfaces for property graphs, along with a powerful traversal language and execution engine. Around this core exists a broader ecosystem that includes:
· Multiple graph databases and engines that implement the TinkerPop APIs
· Graph processors optimized for OLTP, OLAP, or hybrid workloads
· Third-party libraries that extend traversal capabilities, analytics, visualization, and integration
This combination of core components and ecosystem integrations gives TinkerPop both its strength and its perceived complexity. For newcomers—regardless of prior experience with graphs—the breadth of technologies can feel overwhelming, particularly when encountering the reference documentation for the first time.
Understanding where to begin is therefore a critical question.
Finding an Entry Point into TinkerPop
A common challenge when approaching TinkerPop is deciding how to start learning. Should the focus be on graph theory, data modeling, APIs, or database implementations? While all of these topics matter, TinkerPop intentionally provides a clear and practical entry point: Gremlin.
Gremlin is the primary traversal language of Apache TinkerPop. It is the most visible and widely used component of the framework, and it serves as the main interface through which developers interact with graphs. More importantly, Gremlin embodies the core ideas of TinkerPop:
· A uniform way to traverse graph structures
· A language that is both human-readable and machine-executable
· A model that works consistently across different graph systems
By learning Gremlin, developers gain immediate, hands-on access to the TinkerPop ecosystem without needing to understand every underlying component upfront.
Why Start with Gremlin?
Gremlin is intentionally designed to be approachable while remaining expressive and powerful. It allows developers to explore a graph incrementally, building traversals step by step and observing results as they go. This interactive nature makes Gremlin particularly well suited for learning.
From a conceptual perspective, Gremlin teaches how to think in graphs. Rather than issuing declarative queries that describe only the desired outcome, Gremlin encourages a traversal-oriented mindset—moving through vertices and edges, filtering, branching, and aggregating along the way. This shift in thinking is essential for effective graph application development.
Starting with Gremlin offers several advantages:
· Immediate productivity without deep upfront theory
· A concrete way to understand graph structure and behavior
· Skills that transfer directly across TinkerPop-enabled graph systems
In short, Gremlin provides the fastest path from zero to meaningful graph interaction.
The TinkerPop Workout
To lower the barrier to entry even further, this book begins with a focused, time-boxed introduction: The TinkerPop Workout — by Gremlin.
The objective is not mastery, but momentum. By the end of the workout, readers should be able to:
· Understand the role of Gremlin within Apache TinkerPop
· Execute basic traversals against a graph
· Read and reason about Gremlin traversal steps
· Feel comfortable experimenting and exploring further
Think of this workout as a warm-up session. It prepares the mental model required for deeper topics that follow, such as graph modeling, traversal optimization, and system architecture.
With that foundation in place, the broader TinkerPop ecosystem becomes far less intimidating—and far more approachable.
Welcome to Apache TinkerPop.
Getting Started with the Gremlin Console
The most straightforward way to begin working with Apache TinkerPop is through the Gremlin Console. The console is an interactive command line environment that allows developers to write, execute, and experiment with Gremlin traversals in real time. It requires no external graph database to get started and is therefore ideal for learning, prototyping, and exploration.
The Gremlin Console is distributed as a standalone binary package and runs on the Java Virtual Machine. Once launched, it provides an immediate REPL (Read–Eval–Print Loop) experience for Gremlin, enabling rapid feedback and iterative learning.
Downloading the Gremlin Console
To begin, download the Gremlin Console binary distribution from the official Apache TinkerPop website. Apache provides a geographically distributed set of mirrors, the following link will automatically redirect to a nearby mirror:
https://www.apache.org/dyn/closer.lua/tinkerpop/3.8.0/apache-tinkerpop-gremlin-console-3.8.0-bin.zip
This archive contains everything required to run the console, including all necessary dependencies.
Installing and Launching the Console
After downloading the binary archive, extract its contents and start the console from the command line.
$ unzip apache-tinkerpop-gremlin-console-3.8.0-bin.zip $ cd apache-tinkerpop-gremlin-console-3.8.0 $ bin/gremlin.sh
$./bin/gremlin.sh
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::loadLibrary has been called by org.fusesource.hawtjni.runtime.Library in an unnamed module (file:/Users/krishna/Documents/Softwares/apache-tinkerpop-gremlin-console-3.8.0/lib/jansi-1.17.1.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled
\,,,/
(o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.utilities
plugin activated: tinkerpop.tinkergraph
gremlin>
Once the script executes successfully, the Gremlin Console starts and presents a prompt, indicating that it is ready to accept Gremlin commands.
What the Gremlin Console Provides
At this stage, no external configuration is required. The console includes an in-memory graph implementation that allows immediate experimentation with vertices, edges, and traversals. This environment is intentionally minimal and safe for learning:
· No database installation or setup is needed
· Traversals can be executed interactively
· Results are returned instantly for inspection
The Gremlin Console serves as a sandbox for developing intuition about graph traversal, step composition, and Gremlin syntax. As concepts become clearer, the same Gremlin traversals can later be applied to production grade graph systems that implement the TinkerPop APIs.
With the console running, the next step is to begin issuing Gremlin commands and exploring how traversals operate over a graph.
Creating and Exploring a Simple Graph with Gremlin
Once the Gremlin Console is running, the best way to learn Gremlin is by building a small graph by hand and interacting with it. This approach makes traversal concepts concrete and allows immediate experimentation.
The following examples use the in-memory TinkerGraph that ships with the Gremlin Console. No external database or configuration is required.
Initialize an in-memory graph by executing below commands from Gremlin Console.
graph = TinkerGraph.open() g = graph.traversal()
gremlin> graph = TinkerGraph.open() ==>tinkergraph[vertices:0 edges:0] gremlin> g = graph.traversal() ==>graphtraversalsource[tinkergraph[vertices:0 edges:0], standard]
The first command creates a Graph instance named graph, which represents the data structure that Gremlin will operate on.
graph = TinkerGraph.open()
At this point, you have a graph, but Gremlin still cannot execute traversals. This is because a graph by itself does not provide enough execution context. To run traversals, you must also create a TraversalSource.
g = graph.traversal()
The TraversalSource (g) acts as the entry point for all Gremlin queries. It supplies Gremlin with critical execution details, such as:
· Which traversal strategies should be applied
· Which traversal engine should be used
· How traversals should be optimized and executed
In other words, the graph defines what data exists, while the traversal source defines how Gremlin should traverse that data. Only after the traversal source is initialized can Gremlin begin its “journey” through the graph.
Create vertices (5 nodes)
// People
alice = g.addV('person').property('name', 'Alice').property('role', 'Engineer').next()
bob = g.addV('person').property('name', 'Bob').property('role', 'Engineer').next()
carol = g.addV('person').property('name', 'Carol').property('role', 'Manager').next()
// Projects
apollo = g.addV('project').property('name', 'Apollo').property('status', 'Active').next()
zeus = g.addV('project').property('name', 'Zeus').property('status', 'Completed').next()
gremlin> alice = g.addV('person').property('name', 'Alice').property('role', 'Engineer').next()
==>v[0]
gremlin> bob = g.addV('person').property('name', 'Bob').property('role', 'Engineer').next()
==>v[3]
gremlin> carol = g.addV('person').property('name', 'Carol').property('role', 'Manager').next()
==>v[6]
gremlin> apollo = g.addV('project').property('name', 'Apollo').property('status', 'Active').next()
==>v[9]
gremlin> zeus = g.addV('project').property('name', 'Zeus').property('status', 'Completed').next()
==>v[12]
Create edges (10 relationships)
// People working on projects
g.addE('works_on').from(alice).to(apollo).property('since', 2022)
g.addE('works_on').from(alice).to(zeus).property('since', 2021)
g.addE('works_on').from(bob).to(apollo).property('since', 2023)
g.addE('works_on').from(bob).to(zeus).property('since', 2022)
// Management relationships
g.addE('manages').from(carol).to(apollo)
// Collaboration between people
g.addE('collaborates_with').from(alice).to(bob)
g.addE('collaborates_with').from(bob).to(alice)
// Reporting structure
g.addE('reports_to').from(alice).to(carol)
g.addE('reports_to').from(bob).to(carol)
// Oversight
g.addE('oversees').from(carol).to(zeus)
Verify the graph
g.V().count() // => 5 vertices g.E().count() // => 10 edges
gremlin> g.V().count() ==>5 gremlin> gremlin> g.E().count() ==>10
Inspect the edges with properties:
g.E().valueMap(true)
gremlin> g.E().valueMap(true) ==>[id:16,label:works_on,since:2021] ==>[id:17,label:works_on,since:2023] ==>[id:18,label:works_on,since:2022] ==>[id:19,label:manages] ==>[id:20,label:collaborates_with] ==>[id:21,label:collaborates_with] ==>[id:22,label:reports_to] ==>[id:23,label:reports_to] ==>[id:24,label:oversees] ==>[id:15,label:works_on,since:2022]
Example 1: Get all the vertices/nodes as a list
vertices = g.V().toList()
gremlin> vertices = g.V().toList() ==>v[0] ==>v[3] ==>v[6] ==>v[9] ==>v[12]
Example 2: Get the first node values.
g.V(vertices[0].id()).valueMap()
gremlin> g.V(vertices[0].id()).valueMap() ==>[role:[Engineer],name:[Alice]]
Example 3: Get all Edges as a list
edges = g.E().toList()
gremlin> edges = g.E().toList() ==>e[16][0-works_on->12] ==>e[17][3-works_on->9] ==>e[18][3-works_on->12] ==>e[19][6-manages->9] ==>e[20][0-collaborates_with->3] ==>e[21][3-collaborates_with->0] ==>e[22][0-reports_to->6] ==>e[23][3-reports_to->6] ==>e[24][6-oversees->12] ==>e[15][0-works_on->9]
Example 4: Get first edge values.
gremlin> g.E(edges[0]).valueMap() ==>[since:2021]
Example 5: Get all projects Alice works on
g.V().has('name', 'Alice').out('works_on').values('name').toList()
gremlin> g.V().has('name', 'Alice').out('works_on').values('name').toList()
==>Zeus
==>Apollo
Example 6: Get the projects managed by Carol.
g.V().has('name', 'Carol').out('manages').valueMap()
gremlin> g.V().has('name', 'Carol').out('manages').valueMap()
==>[name:[Apollo],status:[Active]]
Example 7: Get all the outgoing edges from Carol.
gremlin> g.V().has('name', 'Carol').outE()
==>e[24][6-oversees->12]
==>e[19][6-manages->9]
Example 8: Get all the incoming edges to Carol.
gremlin> g.V().has('name', 'Carol').inE()
==>e[22][0-reports_to->6]
==>e[23][3-reports_to->6]
In this section, you’ve taken your first steps with TinkerPop and the Gremlin Console. You learned how to instantiate an in-memory graph with TinkerGraph.open() and create a TraversalSource using graph.traversal(), which provides the context needed to navigate and query your graph. Using this setup, you created vertices representing people and projects, and connected them with edges to model relationships such as works_on, manages, collaborates_with, reports_to, and oversees.
By storing vertices in a list, you were able to safely reference them without relying on numeric IDs, making your traversals more readable and reliable. You explored basic traversals to access vertex properties, follow edges to connected vertices, filter results, and answer queries like "Which projects does Alice work on?"" and "Which projects does Carol manage that Alice also works on?" Along the way, you discovered key best practices, such as using property-based lookups instead of literal IDs. While these exercises only scratch the surface of what TinkerPop can do, they provide a solid foundation for more advanced traversals, aggregations, and graph algorithms that you will encounter in the sections ahead.
Previous Next Home
No comments:
Post a Comment