Run and Debug
Once you have connected and entered Cypher in the Cypher editor, you can Run or Debug the Cypher statement.
Run
Click the Run button (
) to run the Cypher statement unmodified. Any results will be immediately displayed in the Graph Visualization and the Results Table.
Debug
Start Debugging
Click the Debug button (
) to enter Debug mode.
The Debug feature works by re-writing the Cypher statement piece-by-piece. In order to perform the re-write, Reveal parses the Cypher statement into an object model, and then re-renders it as a Cypher string depending on what debug step you are on. In this sense, it doesn’t work as a traditional debugger, but rather as a detailed explainer, that can show the difference in execution from one step to another.
If you were to click the Debug button for this statement:
MATCH (:Station { name: 'Denmark Hill' })<-[:CALLS_AT]-(d:Stop)
((:Stop)-[:NEXT]->(:Stop)){1,3}
(a:Stop)-[:CALLS_AT]->(:Station { name: 'Clapham Junction' })
RETURN d.departs AS departureTime, a.arrives AS arrivalTimeYou would see the following:
// Debug version - click Stop to revert
/* MATCH (_gd_1:Station {name:'Denmark Hill'})<-[_gd_2:CALLS_AT]-(d:Stop) ((_gd_3:Stop)-[_gd_4:NEXT]->(_gd_5:Stop)){1,3} (a:Stop)-[_gd_6:CALLS_AT]->(_gd_7:Station {name:'Clapham Junction'}) */
/* RETURN d.departs as departureTime, a.arrives as arrivalTime */You will see a few differences:
-
The statement is completely commented out
-
The whitespace is not exactly preserved
-
Additional variables with the prefix
_gd_have been added where no variable was specified
Even though the whitespace is not exactly preserved, the re-written query should be syntactically equivalent to the original query. The additional _gd_ variables have been added to inspect items that would not normally be returned from the query.
Stepping
In Debug mode, use the following toolbar buttons to step through the debug version of the Cypher statement:
-
Step backward a line (
): Moves back one line and executes the query. -
Step forward a line (
): Moves forward one line and executes the query. -
Step backward inside line (
): Moves backward inside of a line and executes the query. -
Step forward inside line (
): Moves forward inside of a line and executes the query.
Note: the availability to step forward or backward inside of a line depends on the Cypher keyword. Support for MATCH, OPTIONAL MATCH, and RETURN will work. WITH clauses currently cannot be sub-divided - it will advance to the next line. CALL { <subquery> } will work to some extent.
As you step forward, more of the query will become uncommented. As you step backward, the end of the Cypher statement will become commented out once more.
Constructed Cypher
Since the debugger is really a query re-writer, it has to generate valid Cypher statements. It does the following to construct valid Cypher:
-
Close off parentheses, braces, and so forth as needed
-
Honor the syntax of quantified path patterns (QPP) to the extent that it can
-
Add a
Returnclause returning in-scope variables, if aReturnclause is not already present -
Add a
Limitclause, if aLimitclause is not already present
If interested, the actual Cypher being sent for execution can be seen in the web browser’s debugging console.
Results Display
After each debug step, the results from executing that step’s Cypher statement will be shown. Shown below are the Graph Visualization and Results Table immediately after Stepping forward inside line.
You can find out more about the Results Display here.
Limit for a Step
If a Limit clause is not already present, one will be added. A Limit of 10 is specified by default, but you can make it as small as 1 or as large as 1000.
You can adjust the limit in between steps as needed. Sometimes it is useful after adjusting the limit to go backward one step, and then forward a step to see the change with the larger limit.
Syntax Errors when stepping
The query re-writing is not perfect, and syntax errors may occur. If this happens please keep stepping forward to see if the syntax re-writing will recover.
Here is an example Syntax Error you might encounter:
Stepping forward again clears the error and executes a valid Cypher statement for that step:
Stopping Cypher Execution for a Step
During each step, a Cypher statement will be constructed and executed. If the resulting Cypher statement is taking a long time and you need to stop it’s execution, you can click the Stop executing current query (
) button.
When you click the button, you will receive this message.
You can dismiss the message and then take appropriate actions to resolve the issue (e.g. stop debugging and edit syntax, make the Limit smaller)
Other Features
This section discusses a few other features offered by Reveal.
Params
Reveal provides a way to set key / value pairs for parameters in your Cypher statement. Click the Params (
) button to set parameters. Consider the following Cypher:
MATCH (:Station { name: $startStation })<-[:CALLS_AT]-(d:Stop)
((:Stop)-[:NEXT]->(:Stop)){1,3}
(a:Stop)-[:CALLS_AT]->(:Station { name: $endStation })
RETURN d.departs AS departureTime, a.arrives AS arrivalTimeWe have two parameters: $startStation and $endStation. If you run the query without setting the parameters, you will get this message:
To set parameters, click Params to bring up the Set Parameters dialog.
Parameters need to be set using JSON syntax.
{
"startStation":"Denmark Hill",
"endStation":"Clapham Junction"
}However, Reveal will attempt to convert valid Neo4j parameter syntax into JSON format for you when you paste text into the text area:
{
startStation: 'Denmark Hill',
endStation: 'Clapham Junction'
}If the conversion doesn’t generate valid JSON syntax, you will need to correct it by hand.
Click the Set Parameters button to set the parameters and close the dialog. Your parameterized query can now be run.
Validate
Imagine you have two Neo4j databases with Movie data, one with the HAS_GENRE relationship and Genre nodes, and one without. You were testing the following query in Neo4j Browser, but getting no results, and didn’t realize you were connected to the wrong database.
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)<-[:DIRECTED]-(d:Person)
WITH d, m, collect(p) as actors
MATCH (m)-[:HAS_GENRE]->(g:Genre)
WITH d, m, actors, collect(g) as genres
RETURN d, {movie: m, genres: genres, actors: actors} as movieAndActors
LIMIT 20This example is somewhat contrived, but it’s a fairly common occurrence when developing Cypher statements to create a statement that unintentionally returns no results. This can be because of a typo, using the wrong label, data isn’t loaded yet, and so forth.
Reveal provides a feature called Validate (
) that converts the statement into debug form, and executes each step one-by-one with a Limit of 1. It then shows the Cypher statement that it executed with one of the following results:
-
Pass: data is present
-
No Data: no data returned from Cypher
-
Error: an error occurred
The first No Data result will be highlighted showing you where to look to correct the issue.
You can see that _gd_3:HAS_GENRE returned no data. To correct the error you would need to either load the necessary data or change the line as follows:
MATCH (m)-[:HAS_GENRE]->(g:Genre)to:
OPTIONAL MATCH (m)-[:HAS_GENRE]->(g:Genre)Breakpoints
Experimental. In Debug mode, you can click to the right of the line numbers in the Cypher editor to add a breakpoint. Once you’ve added a breakpoint, click the Run () button to run to the breakpoint.
The line with the breakpoint will be executed, but debugging will stop at that line, and wait for you to step forward or backward to continue debugging.
Breakpoints can only be set in debug mode. If you exit Debug mode and click the Debug button again, the breakpoint is not preserved.
The user clicked the gutter to the left of line 4 to set a breakpoint.
The Run () button was clicked to run to the breakpoint.