Query parameters

Neo4j 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:

literals and expressions
node and relationship IDs

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
relationship types
labels

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 v.5 - Parameters.

Set query parameters

You can set a parameter to be sent with your queries by using the :param command. Using parameters rather than hard-coded values allows for the reuse of the query plan cache.

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

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}).

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

To run this example, in the Browser Settings drawer, check Enable multi statement query editor. Note that the results are displayed in a different way when you run multiple statements. In Neo4j Browser, the current state of multi-statement is to set up your environment with multiple statements so that you can execute queries and examine the results, one by one. Alternatively, you can run the :param command separately from the MATCH query.

Cypher result

It is possible to save the result from a Cypher query to a parameter.

The syntax is:

:param <parameter_name> => { CYPHER STATEMENT }

Example 6. One row returned

This example shows a result of one record returned.

:param result1 => { RETURN 1 AS foo }

The result1 parameter

$result1 = [{foo: 1}]

Example 7. Several rows returned

This example shows a result of three records returned.

:param result2 => { UNWIND [1, 2, 3] AS nbr RETURN nbr }

The result2 parameter

$result2 = [{"nbr": 1}, {"nbr": 2}, {"nbr": 3}]}

Example 8. One row with a node returned

:param result3 => { MATCH (n) WHERE n.name = "Example" RETURN n }

The result3 parameter

$result3 = [{"n": {"identity": 4, "labels": [], "properties": {"name": "Example"}}}]

Destructuring

It is possible to pick individual values from your result using destructuring and set a specific parameter to a specific value.

The syntax is:

:param [{<returned_parameter>: <parameter_name>, ...}, ...] => { CYPHER STATEMENT }

Example 9. One row returned

:param [{foo}] => { RETURN 1 AS foo }

$foo = 1

Example 10. Rename destructured parameter

:param [{foo: bar}] => { RETURN 1 AS foo }

$bar = 1

Example 11. Syntax

:param [{foo1: bar1, foo2: bar2}] => { RETURN 1 AS foo1, 2 AS foo2 }

$bar1 = 1
$bar2 = 2

Example 12. Several rows returned

:param [{nbr: x}] => { UNWIND [2, 3, 1] AS nbr RETURN nbr ORDER BY nbr ASCENDING }

$x = 1

:param [nbr, nbr, nbr] => { UNWIND [2, 3, 1] AS nbr RETURN nbr ORDER BY nbr ASC }

$nbr = 3

:param [{nbr: x}, nbr, nbr] => { UNWIND [2, 3, 1] AS nbr RETURN nbr ORDER BY nbr ASC }

$x = 1
$nbr = 3

:param [{nbr: x}, {nbr: y}, {nbr: z}] => { UNWIND [2, 3, 1] AS nbr RETURN nbr ORDER BY nbr ASC }

$x = 1
$y = 2
$z = 3

:param [{n: example}] => { MATCH (n) WHERE n.name = "Example" RETURN n LIMIT 1}

$example = {"identity": 4, "labels": [], "properties": {"name": "Example"}}}

Clear parameters

You can clear all currently set parameters from Neo4j Browser by running:

:params {}

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 13. 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 ParameterMissing 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.

The command offered with parameter assistance is always :params even if you only have one parameter.

Duration for the query parameters

Parameters are not saved when you close the browser. You can save a :params command as a favorite to quickly populate parameters again.