The within Predicate in Gremlin

  Earlier, we used the has() step to instruct Gremlin how to locate a specific vertex—for example, finding the vertex representing the person named "marko". While this single-value comparison is common, Gremlin also provides powerful mechanisms for matching multiple possible values in a single step. One of the most frequently used tools for this purpose is the within predicate.

 

To understand the within predicate more concretely, it helps to walk through a complete, self-contained example from creating a graph, to adding vertices and edges, and finally querying the graph using within. This section uses a different dataset to reinforce the concept without relying on earlier examples.

 

Step 1: Create a New In-Memory Graph

Apache TinkerPop provides TinkerGraph, an in-memory reference graph implementation that is ideal for learning, experimentation, and examples.

 

Open Gremlin console.

$./bin/gremlin.sh 
WARNING: A restricted method in java.lang.System has been called
WARNING: java.lang.System::loadLibrary has been called by org.fusesource.hawtjni.runtime.Library in an unnamed module (file:/Users/krishna/Documents/Softwares/apache-tinkerpop-gremlin-console-3.8.0/lib/jansi-1.17.1.jar)
WARNING: Use --enable-native-access=ALL-UNNAMED to avoid a warning for callers in this module
WARNING: Restricted methods will be blocked in a future release unless native access is enabled


         \,,,/
         (o o)
-----oOOo-(3)-oOOo-----
plugin activated: tinkerpop.server
plugin activated: tinkerpop.utilities
plugin activated: tinkerpop.tinkergraph
gremlin>

Execute following statement to create new Graph.

graph = TinkerGraph.open()
g = graph.traversal()

  

gremlin> graph = TinkerGraph.open()
==>tinkergraph[vertices:0 edges:0]
gremlin> g = graph.traversal()
==>graphtraversalsource[tinkergraph[vertices:0 edges:0], standard]
gremlin> 

   

At this point:

 

·      graph represents an empty graph stored entirely in memory.

·      g is a GraphTraversalSource, which is the entry point for all Gremlin traversals.

 

Step 2: Create Vertices

Next, add a few vertices representing employees in an organization.

Step 2: Create Vertices

Next, add a few vertices representing employees in an organization.

alice = g.addV('employee').
            property('name', 'Alice').
            property('department', 'Engineering').
            property('experience', 8).
            next()

bob = g.addV('employee').
          property('name', 'Bob').
          property('department', 'Engineering').
          property('experience', 5).
          next()

carol = g.addV('employee').
            property('name', 'Carol').
            property('department', 'HR').
            property('experience', 6).
            next()

gremlin> alice = g.addV('employee').
......1>             property('name', 'Alice').
......2>             property('department', 'Engineering').
......3>             property('experience', 8).
......4>             next()
==>v[0]
gremlin> 
gremlin> bob = g.addV('employee').
......1>           property('name', 'Bob').
......2>           property('department', 'Engineering').
......3>           property('experience', 5).
......4>           next()
==>v[4]
gremlin> 
gremlin> carol = g.addV('employee').
......1>             property('name', 'Carol').
......2>             property('department', 'HR').
......3>             property('experience', 6).
......4>             next()
==>v[8]
gremlin> 

After this step:

·      Three vertices with the label employee exist in the graph.

·      Each vertex has properties such as name, department, and experience.

 

Step 3: Create Edges Between Vertices

Now, establish relationships between employees, for example, collaboration relationships

g.addE('collaborates_with').
  from(alice).
  to(bob)

g.addE('collaborates_with').
  from(bob).
  to(carol)

gremlin> g.addE('collaborates_with').
......1>   from(alice).
......2>   to(bob)
==>e[12][0-collaborates_with->4]
gremlin> 
gremlin> g.addE('collaborates_with').
......1>   from(bob).
......2>   to(carol)
==>e[13][4-collaborates_with->8]
gremlin>

   

These edges describe how employees interact but are not strictly required to demonstrate within. They are included to make the graph more realistic and complete.

 

Step 4: Query Using within

Suppose the requirement is to find the experience values of employees named "Alice" and "Carol". Instead of writing multiple filters, within allows this condition to be expressed succinctly.

 

Without using within

 

g.V().
  hasLabel('employee').
  or(
    has('name', 'Alice'),
    has('name', 'Carol')
  ).
  values('experience')

gremlin> g.V().
......1>   hasLabel('employee').
......2>   or(
......3>     has('name', 'Alice'),
......4>     has('name', 'Carol')
......5>   ).
......6>   values('experience')
==>8
==>6

   

We can get the above result using within like below.

 

g.V().
  has('employee', 'name', within('Alice', 'Carol')).
  values('experience')

gremlin> g.V().
......1>   has('employee', 'name', within('Alice', 'Carol')).
......2>   values('experience')
==>8
==>6

   

Why within Is the Right Tool Here?

The within predicate is ideal when:

 

·      Multiple acceptable values are known in advance

·      The traversal should remain compact and expressive

·      The intent is to test set membership, not equality against a single value

 

Conceptually, within behaves like asking "Is this property value one of the values in this list?". This makes it both readable and scalable as the number of comparison values grows.

 

Inspecting Complete Vertex Details with valueMap(true)

So far, the examples have focused on extracting individual property values using steps such as values('experience'). While this is useful for targeted queries, it is often necessary—especially during learning, debugging, or exploratory analysis—to inspect all details of the matching vertices. Gremlin provides the valueMap() step for exactly this purpose.

 

Using valueMap(true) to Retrieve Full Vertex Information

The valueMap() step returns a map of property keys to their corresponding values for each element in the traversal. When the argument true is supplied, Gremlin also includes the element metadata:

 

·      Vertex identifier (id)

·      Vertex label (label)

 

Consider the following traversal:

g.V().
  has('employee', 'name', within('Alice', 'Carol')).
  valueMap(true)

gremlin> g.V().
......1>   has('employee', 'name', within('Alice', 'Carol')).
......2>   valueMap(true)
==>[id:0,label:employee,name:[Alice],department:[Engineering],experience:[8]]
==>[id:8,label:employee,name:[Carol],department:[HR],experience:[6]]

   

When to Use valueMap(true)?

valueMap(true) is especially useful when:

 

·      Exploring a graph interactively in the Gremlin Console

·      Verifying that vertices were created correctly

·      Debugging complex traversals

·      Teaching or documenting graph structures

 

It provides a complete, structured snapshot of each vertex without requiring prior knowledge of the property keys.

 

valueMap(true) vs values()

It is important to distinguish between these two steps:

 

·      values('experience'): Returns only the raw property values, without context.

·      valueMap(true): Returns a rich, self-describing representation that includes metadata and all properties.

 

In practice, values() is preferred for production queries focused on specific attributes, while valueMap(true) is invaluable for understanding and inspecting graph elements.

 

 

Previous                                                    Next                                                    Home