discuss terminating steps

[pluradj]

One the most common stumbling blocks that developers run into when building an application with Gremlin is that the reference docs tend to assume that the traversals are being run in the Gremlin Console, which auto-iterates the traversal.

When they move to write a program outside of the console, they need to be aware that they need to iterate the traversal. I had previously added a section to this to the JanusGraph docs.

• https://tinkerpop.apache.org/docs/current/reference/#terminal-steps
• https://docs.janusgraph.org/latest/gremlin.html#_iterating_the_traversal

In the book, there is some mention of terminating steps in Chapter 3.6 http://kelvinlawrence.net/book/Gremlin-Graph-Guide.html#var

[krlawrence]

Thanks @pluradj. I will think about how to call them out more obviously. I agree this is a common stumbling block.

[krlawrence]

Would value your opinion @pluradj . Would it make more sense to add a section up front somewhere in Chapter 3 to go deeper into this (as you mentioned there already is some coverage in Chapter 3) or perhaps instead add a section near the start of Chapter 6 which is where the switch away from the Console to programming languages happens? I do have a brief note about iterate() also in that Chapter but I will agree it is not enough.

[pluradj]

I ran across this again today when using the :record feature. If you don't use the terminating step next() in your example in 2.2.2 Saving output from the console to a file, the result in the text file contains the toString() version of the traversal rather than the execution result.

I think it's worth mentioning terminal steps earlier rather than later. The Gremlin Console has the auto-iteration behavior which makes them unnecessary for single statement queries. If you string together multiple statements in a single line, you would still need to use the terminal steps.

gremlin> x = g.V().count(); "there are " + x + " vertices"
==>there are [GraphStep(vertex,[]), CountGlobalStep] vertices
gremlin> x = g.V().count().next(); "there are " + x + " vertices"
==>there are 6 vertices