Gremlin Snippets are typically short and fun dissections of some aspect of the Gremlin language. For a full list of all steps in the Gremlin language see the Reference Documentation of Apache TinkerPop™. This snippet is based on Gremlin 3.6.2.This snippet demonstrates its lesson using the data of the "modern" toy graph (image).Please consider bringing any discussion or questions about this snippet to Discord or the Gremlin Users Mailing List.


In recent weeks there have been many questions about the local()-step both in Discord and in TinkerPop’s JIRA. I’d written on this topic once before in Use of local() but it perhaps begs a further revisit. The example that arose from Discord helped inspire this post as it was sufficiently primitive to hopefully clarify usage.

Here’s the primitive example:

gremlin> g.inject([1,2],[1],[1,2]).count(local)
==>2
==>2
==>1
gremlin> g.inject([1,2],[1],[1,2]).map(unfold().count())
==>2
==>2
==>1
gremlin> g.inject([1,2],[1],[1,2]).local(unfold().count())
==>4
==>1

We’d expect the last traversal to behave the same as the other two. The strangest looking thing here is that there are just two results, when we clearly started with three lists that were given to inject(). The local()-step covers a fairly narrow and yet potentially helpful use case, in that it is meant to be used in cases where you want object-local computations. By object-local we’re talking about a particular object and not the objects in the stream as a whole. As a result, the two [1,2] lists which have an equality end up counting to the same object and we get “4”. Demonstrated another way:

gremlin> g.inject([1],[1],[1]).local(unfold().count())
==>3
gremlin> g.inject([1,2],[1,2],[1,2]).local(unfold().count())
==>6

When I see a traversal with local() in it, I always question if it is being used properly. More often than not, folks tend to use local() when they instead intend Scope.local processing, as in count(local) in this case or a map() or flatMap() operation. Always prefer those options, unless you are sure that object-local processing is what you need in your computation.