Step-by-Step Debugger

Overview

The Step-by-Step Debugger is a Pro feature that lets you execute Gremlin queries one traversal step at a time. At each step, intermediate results are displayed in the results panel and highlighted on the graph visualization. If you have ever struggled to understand why a multi-step Gremlin query returns unexpected results, the debugger gives you the visibility you need to pinpoint the problem.

Why Gremlin Needs a Debugger

Gremlin queries are compositional. Each step in a traversal transforms the set of traversers flowing through the pipeline: filtering vertices, traversing edges, projecting properties, grouping results, and more. A query like g.V().has('person','age',gt(30)).out('knows').dedup().values('name') chains five distinct operations, and the output of each step feeds into the next. When the final result is wrong, it is often difficult to determine which step introduced the problem without seeing the intermediate state. Traditional database tools show you only the final result. The GremlinStudio debugger shows you every step along the way, making it the most effective way to debug Gremlin queries.

How It Works

1. Write a Gremlin query in the editor.
2. Click the Debug button in the Query Toolbar (or use the keyboard shortcut).
3. The Debug Panel opens below the editor, showing the parsed steps of your query.
4. Click Step to execute one step at a time.
5. Watch as the graph view highlights the currently active traversers at each step.
6. When you have found what you need, click Run to End to execute all remaining steps, or Reset to start over.

Behind the scenes, the debugger parses your Gremlin query into its constituent steps and executes progressively longer prefixes of the query against the database. For example, given the query g.V().has('person','name','Alice').out('knows').values('name'), the debugger executes these prefixes in order:

1. g.V() — returns all vertices in the graph.
2. g.V().has('person','name','Alice') — filters to only the vertex with name Alice.
3. g.V().has('person','name','Alice').out('knows') — traverses outgoing knows edges from Alice and returns the adjacent vertices.
4. g.V().has('person','name','Alice').out('knows').values('name') — extracts the name property from each of those vertices.

Walkthrough Example

Suppose you have a social graph and want to find the names of everyone Alice knows. Your query is:

g.V().has('person','name','Alice').out('knows').values('name')

Step 1: g.V() The debugger executes the first prefix and returns all vertices in the graph. On the graph canvas, every node lights up with the accent highlight color. The results panel shows the full vertex list. This confirms that the traversal starts from the complete vertex set.

Step 2: g.V().has('person','name','Alice') Now only the Alice vertex is highlighted. All other nodes return to their default appearance. If nothing is highlighted at this step, you know the filter is wrong — perhaps the label is not person, or the property name is spelled differently. The debugger makes this immediately obvious.

Step 3: g.V().has('person','name','Alice').out('knows') The traversal follows outgoing edges labeled knows from Alice. The highlighted nodes shift to Alice’s friends — the vertices on the other end of those edges. The edges themselves glow to show the traversal path. You can inspect the results panel to see the full vertex objects and confirm they are the neighbors you expect.

Step 4: g.V().has('person','name','Alice').out('knows').values('name') The final step extracts the name property from each traverser. The results panel shows a simple list of name strings. Since this is a property extraction step rather than a vertex step, the graph highlighting remains on the vertices from the previous step so you can still see which nodes produced these values.

Debug Controls

• Step — Execute the next traversal step and update the graph highlighting.
• Run to End — Execute all remaining steps at once. Useful when you have already found the problem and want to see the final result.
• Reset — Discard all debug state and return to the beginning of the query.

Visual Highlighting

As you step through the traversal, the graph canvas provides real-time visual feedback:

• Active nodes are highlighted with a bright accent color so they stand out from the rest of the graph.
• Active edges glow to indicate the paths currently being traversed.
• The results panel updates at each step to show the intermediate data, whether that is a set of vertices, edges, property values, or aggregated results.

This combination of graph highlighting and tabular results gives you two complementary views of the traversal state at every step, making step by step Gremlin debugging intuitive and fast.

Debugging Complex Queries

The debugger is especially valuable for complex queries involving multiple filters, branching, and aggregation:

• Chained filters — Step through each .has() or .where() clause to see how many traversers survive each filter. This helps you find overly restrictive conditions.
• Joins and traversals — When your query chains multiple .out(), .in(), or .both() steps, the debugger shows you exactly which vertices are reached at each hop.
• Aggregations — Steps like .groupCount(), .group(), and .aggregate() can produce surprising results. Seeing the input set at the previous step helps you understand the output.
• Deduplication — If .dedup() removes more traversers than expected, step back one step to see the duplicates that were present before deduplication.

Limitations

The debugger executes each prefix query as a separate request to the database. This means:

• Additional request units (RUs). A query with five steps results in five separate queries to Cosmos DB. Each query consumes RUs, so debugging is more expensive than running the query once. This is generally negligible for small datasets but can add up on large production graphs.
• Best used with small datasets or the Cosmos DB Emulator. For development and learning, the Cosmos DB Emulator provides free local execution with no RU costs. This is the ideal environment for the Gremlin traversal debugger.
• Non-deterministic results. If your graph is being modified by other clients while you debug, intermediate results may not be consistent across steps because each step is a separate query execution.
• Step parsing. The debugger parses Gremlin syntax to identify step boundaries. Extremely complex queries with nested closures or anonymous traversals may not parse perfectly in all cases.

Use Cases

• Learning Gremlin — New users can watch how each step transforms the traversal, building intuition for the Gremlin query language.
• Debugging unexpected results — When a query returns wrong data, step through it to find the exact step where the output diverges from your expectation.
• Teaching and presentations — The visual highlighting makes it easy to demonstrate Gremlin concepts to colleagues or students.
• Query optimization — Identify steps that produce unexpectedly large intermediate result sets, then add earlier filters to reduce work.