From af612c1562b9542f0c1b472bbc6989a73890df32 Mon Sep 17 00:00:00 2001 From: Stephen Mallette Date: Thu, 25 Jan 2024 13:30:47 -0500 Subject: [PATCH] Complete content on terminal steps - added iterate() closes #111 --- book/Section-Beyond-Basic-Queries.adoc | 7 +++--- book/Section-Writing-Gremlin-Queries.adoc | 27 +++++++++++++++++++++++ 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/book/Section-Beyond-Basic-Queries.adoc b/book/Section-Beyond-Basic-Queries.adoc index 9bb9a9a..af6808f 100644 --- a/book/Section-Beyond-Basic-Queries.adoc +++ b/book/Section-Beyond-Basic-Queries.adoc @@ -899,7 +899,8 @@ for (a in vertices) {g.addV("airport").property("code",a[0],"iata",a[1]).iterate ---- Note the call to 'iterate' at the end for without that terminal step, the query would -not execute. +not execute. If you don't recall why 'iterate' is important you can read about it in +the "<>" section. This technique of creating vertices and/or edges using a 'for' loop can also be useful when working with graphs remotely over HTTP connections. It is a very convenient way @@ -916,8 +917,8 @@ vertices.each { ---- [[addinject]] -Adding vertices and edges using inject -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Adding vertices and edges using 'inject' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The previous section on "<>" used the loop semantics of programming languages to add multiple vertices by iterating over an array of data. In tihs diff --git a/book/Section-Writing-Gremlin-Queries.adoc b/book/Section-Writing-Gremlin-Queries.adoc index 8cc4caf..555af75 100644 --- a/book/Section-Writing-Gremlin-Queries.adoc +++ b/book/Section-Writing-Gremlin-Queries.adoc @@ -2201,6 +2201,33 @@ println s [2, 7, 5, 3, 4, 1] ---- +[[ignoringresults]] +Ignoring query results with 'iterate' +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +There are a number of cases where the results of a query are not of interest to you. +A common situation where this happens is when you have a graph mutation query and are +only interested in persisting those changes to the database, but are not interested +in doing anything with the output that the traversal produces. + +[source,groovy] +---- +g.addV('airport').property('code','AUS').as('aus'). + addV('airport').property('code','DFW').as('dfw'). + addE('route').from('aus').to('dfw').iterate() +---- + +In the example above, you can see that we add two vertices and an edge between them +with the return value being the edge. Has we used 'next' as the terminal step, the +query would have returned the newly created edge. With the use of 'iterate' as the +the terminal step, the query has no value returned. The vertices are added to the +graph along with the edge and the edge is discarded. Additional calls to 'next' after +'iterate' will result in a 'NoSuchElementException'. + +The use of 'iterate' can bring some performance improvements because it signals to +the graph that you are not interested in the results which could save some processing +costs (e.g. serialization, network). + [[deepdivetraversals]] Deep dive on traversal terminology ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~