Home

Awesome

Practical Gremlin: An Apache TinkerPop Tutorial

map

Welcome!

This repository is the home for the source materials, sample code and examples for the book "Practical Gremlin - An Apache TinkerPop Tutorial". This is also the home for the air-routes dataset referenced throughout the book and samples.

Quick Start - the latest version

Preview releases for the second edition are published as HTML automatically as they are authored and can be found here. It should be noted when reading this revision of the book that it is still a draft version and under significant modification, so you can expect volatile changes.

The first edition is still available. To view it in a browser (HTML format) click here or for a PDF version click here. These versions are not typically updated anymore. You will find other formats including MOBI, EPUB and XML (Docbook) in the releases section. The PDF version is currently the "official" version. It has a better table of contents, page numbers, and some better formatting.

LATEST NEWS

Work has begun on the second edition!

September 23rd 2023

Ever since I began working on Practical Gremlin, I viewed it as a living book, and have tried to keep up with new features and changes taking place at Apache TinkerPop, updating the manuscript as TinkerPop and Gremlin evolve. However, and this is great to see, the rate and pace at which new features are appearing in Gremlin has steadily increased over the years. This has made it hard to keep up in a "living book" fashion. Moreover, some of the material currently in Practical Gremlin discusses features and limitations in the language that have since either been improved or deprecated. It's really time to start work on a second edition. I'm excited to announce that Stephen Mallette has graciously offered to help with this task. We have created a V1 branch which archives the first edition progress. Work for the second edition will simply occur on the default branch. Many of the new Gremlin features that need adding to the manuscript are captured in a tracking issue and there is also a planning board that will continue to be used as a way to organize the work ahead. I'm really looking forward to the collaboration with Stephen, and to the production of a fully up-to-date second edition of Practical Gremlin. Please keep an eye on the latest news section here for more updates.

Releases and change history

The most recent changes and additions are tracked in the change history file.

A Special note about releases

Starting with revision 274 (Dec 24th 2017), all of the output files (XML, EPUB, MOBI, HTML and PDF) will now be stored using Git releases. Going forward, this should reduce the amount of disk space required for people who create forks of this project. The release notes and downloadable materials are located here.

Details of how to build the various output formats from the AsciiDoc source are contained in the README.md file under the book folder.

How this book came to be

I forget exactly when, but over a year ago I started compiling a list of notes, hints and tips, initially for my own benefit, of things I had found poorly explained elsewhere while using graph databases and especially using Apache TinkerPop, JanusGraph and Gremlin. Over time that document grew (and continues to grow) and has effectively become a book. After some encouragement from colleagues I have decided to release it as a living book in an open source venue so that anyone who is interested can read it. It is aimed at programmers and anyone using the Gremlin query language to work with graphs. Lots of code examples, sample queries, discussion of best practices, lessons I learned the hard way etc. are included.

While this book remains a work in progress, indeed some sections are still to be filled in, I think there is enough here that people may find it a useful aid to learning the Gremlin graph traversal and query language.

Thanks to all those that have encouraged me to keep going with this adventure!

Kelvin R. Lawrence
October 6th, 2017

Introduction

This book is a work in progress. Feedback (ideally via issue) is very much encouraged and welcomed!

The title of this book could equally well be "A getting started guide for users of graph databases and the Gremlin query language featuring hints, tips and sample queries". It turns out that is a bit too too long to fit on one line for a heading but in a single sentence that describes the focus of this book pretty well.

The book introduces the Apache TinkerPop 3 Gremlin graph query and traversal language via real examples against a real world graph. They are given as a set of working examples against a graph that is also provided in the sample-data folder. The graph, air-routes.graphml, is a model of the world airline route network between 3,367 airports including 43,160 routes. The examples presented will work unmodified with the air-routes.graphml file loaded into the Gremlin console running with a TinkerGraph.

How this site is organized

The book is being written using a text editor in AsciiDoc format. The source manuscript "Practical-Gremlin.adoc" can be found in the /book folder. These files always reflect the most recent updates and will often be ahead of the other formats that are only updated as part of a formal release. You will find formatted HTML and PDF versions of the book in the releases area. Formal releases also include DOCBOOK, EPUB and MOBI versions. These can be viewed using many tools and e-book readers. Note that currently, only the HTML and PDF versions have all the nice colors for source code listings etc.

Included with the book are sample graph data (GraphML) and program files. You will find these, as well as some screen shots and images, and demos in the following folders.

The air-routes data set, along with tools to manipulate it and generate different file formats, is located here:

How the book is organized

This is the current layout of the second edition. As work progresses additional chapters may be added and the layout further refined.

Chapter 1 - INTRODUCTION

Chapter 2 - GETTING STARTED

Chapter 3 - WRITING GREMLIN QUERIES

Chapter 4 - BEYOND BASIC QUERIES

Chapter 5 - MISCELLANEOUS QUERIES AND THE RESULTS THEY GENERATE

Chapter 6 - MOVING BEYOND THE GREMLIN CONSOLE

Chapter 7 - INTRODUCING JANUS GRAPH

Chapter 8 - INTRODUCING GREMLIN SERVER

Chapter 9 - COMMON GRAPH SERIALIZATION FORMATS

Chapter 10 - FURTHER READING

NEWS ARCHIVE