Practical Gremlin: a living TinkerPop book with its own dataset

A book repository, not a library

The README is explicit about what this repository is for. It is the home for the manuscript sources and the code for the book Practical Gremlin, An Apache TinkerPop Tutorial, and it is also the home for the air-routes dataset that the book and the code reference throughout. The audience is named in the same paragraph, programmers and anyone using the Gremlin query language to work with graphs, and the content is described as lots of code, queries, discussion of best practices and lessons learned the hard way. The origin story in the How this book came to be section deserves reading, because it explains the tone. The author began compiling notes for his own benefit, a list of hints and tips about things he had found poorly explained elsewhere while using graph databases, and especially while using Apache TinkerPop, JanusGraph and Gremlin. That document grew into a book, and the decision to release it in an open source venue as a living book is what makes the repository behave the way it does.

Where to read it, and in which formats

The current edition is published automatically as changes are authored, and it is available in three shapes. There is an HTML edition, a PDF edition, and a Markdown version offered through an llms.txt file, which the README describes as more suitably for agents. The book is also the project's reason for existing in a conventional sense, since the repository carries the asciidoc sources, the scripts and the code. The first edition, covering versions prior to 3.8.0, is still available but is no longer updated, and its final publication is tagged as Revision 283. That older edition exists in the standard publishing formats, PDF, HTML, MOBI, EPUB and XML in Docbook, and an archived HTML copy of the first edition is kept online separately. The releases section continues to offer all of these formats as snapshots for ongoing reference, which matters if you are citing the book, because a citation should point at a specific revision rather than at a page that keeps moving.

Why the second edition took two and a half years

The announcement of the second edition, dated September 23 2023, explains the delay and the reasoning in unusual detail. The author had always regarded the book as a living one and kept updating the manuscript as Gremlin evolved, but the rate of new features had increased steadily to the point where keeping up became hard, and parts of the first edition discussed features and limitations that had since been improved or deprecated. The completion note of January 1 2026 gives the rest. The work was delayed by the unexpected introduction of the 3.8.0 release, which did not occur until November 12 2025, and it only made sense to finalise the second edition after that release became official. Choosing 3.8.0 as the base was deliberate, because the expectation in TinkerPop is that Gremlin semantics will not change between 3.8.0 and 4.0.0, which gives this edition a long shelf life. The writing still had to stop somewhere, and the end of 2025 was chosen. Stephen Mallette joined the effort, a V1 branch was created to archive the first edition's progress, and the second edition work happens on the default branch with a tracking issue and a planning board.

Continuous publishing by GitHub Actions

The mechanism that keeps the book current is unusual for a book. The news list records that the PDF version began being auto-published via GitHub Actions as changes arrive on the main branch on 2025-12-17, and that the HTML version had been auto-published the same way since 2024-07-17. A Markdown version and the llms.txt file followed on 2026-09-04. Which means there is no publication step you have to wait for, since a change to the sources in the repository becomes a new edition of the book, in every format, on the next build. The trade-off is the mirror image of the benefit, because the book at any given URL is the current draft rather than a fixed release, so a reader who needs a stable reference has to use the releases, and a reader who wants the latest has to accept that a paragraph can change under them. The change history is tracked in the ChangeHistory.md file at the root, which is the file to read before quoting a specific passage.

The air-routes dataset and the code around it

The dataset is not incidental to the book, because the whole tutorial is built on it. The air-routes dataset is generated, and the news list records that version 1.0 was generated on 2025-10-22. It is referenced throughout the book and in the code, which is what lets the queries in the text be runnable rather than illustrative, and the repository has a make-route-graph directory that appears to hold the tooling for turning the route data into the graph the queries run against. The rest of the code sits in dedicated code and data directories alongside, and there is a bin directory for the scripts that support the book build. For a reader who wants to practise, the combination of a real dataset, the queries that work against it, and the ability to rebuild the graph locally is the useful part, since a graph tutorial that gives you a toy graph of five nodes teaches you the syntax and not the query.

The repository layout and the state of the project

The top level tells you how a book repository is organised, and there is very little in it that is not about the book. There is the book directory with the sources, a code directory, a data directory, the make-route-graph tooling, the images used in the text, the ChangeHistory.md, an AGENTS.md, a CONTRIBUTORS file, a LICENSE and a NOTICE, plus the .github directory holding the workflows that publish the editions. The primary language is recorded as Ruby, which fits the asciidoc toolchain and the scripts that drive the book build. On the licence, the project is Apache 2.0, which is the same licence Apache TinkerPop itself uses, and that is the sensible choice for a book that a company might want to vendor or adapt internally. On maintenance, the last push was on 2026-09-08 and the repository is not archived, so the pipeline is still running. The release history is irregular by design, since releases here mark book revisions rather than software versions, with Revision 283 from 2026-01-12 being the final first edition, before it Revision 282 from 2019 and Revision 281 from 2018.

Editorial conclusion

Practical Gremlin fits a developer learning the Gremlin traversal language who wants more than an API reference, since the book is built around the awkward parts of graph querying and the queries that work, and it fits a team that needs a realistic graph to experiment on, because the air-routes dataset is right there with the code. It is the wrong choice if you need a query engine or a driver, since this repository contains documentation and a data set rather than a runtime, and it is a poor fit if you are working with a TinkerPop 4 style stack, since the second edition deliberately targets 3.8.0 on the expectation that Gremlin semantics hold until 4.0.0. Before you rely on the text, check the ChangeHistory.md and the latest news entries, because the book is republished as the upstream release moves.

Frequently asked questions

Official sources

1. Issues
2. krlawrence/graph on GitHub
3. License: Apache-2.0
4. README
5. Releases