NodeEra Cypher Editor And Data Grid

NodeEra Cypher Editor Overview

The NodeEra Cypher Editor provides a professional text editor for creating and running Cypher queries.  This is a tabbed interface so you can have many cypher queries open at the same time.

The diagram above illustrates a Cypher query that was generated by NodeEra in an editor tab with the label “Unsaved-02”.

Edit A Cypher Query

Common Editor Functions (see Figure 1) – These commands apply to the currently selected editor tab.

• New Cypher Query – opens a new empty cypher editor tab
• Open Cypher File – allows the user to select a file on disk to open in a cypher editor tab
• Save Cypher File – saves the currently selected cypher editor file.
• Save Cypher File As … – saves the currently selected cypher editor file to the location and file name selected by the user.
• Close Cypher File – closes the currently selected cypher editor tab
• Increase/Decrease Font Size – increases or decreases the font size for the currently selected cypher editor tab.
• Comment Line – adds a double forward-slash “//” to the line where the cursor is to indicate a comment line.
• Uncomment Line – removes the double forward-slash “//” from the line where the cursor is.
• Undo / Redo – this will undo or redo the last editing operation for the currently selected cypher editor tab.

Run a Cypher Query

Cypher execution functions (see Figure 1) – These functions apply to the cypher query on each specific tab.  Each tab runs queries in its own transaction.

• Run Query At Cursor – This will execute the cypher statement that the cursor is pointing at. The text file can contain multiple cypher statements, each of which is terminated by a semicolon “;”.  Place the cursor anywhere inside the query you want to run and then click this button.
• Run File As Script – This will execute each query in the file one at a time. If any query generates an error, the error will be displayed and after the user confirms the error, the next query will run.
• Auto Commit drop-down – Select “Auto Commit On” to have NodeEra perform a commit after each execution. Select “Auto Commit Off” to manually control commits or rollbacks.  If auto commit is off, other cypher tabs won’t see any database updates until you click on the commit button.
• Commit Current Transaction – this is only valid if auto commit is off. Sends a commit request to the Neo4j server.
• Rollback Current Transaction – this is only valid if auto commit is off. Sends a rollback request to the Neo4j server.

Any error messages returned from the Neo4j server will be displayed in a popup window.  If a syntax error occurs, the error indicates the row and column of the error and the cursor will be placed in this location on the Cypher edit tab.  The error message is recorded in the “Log” tab for later review (see section below on the Data Grid Log Tab.

Parameterized Cypher Queries

It is considered a best practice to use parameterized Cypher queries whenever possible.  This can improve performance for frequently run queries as the server will cache to execution plan for the query. NodeEra supports parameterized queries by giving the user a dialog box to enter parameter values when it detects a parameter in a query.

In the example shown above, there is a parameter called $string-Name.

When this query is executed NodeEra will display a dialog box that allows the user to enter the parameter value (see below).

There is no limit to the number of parameters a cypher query may have.

NodeEra provides context sensitive data entry widgets based on the datatype.

If you include the datatype in the parameter name then that datatype will be selected for you automatically.  Otherwise, you can click in the datatype cell and use a dropdown to select the appropriate datatype.  The example above has a parameter name of “stringName” so the UI automatically selected String as the datatype.

If you don’t include a datatype in the parameter name, then NodeEra will default to “String” but you can change it if you want.

Once you have completed the parameter values:

• Click on the “Run Query” button to execute the query
• Click on the “Cancel Query” button to cancel execution

Cancel A Long Running Query

Once a query starts running a dialog box will appear that ticks of the time spent running the query.

You can click on the “Cancel Query” button to cancel the query at any time.

NodeEra Data Grid Overview

The NodeEra Data Grid provides a familiar spreadsheet user interface that allows you to interact with the results from running a cypher query.

The following example screen shots were obtained after running the following Cypher query.

Data Grid – Data Tab

The result set from the query (see above) produced the following output in the Data Grid.

The data grid displays the Cypher query results in a spreadsheet style metaphor using rows and columns.

Each column represents one item in the Cypher query “Return” clause.

You can use the “as” clause in your Cypher query to create more meaningful column names as can be seen in the example above.

Neo4j returns a wide variety of datatypes in the Cypher “Return” clause some of which are illustrated above.

See the Tutorial on datatypes for a complete discussion of how NodeEra handles Neo4j datatypes.

NodeID – this is the user friendly column name for the node id. In the Cypher query it is coded as “id(n) as NodeID”  The result is an integer.

Person – In the Cypher query this is coded as n:Person as Person.  This returns the node label “Person” which is shown as “True” if the label is in the node or “False” if the label is missing.

Name – In the Cypher query this is coded as n.name as Name.  This returns the value of the “name” property.  If the node being returned does not have the property “name” then the grid will display “Null”.  Remember that Neo4j itself does not store null values for properties – the absence of the property in the node indicates the property is null.

Node – In the Cypher query this is coded as “n as Node”.  The result set contains an object that represents the entire node referenced by “n”.  NodeEra displays a text representation of the node object that shows all the labels and properties in the node.

Note that similar data type functionality applies to relationships in a Cypher query.

Reading All The Data In The Cypher Result Set

The data grid displays only the first 2000 rows of the result set from the query.  NodeEra makes it possible to run queries that produce very large result sets, view a subset of the data, and export the entire result set if you desire.  Of course, the query must complete on the Neo4j server which might take some time if you are retrieving millions of nodes or relationships, but once the query completes NodeEra will manage fetching the results in smaller chunks so the end user experience is useful.

The navigation buttons on the Data tab allow you to step through a large result set in chunks.  You can move forward/backward one chunk at a time, or you can move to the very end or the very beginning of the entire result set using the “Move To Last Row” or “Move To First Row” buttons.

Exporting Data In The Data Grid

A common use case for data analysts is to query data from the Neo4j server and export that data to a spreadsheet for further processing.

The Export button will display a dialog box that allows the user to export the reset set from the Cypher Query to a CSV file which can then be opened by spreadsheet software or imported into another application.

The Export Dialog Box (shown above) will export the data retrieved by the Cypher query and write it to a CSV (comma separated variable) file.

Complete the fields on the dialog box to define the export file format:

• File Name: – click the “Select File Name…” button to select the file path and file name.
• Output Header Column Names – check the checkbox if you want the first row in the CSV file to contain the column headers which will be the same as you see in the data grid.
• Delimiter: – select the character used to separate each field in the output file.
• Quote Character: select which character to use to quote strings.
• Use Quotes: select the quoting strategy.
• Escape Character: select the character used to escape the “Quote Character” when it appears in data.
• Line Terminator: select the characters used to denote the end of a line in the output file.

Click the “Export” button to perform the export.

The Data Grid Log Tab

Each time you run a query the results of the query execution are stored as a row in the “Log” tab.

The “Log” tab is useful for reviewing results of Cypher query executions as you develop and refine queries.

• The “Duration” column gives you an idea of how long the query took to execute.
• The “Cypher” column records the exact Cypher statement executed so you can track changes or revert back to a previous version.
• The “Plan” column will contain the results of a Profile or Plan clause in your Cypher query. This allows you to track improvements in query performance as you tune a query.
• The “Error” column tracks error messages from Cypher executions (typically syntax errors).
• The “Export” button will export the contents of the grid to a CSV file for later analysis (useful when tuning queries).
• The “Clear Log” button will clear all rows from the Log tab.