Query operations

Result frames

There are a variety of ways to view data in Query. All queries that you run in the Cypher editor populate a reusable result frame. Query results are rendered as:

  • Visual graph — graph result frame.

  • Table — table result frame.

  • Meta data — RAW result frame.

  • Execution plan — plan result frame (only available for PROFILE and EXPLAIN queries).

You can switch between them in the top left corner of the result frame.

Graph result frame

The graph visualization functionality is designed to display a node-graph representation of the underlying data stored in the database in response to a given Cypher query. The visual representation of the graph is useful for determining areas of interest or assessing the current state and structure of the data. Graph view results can be downloaded as PNG.

graph result frame
Figure 1. Graph result frame

A squiggly line anywhere in your query indicates a warning. This is most commonly caused by a query attempting to match a pattern not present in the graph. Hover over the underlined segment to see the explanation.

Tips when using the Graph view:

  • Use the controls in the bottom right corner of the frame to zoom in and out of the visualization. Additionally, you can zoom using trackpad zoom gestures or a mouse wheel in combination with a modifier key. (If you are in full-screen view, the modifier key is not needed to zoom.) On Mac, use ⌘ + scroll and on Windows and Linux, use Ctrl + scroll to trigger zoom. You can also use the Fit to screen button to fit all query results into the view.

  • Expand the Cypher editor area with the expand icon next to the play button in the editor.

  • Select a node or a relationship to view its properties. The nodes already have sensible captions assigned by the Query tool, which auto-selects a property from the property list to use as a caption. To change the look of your graph, see Styling.

  • Right-click a node to expand (see its neighbors), dismiss it from the visualization, or unpin it. If you double-click a node, you automatically expand it, and if you double-click it again, you undo the expansion. If you right-click a relationship, you can dismiss it.

  • Right-click in an empty spot allows you to show all relationships between elements in the result frame or to undo your last ation with the visualization.

  • If you cannot see the whole graph or the results display too close together, you can adjust by moving the visual view and dragging nodes to rearrange them.

The graph results also reports the query time, including the actual query execution time, latency, and deserialization costs.

Table result frame

The Table result view displays the result in a table format. It also reports the query time, including the actual query execution time, latency, and deserialization costs.

table
Figure 2. Table format

RAW result frame

The RAW result view displays the submitted request, the Neo4j Server version and address, and the response. It also reports the query time, including the actual query execution time, latency, and deserialization costs.

raw
Figure 3. RAW format

Plan view

The Plan view is available for EXPLAIN and PROFILE queries and shows the execution plan for the query. For such queries, you can also toggle to view the results in a RAW format.

plan view
Figure 4. Plan view

Styling

You can customize your graph query results directly in the result frame based on node labels and relationship types.

query styling
Figure 5. Query styling

If you select a node label in the Results overview, there are several styling options available:

  • Color — set the color for nodes of the selected label.

  • Size  — set the size for nodes of the selected label.

  • Caption — set what should be displayed as the caption for nodes of the selected label.

node styling

If you select a relationship type in the Results overview, there are several styling options available:

  • Color — set the color for relationships of the selected type.

  • Line width  — set the line width for relationships of the selected type.

  • Caption — set what should be displayed as the caption for relationships of the selected type.

relationship styling

For nodes with multiple labels, you can select which label should take priority. Use the arrows to get a list of available labels in your graph and order them as you like. Nodes with multiple labels are then styled according to the first label in the list.

prioritize

Query parameters

Query supports querying based on parameters. It allows the Cypher query planner to re-use your queries instead of parse and build new execution plans.

Parameters can be used for:

Parameters cannot be used for the following constructs, as these form part of the query structure that is compiled into a query plan:

  • Property keys; MATCH (n) WHERE n.$param = 'something' is invalid.

  • Relationship types; MATCH (n)-[:$param]→(m) is invalid.

  • Node labels; MATCH (n:$param) is invalid.

Parameters may consist of letters and numbers and any combination of these but cannot start with a number or a currency symbol.

For more details on the Cypher parameters, see Cypher Manual → Parameters.

Set query parameters

You can set a parameter to be sent with your queries via the Parameters drawer ({}) or by using the :param command.

Parameter drawer

The Parameter drawer provides inputs directly from the UI for most of the property types in Neo4j.

param drawer
Figure 6. Parameter drawer

For other property types, such as Point and setting constructed types, the parameter drawer has a special evaluated option. This option allows you to express a parameter type and have it evaluated by the server as Cypher. Give the parameter a name, select evaluated as the type, enter the value, and use the play button to evaluate the parameter. This process is much like using the :param command, as described in the following section.

:param command

The :param name => 'Example' command defines a parameter named name, which will be sent along with your queries. The right hand side of ⇒ is sent to the server and evaluated as Cypher with an implicit RETURN in front. This gives better type safety since some types (especially numbers) in JavaScript are hard to match with Neo4j’s type system. To see the list of all currently set query parameters and their values, use the :params command. For more information on how to use the commands, see :help param and :help params.

Example 1. Set a parameter as an integer
:param x => 1
Example 2. Set a parameter as a float
:param x => 1.0
Example 3. Set a parameter as a string
:param x => "Example"
Example 4. Set a parameter as an object

  1. Map

    :param obj1 => ({props: {productName: "Chai", productID:1}})
    The obj1 parameter
    $obj1 = {"props": {"productName": "Chai", "productID": 1}}

    Maps like {x: 1, y: 2} must be wrapped in parentheses ({x: 1, y: 2}).

  2. List

    :param obj2 => [1, 2, 3, 4]
    The obj2 parameter
    $obj2 = [1, 2, 3, 4]
Example 5. Cypher query example with a parameter
:param name => 'Chai';
MATCH (p:Product)
WHERE p.productName = $name
RETURN p

You need to run the :param command separately from the MATCH query.

Any parameter value enclosed in single (') or double (") quotes is considered a string. If the intention is to use JSON objects as a parameter, you may use the APOC function apoc.convert.fromJsonList to achieve this. See APOC Core documentation → Procedures and functions for more information.

Clear parameters

You can clear all currently set parameters from Query by running:

:params clear

Set several parameters

You can set several parameters with the :params command, this also clears all currently set parameters.

Example 6. Set several parameters
:params {x: 1, y: 2.0, z: 'abc', d: null, e: true, f: false}
$x = 1.0
$y = 2.0
$z = "abc"
$d = null
$e = true
$f = false

Parameter assistance

If you run a query using parameters without first declaring them all, Query returns a parameter-missing error and lists the missing parameter(s). You can click the provided template to populate the editor with the command for setting parameters and all you have to do is enter the value(s) for the missing parameter(s). Since the result frame is reusable, once you have set your parameter(s), you can run the same Cypher query again without having to re-enter it.

param assist
Figure 7. Parameter assistance

Duration for the query parameters

Parameters are not automatically saved when you refresh or close Query, nor if you switch instances.

If you wish to retain your parameters across sessions, you can use the Local storage toggle in the Query Settings, as shown:

param settings
Figure 8. Save parameters across sessions

You can also save a :params command to your Saved Cypher.