krlawrence / graph

Practical Gremlin - An Apache TinkerPop Tutorial

Practical Gremlin: An Apache TinkerPop Tutorial

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

• [Jul-17-2024] Auto-published the book via GitHub Actions as changes arrive to the 'main' branch.
• [Sep-23-2023] Work has started on a second edition of the book! See the note below for more details.
• [Sep-22-2023] Added a script to the sample-data folder for producing Cypher versions of the air-routes data.
• [Aug-29-2022] Updated versions of the sample data and corresponding demo apps have been uploaded.

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.

• /book
• /sample-data
• /sample-code
• /images
• /demos

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

• /make-route-graph

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

• We start our journey with a brief introduction to Apache Tinkerpop and a quick look at why Graph databases are of interest to us. We also discuss how the book is organized and where to find additional materials; such as sample code and data sets.

Chapter 2 - GETTING STARTED

• Many of the examples throughout the book use the Gremlin Console and TinkerGraph, and both are introduced in this chapter. We also introduce the air-routes example graph - air-routes.graphml - used throughout the book.

Chapter 3 - WRITING GREMLIN QUERIES

• Now that the basics have been covered, things start to get a lot more interesting! It's time to start writing Gremlin queries. We briefly explore how we could have built the 'air-routes' graph using a relational database, and then look at how SQL and Gremlin are both similar in some way,s and very different in others. We then introduce several of the key Gremlin query language '"steps"'. We focus on exploring the graph rather than changing it in this chapter.

Chapter 4 - BEYOND BASIC QUERIES

• Having now introduced Gremlin in some detail, we introduce the Gremlin steps that can be used to create, modify, and delete, data. We present a selection of best practices and start to explore some more advanced query writing.

Chapter 5 - MISCELLANEOUS QUERIES AND THE RESULTS THEY GENERATE

• Using the Gremlin steps introduced in Chapters 3 and 4, we are now ready to use what we have learned so far and write queries that analyze the air-routes graph in more depth, and answer more complicated questions. The material presented includes a discussion of analyzing distances, route distribution, and writing geospatial queries.

Chapter 6 - MOVING BEYOND THE GREMLIN CONSOLE

• The next step in our journey is to move beyond the Gremlin console and take a look at interacting with a TinkerGraph using Java and Groovy applications.

Chapter 7 - INTRODUCING JANUS GRAPH

• As we continue the journey beyond the Gremlin Console, we now also move beyond TinkerGraph. This chapter introduces JanusGraph and includes a discussion of defining schema, managing trabsactions, and different storage and indexing options.

Chapter 8 - INTRODUCING GREMLIN SERVER

• Our journey so far has focussed on working with graphs in a "directly attached" fashion. We now introduce Gremlin Server as a way to deploy and interact with remotely hosted graphs.

Chapter 9 - COMMON GRAPH SERIALIZATION FORMATS

• Having introduced Gremlin Server we take a look at some common Graph serialization file formats along with coverage of how to use them in the context of TinkerPop enabled graphs. We take a close look at the TinkerPop GraphSON (JSON) format which is used extensively when using Gremlin queries in conjunction with a Gremlin Server.

Chapter 10 - FURTHER READING

• Our journey to explore Apache TinkerPop and Gremlin concludes with a look at useful sources of further reading. We present l links to useful web sites where you can find tools and documentation for many of the topics and technologies covered in this book.

---

NEWS ARCHIVE

• [May-04-2022] The latest preview draft of revision 283 (TP 3.5.1) is now available in HTML and PDF versions. See change history for details.
• [Jun-28-2020] I have started creating a series of issues to capture changes and updates I hope to make soon. The issues contain some interesting examples of both new Gremlin features and some additional queries, some of which are quite advanced, that I intend to add to the manuscript as time allows. The issues have been sorted into a Kanban board which can be found in the Projects area.
• [Oct-26-2019] Revision 282 (TP 3.4.4) was just published in all formats. See change history for details.
  [Aug-31-2021] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Aug-02-2021] The latest preview draft of revision 283 (TP 3.5.1) is now available in HTML and PDF versions. See change history for details.
  [Jul-31-2021] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Jul-10-2021] The latest preview draft of revision 283 (TP 3.4.10) is now available in HTML and PDF versions. See change history for details.
  [Mar-21-2021] The latest preview draft of revision 283 (TP 3.4.10) is now available in HTML and PDF versions. See change history for details.
  [Mar-14-2021] The latest preview draft of revision 283 (TP 3.4.10) is now available in HTML and PDF versions. See change history for details.
  [Aug-28-2020] The latest preview draft of revision 283 (TP 3.4.8) is now available in HTML and PDF versions. See change history for details.
  [Feb-01-2020] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Jan-06-2020] The latest draft of revision 283 (TP 3.4.4 preview) is now available in HTML and PDF versions. See change history for details.
  [Oct-13-2019] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Oct-26-2019] Revision 282 (TP 3.4.4) was just published in all formats. See change history for details.
  [Apr-27-2019] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Dec-26-2018] Revision 281 (TP 3.3.4) was just published in all formats. See change history for details.
  [Dec-24-2018] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Sep-29-2018] Updated versions of the sample data and corresponding demo apps have been uploaded.
  [Jul-28-2018] Revision 280 (TP 3.3.3) was just published in all formats. See change history for details.
  [May-29-2018] Revision 279 (TP 3.3.3) was just published in all formats. See change history for details.
  [Mar-28-2018] Revision 278 (TP 3.3.1) was just published in all formats. See change history for details.
  [Feb-11-2018] Revision 277 was just published in all formats. See change history for details.
  [Jan-12-2018] Revision 276 was just published in all formats. Many updates to book and samples.
  [Jan-12-2018] Based on feedback I have decided to rename the book "Practical Gremlin" (see issue #29)
  [Jan-06-2018] Several new Java samples have been added to the sample-code directory and others improved.
  [Jan-03-2018] Revision 275 was just published in all formats. Lots of updates to book and sample code.
  [Dec-24-2017] Revision 274 was just published in all formats. Now using releases to store output files.
  [Dec-12-2017] Revision 273 was just published in all formats. Fixes issue #12. Also added additonal clarifications.
  [Nov-23-2017] Revision 272 was just published in all formats. Many updates to sections 3 and 4.
  [Nov-03-2017] Revision 271 was just published in all formats. Several improvements and additions.
  [Oct-27-2017] Revision 270 was just published in all formats. Fixes issue #6 and adds more to Janus section.
  [Oct-23-2017] Quite a lot has been added to the Janus Graph section - more to come soon
  [Oct-15-2017] Experimental - The /book folder now includes DOCBOOK, EPUB and MOBI format versions of the book.
  [Oct-10-2017] Several sections have been improved, I also made updates to reflect changes made in Tinkerpop 3.3

graph's Issues

Notes

I just had a few notes that I compiled as I read through your work:

• Section 2.1 - "Parts of TinkerPop are themselves developed in Groovy. Most notably the Gremlin Console and the Gremlin Server." - No part of Gremlin Server is written in Groovy (it is just capable of processing groovy strings)
• Section 2.3
  • "As TinkerGraph is intended mostly for learning and testing..." - it would be nice if that phrase wasn't so limiting. There are many production use cases for TinkerGraph. Most tend to revolve around subgraphing (subgraph a large graph for ad-hoc analysis, subgraphs as a return object in application services, subgraphs as caches), but virtually any static graph that fits in memory is almost always better in a TinkerGraph.
  • "When running in the Gremlin Console, support for TinkerGraph is off by default." - it shouldn't be...under what circumstance do you see that? an out-of-the-box install should have that enabled.
  • "we will always use the variable name g for any variable that represents an instance of a graph traversal object" - should be "graph traversal source object"
• Section 2.5.3 - "TinkerPop 2 provided by default a plugin called Tinkerpop.sugar..." - TinkerPop 2 had Gremlin completely Groovy-based via-metaprogramming. If you wanted to use Gremlin you had to involve Groovy. So - the point I'm trying to make is that, TinkerPop 2.x didn't have so much of a plugin for sugar, as sugar was just inherent to Gremlin.
• Section 2.6 - Mentioned earlier, but I'll point it out more generally. "g" is a traversal source (emphasis on "source") and it spawns traversals. I think it's important to ensure that terminology throughout your book.
• Section 3.1.1 - Nice sql/gremlin comparison
• Section 3.2 - The document seems to switch back and forth in places between "node" and "vertex" interchangeably. I think it would be good to stick with "vertex" throughout as that's the language TinkerPop uses. Imagine if Gremlin was were g.N() - hehe
• Section 3.8.4 - Interesting finding with sample() step. I wonder if we could make that better
• Section 4.3 - Nice to see some points on data modelling
• Section 4.5 - Lots of good examples that use the Traversal API - you included a Graph API example or two...maybe consider removing those since we've been trying to keep users away from that graph.addVertex(), vertex.addEdge(), etc.
• Section 4.7.3 - " Certainly with TinkerGraph I have encountered cases where a node and a property share the same ID. " - hmmm, will have to look into that...i thought all vertices/edges/properties used the same AtomicLong counter. is that something that can be reproduced?
• Section 4.8.1 - "The it is Groovy syntax for the thing that came in (in this case a vertex." - It is actually a Traverser, the holder for the Vertex and .get() retrieves that vertex so that you can operate on it. It might be good to link to the reference documentation on Traversers here: http://tinkerpop.apache.org/docs/current/reference/#_the_traverser
• Section 4.9 - Good stuff in there - I'm wondering if there are interesting implications for Gremlin DSLs. The trouble lies in not being able to serialize new elements of P I guess.
• Section 6.1 - "In reality, for a commercial application you would not use TinkerGraph as your graph database." - never underestimate the power of TinkerGraph :)

I hope some of this is useful to you. Thanks for publishing this.

Cannot find link to air-routes.graphml on the html version of the book

mobi format

I convert for my own needs your book to Mobi format. Would you like pull request?

Replace AsciiDoc headings with new recommended style

In issue #16, we want to replace "Janus Graph" with "JanusGraph", which shortens the headings by a single character. However, the AsciiDoc headings currently in use have the same # of characters are the headings, e.g.,

Heading
~~~~~~~

That said, this is a deprecated heading, and was fixed in JanusGraph in this commit which also says:

As described in the Asciidoc best practices document:
http://asciidoctor.org/docs/asciidoc-recommended-practices/#section-titles
using heading markers using underlines of various characters is not recommended
for several reasons:

• hard to remember which character means which level header
• hard to maintain the correct number of characters (must match heading line)

That commit also includes a complete Python script for making this update for AsciiDoc files, which will be used to convert the headings to the new recommended format, and make it easier to cleanup the name format.

Add coverage of SelectTraversalStep added in Tinkerpop 3.3

Add coverage of SelectTraversalStep added in Tinkerpop 3.3

Provide CSV files for airports and routes

It would be useful for people using different graph databases to provide CSV format files containing the airport, route, continent and country data.

Can I get all vertexes and edges from the following query using repeat step ? g.V().repeat(both()).times(2).path()

Can I get all vertexes and edges from the following query using repeat step ?
g.V().repeat(both()).times(2).path()

Add coverage of GraphSONMapper

I realized today when looking at some questions on Stack Overflow that I currently have no coverage of GraphSONMapper. I have coverage of serializing whole graphs but not the results of individual queries. This would be a good thing to add.

c.f. https://stackoverflow.com/questions/49336250/convert-gremlin-console-output-into-json

Issue with querying properties of a vertex

I am using Gremlin version 3.3.0 and not able to query the properties of any vertex.

Example:
g.V(3).valueMap(true).unfold()

The above query doesnot return any result of the properties of vertex 3

Please look into the issue in your book in 2.4. Introducing the air-routes graph and rectify the issue.

lowercased Gremlin queries

In section 4.7.4. "Attaching multiple values (lists or sets) to a single property" http://kelvinlawrence.net/book/Gremlin-Graph-Guide.html#listprop it looks like the Gremlin queries all got lowercased. For example:

g.v().has('code','aus').valuemap()

should be:

g.V().has('code','AUS').valueMap()

MOBI & EPUB versions do not label forward referencing links correctly

Forward referencing links in the text are displayed as "???" or "section_topic" in the MOBI and EPUB versions.

When I look at the DOCBOOK using Yelp they display correctly so I suspect this is a setting I need to add or a bug I need to work around in Pandoc.

Fix inconsistent usage of terms 'node' and 'vertex'

The text currently uses both 'node' and 'vertex' interchangeably. Given that the TinkerPop documentation has standardized on the word 'vertex' this document should follow that lead.

Need to:

1. Add text near the start of the book that explains 'node' and 'vertex' are the same
2. Throughout the remainder of the book change all use of the word 'node' or 'nodes' to be 'vertex' or 'vertices'

Add testing to ensure the book "builds" at all times

The book is built using the script book/make-book.sh; however, syntax errors in the AsciiDoc file can break that build.

We should add a CI build (e.g., Travis) to test every PR and the master branch to ensure that it continues to build.

Proposal:

• @krlawrence needs to visit https://travis-ci.org/krlawrence/graph and enable the repo
• be sure to set the option in settings "only run when .travis.yml is present
• @mbrukman offers to add a .travis.yml to run the build steps in a PR, which will also test that config

Release version should reflect supported TinkerPop version

It has been suggested that the official release versions should also reflect which version of TinkerPop the current version has been tested against. Something like a versioning scheme along the lines of v278/3.3.1 might be a good choice.

See also: https://groups.google.com/forum/#!topic/gremlin-users/p1TViUlaahU

Update air-routes GraphML data set

The air-routes.graphml and air-routes-small.graphml data sets have not been updated since the book was initially uploaded in Oct 2017. The book currently reflects version 77 of the data set. Version 78 of the data set contains over 1,000 new routes and adds several additional airports. In order for the new data set to be integrated the following steps are needed.

1. Upload the latest GraphML files to the sample-data folder.
2. Update the README.md and README-air-routes.txt files in the sample-data folder.
3. Update the parts of the book that introduce the air-routes graph data.
4. Re-run all the queries in the book to reflect the new data set and update the text (non trivial task)
5. Update the demo applications to reflect the new data.

Expand subgraph section

The sub graph section could benefit from more examples and also examples of the results the examples showed generate.

Small typo in 3.3, v278-preview

In v278-preview Section 3.3, 2nd paragraph, last sentence:

These steps tell Gremlin which places to move to next next as it traverses a graph for you.

"next" is accidentally written twice. Should be:

These steps tell Gremlin which places to move to next as it traverses a graph for you.

Add coverage of the `optional` step.

Currently the book is missing any coverage of the optional step.

Add coverage of the new TinkerPop 3.3.1 math() step

TinkerPop 3.3.1 introduces the math() step that adds some nice capabilities. Need to add some coverage.

TYPO ? : 6.1.3. Compiling our code

Hi,

They may be a typo in the CP variable in section "6.1.3. Compiling our code" :

-------- ORIGINAL (full) -----------------------------------
GREMLIN=...
LIBPATH=$GREMLIN/lib/*
EXTPATH=$GREMLIN/ext/*
ADDL=$GREMLIN/ext/tinkergraph-gremlin/lib/*
export CP=$CLASSPATH:$LIBPATH/:$EXTPATH/:$ADDL
javac -cp $CP TinkerGraphTest.java

-------- CORRECTION SUGGESTION (one line) ---
export CP=$CLASSPATH:$LIBPATH:$EXTPATH:$ADDL
(suppression of the "/*" after "$LIBPATH" and "$EXTPATH")

-------- JUSTIFICATION ---------------------------------
The "/" is already at the end of the "LIBPATH" and "EXTPATH"
The result when i do: "echo $CD" is variables names ending with "//*" (concatenation)

I've successfully compiled the "first TinkerPop Java program" with the corrected version while I had errors with the original one.

For information, I used Ubuntu 16.04 LTS

Best regards,

Victor

Update manuscript to reflect TinkerPop 3.3.1 changes and updates

This issue is in addition to issue #21 (math step) as a placeholder/reminder to add coverage of all the other new things in TP 3.3.1

Fix syntax for adding vertices and edges

In section 4.5 Adding vertices, edges and properties, you recommend a way of adding edges which are not valid syntax for Gremlin queries.

Query being referred here:
g.V().has('code','DFW').addE('route').to(V().has('code','XYZ'))

Steps to reproduce:

1. Download the latest Tinkerpop server (currently 3.3.0)

2. Start the server in secure mode which enables the groovy static compilation type check (I removed the ssl authentication for the sake of this demo)
   ./bin/gremlin-server.sh conf/gremlin-server-secure.yaml

3. Run the following commands on the console

gremlin> :remote connect tinkerpop.server conf/remote.yaml
==>Configured localhost/127.0.0.1:8182
gremlin> :remote console
==>All scripts will now be sent to Gremlin Server - [localhost/127.0.0.1:8182] - type ':remote console' to return to local mode
gremlin> g
==>graphtraversalsource[tinkergraph[vertices:0 edges:0], standard]
gremlin> g.addV('airport').property('code','XYZ')
==>v[0]
gremlin> g.addV('airport').property('code','DFW')
==>v[2]
gremlin> g.V().has('code','DFW').addE('route').to(V().has('code','XYZ'))
Script6.groovy: 1: [Static type checking] - Cannot call org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal <org.apache.tinkerpop.gremlin.structure.Vertex, org.apache.tinkerpop.gremlin.structure.Edge>#to(org.apache.tinkerpop.gremlin.process.traversal.Traversal <org.apache.tinkerpop.gremlin.structure.Edge, org.apache.tinkerpop.gremlin.structure.Vertex>) with arguments [org.apache.tinkerpop.gremlin.process.traversal.dsl.graph.GraphTraversal <A extends java.lang.Object, org.apache.tinkerpop.gremlin.structure.Vertex>]
 @ line 1, column 1.
   g.V().has('code','DFW').addE('route').to(V().has('code','XYZ'))
   ^

1 error
Type ':help' or ':h' for help.
Display stack trace? [yN]
gremlin> g.V().has('code','DFW').as('a').V().has('code','XYZ').as('b').addE('route').from('a').to('b')
==>e[4][2-route->0]

As you can see, the query you suggest in the tutorial fails with an error. I have also included an example of a query which achieves the same result.

Why does the syntax work without groovy static compilation?
From what I understand here, the to(V().has('code','XYZ')) part in the query uses anonymous traversal which methods which are parameterized over type in its java implementation in Tinkerpop's implementation. Without static compilation, groovy creates JVM objects at runtime which do not have typed arguments to its type parameters, hence, the runtime succeeds with every parameter type being Object. Once we enable static compile time type inference, it assigns arguments to the type parameters and thus, fails because the syntax is invalid in Java.

Fix incorrect sack example

As reported by @anglepei (I moved your text to here from #75)

Likewise, minus will subtract the values before putting them into the sack. Note that the values are subtracted from the sack’s initialization value.
`g.V().has('code','AUS').sack(assign).by('runways').
V().has('code','SAF').out().
sack(mult).by('runways').sack().fold()

[-5,-2,-1,-4]`

hi,this code should be wrong, it should be minus.

Add a section on using Gremlin with Neo4J

Would be good to add examples of using Gremlin/TinkerPop with Neo4J

Expand coverage of using TinkerPop / Gremlin with Java

This is to track a work item that is already on my todo list, namely to add more coverage of working with Gremlin from Java.

Section 3.3.5. Using multiple as steps with the same label

Section 3.3.5. Using multiple as steps with the same label
when I run this query on janusgraph 0.2.0
g.V(1).as('a').V(2).as('a').select('a')

return:
[v[1],v[2]]

MOBI, EPUB and DOCBOOK versions need improved source highlighting

Apparently the Groovy language type is not recognized by a lot of tools. Asciidoctor and Pygments recognize it so the HTML comes out nicely but the other formats less so.

One option is to change all use of Groovy to Java but first I want to figure out if there are ways to tell the other tools to treat Groovy the same as Java.

Replace "Janus Graph" with "JanusGraph"

The official name of the project (and the trademark that The Linux Foundation holds) is for the single word "JanusGraph", not the two-word phrase "Janus Graph".

The two-word phrase should be globally updated to be a single word.

Unable to load GraphML

Getting the following error on loading air-routes.graphml on Tinkerpop 3:
com.ctc.wstx.exc.WstxUnexpectedCharException: Unexpected character '>' (code 62) expected '='
at [row,col {unknown-source}]: [42,92]

JanusGraph indexing states

It will be great help if you can add subsection under JanusGraph indexes explaining different states of indexing. Recently I was stuck at INSTALLED state of index and couldn't figure out what it means.

I found state diagram on JanusGraph wiki very useful.

Code typo - Section 2.3 Introducing TinkerGraph

Hi,
Many thanks for your work 🥇

In the code listing in section 2.3, at the prompt:
> GraphFeatures ...
should be:
> graph.features() ...

If this helps and it's the type of feedback you would like - let me know and I'll try and contribute.

Explanation in details the sql2gremlin queries

The http://sql2gremlin.com/ has some queries I'm trying to understand what they do and why this is done that way. What this commands produce as result.... Wold be nice to have some clarification on that.

Tidy up placeholder area at the end of Section 5

There are a set of miscellaneous queries sitting at the end of section 5 that either need to be removed or have some text added and move to the appropriate spot in the book.

Add a dedicated section to introduce the constant and identity steps

The book has lots of examples of constant and identity already but the steps should probably their own small introductory sections.

Add coverage of withRemote

Would be good to add coverage of withRemote and using it to connect from a Java program and maybe some other languages as well.

Add coverage of Gremlin ByteCode

The book currently does not cober Gremlin Byte Code. More and more use cases for the usage of Gremlin Byte Code have been emerging and it is now time to add it to the book.

Update LICENSE file to consist of a complete, verbatim copy of Apache 2.0 license

Right now, the LICENSE file has what's called the "short-form" of the Apache license:

Copyright [2017] [Kelvin R. Lawrence]

Licensed under the Apache License, Version 2.0 (the "License");
you may not use the files in this project except in compliance with 
the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

This is the format that can be used in header file comments, for example, but it's not the complete text of the license, which also means that GitHub doesn't automatically detect it and label the repo as being licensed under the Apache 2.0 license.

Any objections to replacing the contents of the LICENSE file with a verbatim copy of the full Apache 2.0 license?

REPL - Read Execute Print Loop?

Only a minor issue and I might be wrong, but I know this term as Read Eval Print Loop.

Use GitHub releases for book version build outputs

Right now, new builds of the book are being submitted via Git to https://github.com/krlawrence/graph/tree/master/book which is growing the total size of the Git repo (since Git history stores all past versions), even though typically users will only want the latest version, while developers need to keep syncing the full Git history to contribute to this repo.

What about using the GitHub "Releases" feature (which seems to be disabled in this repo) to store each new build instead of keeping it in version control?

Verify examples against TinkerPop 3.3.3

Need to run the regression tests against newly release TinkerPop 3.3.3

Update samples/examples that use deprecated form of addV()

The form of addV that takes a label and property values is now deprecated.

so

g.V().addV(label,"airport","code","AUS"

should now be

g.V().addV("airport").property("code","AUS")

Add coverage of Gremlin console color coding settings

Should add some coverage of the settings that allow the output from the Gremlin console to be color coded to the Gremlin console introduction section. The official docs have coverage of these settings at https://tinkerpop.apache.org/docs/current/reference/#gremlin-console

Gremlin query not working

g.V().hasLabel('airport').groupCount().by('country').order(local).by(valueDecr)

The above query is not working as it is not displaying the number of airports in decreasing order but only displaying its list.

Please, check the above issue and reply.

One more issue how to find the country having the highest number of airports ?

Thanks for the wonderful book you have written.

Expand Graphson coverage to include new Graphson v3

Need to add coverage of the new Graphson V3 format and explain how to handle older formats

Expand TinkerGraph coverage to include automatic serialization

The book shows how to load and save graphs using GraphML and GraphSON but does not cover the explicit serialize automatically on graph.close() or load automatically on graph instance creation configuration settings.

Change book title to Practical Gremlin

I have had a few people point out that the current title of the book (Graph Databases, Gremlin and TinkerPop - a Tutorial) is a bit of a mouthful to quote when referencing this work. I agree! Moving forward I am going to rename the book "Practical Gremlin" with a subtitle of something like "An Apache TinkerPop Tutorial" This way we can all just refer to Practical Gremlin - much simpler!

Thank You

Not a new issue, but you solved an existing one. Thanks for the hard work on this.

Add coverage of TinkerPop strategies

It would be good to have a section that covers use of the various strategies such as the subgraph strategy.

Add a change history file to the project

Add more focused coverage of collection usage in traversals

From the Gremlin users list: (thanks Marc)
https://groups.google.com/forum/#!topic/gremlin-users/Dhdct_f5bSw

The book is indeed growing into a comprehensive and easy to read tour through the TinkerPop! If there is one thing I can suggest, it is the following. Throughout the book you can see examples how the Traversal can hold the gathered information in standard collections such as lists, sets and maps and how you can create and manipulate these collections with various steps to get the specified output from a query. From the questions to this user list we know that both beginning and somewhat experienced gremlin users have trouble in really mastering this working with collections in a Traversal. Both your book and the TinkerPop ref docs miss a grand overview of the possibilities of creating and manipulating intermediate and result collections. So I feel this is a perspective for which a dedicated section would be justified.