Query parameters

Browser 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 1. Parameter drawer

For other property types, such as POINT and setting constructed types, the parameter sidebar 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

You can set a parameter to be sent with your queries by using the :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.

If you are using a multi-database DBMS, parameters cannot be declared when using the system database. Switch to a different database and declare, then switch back to the system database and use them.
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: {name: "Tom Hanks", born:1956}})
    The obj1 parameter
    $obj1 = {"props": {"name": "Tom Hanks", "born": 1956}}

    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 => 'Tom Hanks';
MATCH (n:Person)
WHERE n.name = $name
RETURN n

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 Neo4j Browser by running:

:params clear

Set several parameters

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

Integers are set to float with this style.
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, Browser returns a missing-parameter error and lists the missing parameter(s). You can click the provided template to populate the editor with the command for setting parameters and you just have to 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.

Additionally, in the bottom of that frame, you can use the link Learn more about :params syntax to bring up a guide in the sidebar with more information. The parameter guide is also accessible via the parameter drawer.

param assist

Duration for the query parameters

Parameters are not saved when you close the browser.

If you wish to retain your parameters in local storage to use across sessions, use the Local storage toggle in the Settings drawer.