GraphAcademy

Intermediate Cypher Queries

Filtering Queries

Controlling Results Returned

Working with Cypher Data

Graph Traversal

Pipelining Queries

Reducing Memory

Using Parameters

Parameters in Cypher

Parameters

As you test your Cypher statements, you will use a variety literal values to ensure that your Cypher queries are correct. But you don’t want to change the Cypher statement every time you test. In fact, any change to a Cypher statement requires a recompilation of the Cypher code which is expensive. You create Cypher statements that will not change, except for the substitution of placeholders (parameters) in the query. A best practice is to parameterize values in your Cypher statements.

Using Cypher parameters

In your Cypher statements, a parameter name begins with the $ symbol.

Here is an example where we have parameterized the query:

cypher
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = $actorName
RETURN m.released AS releaseDate,
m.title AS title
ORDER BY m.released DESC

You will not be able to run this code yet in Neo4j Browser because you have not yet set a value for the parameter.

At runtime, if the parameter $actorName has a value, it will be used in the Cypher statement when it runs in the graph engine.

Setting a parameter

You can set values for Cypher parameters that will be in effect during your Neo4j Browser session.

You can set the value of a single parameter in the query editor pane as shown in this example where the value Tom Hanks is set for the parameter actorName:

cypher
:param actorName: 'Tom Hanks'

After you have set the parameter, you can then successfully run the Cypher code:

cypher
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = $actorName
RETURN m.released AS releaseDate,
m.title AS title
ORDER BY m.released DESC

Setting Integers

Special consideration should be made when setting integer values in a Neo4j Browser session. Due to a discrepancy between integers in JavaScript and the Neo4j type system, any integers are converted to floating point values when the parameter is set. This is designed to avoid any data loss on large numbers.

For example, if you run the following code to set the number parameter using colon (:) operator, the number will be converted from 10 to 10.0.

cypher
Numbers and Colons
:param number: 10

The Browser will output the following result, with number cast as a float.

json
Browser Output
{
  "number": 10.0
}

Instead, to force the number to be an integer, you can use the ⇒ operator.

cypher
Correctly setting Integers
:param number=> 10

The Browser will output the following result, with the number cast as an integer.

json
Browser Output
{
  "number": 10
}

You can learn more about the difference between JavaScript integers and Neo4j Integers in the Building Neo4j Applications with Node.js course.

Setting multiple parameters

You can also use the JSON-style syntax to set all of the parameters in your Neo4j Browser session. The values you can specify in this object are numbers, strings, and booleans. In this example we set two parameters for our session:

cypher
:params {actorName: 'Tom Cruise', movieName: 'Top Gun'}

If you have set multiple parameters, you can use the ⇒ operator as seen before to add more parameters to a set of parameters.

cypher
:param number=> 10

Using multiple parameters

Here is a different query that uses both parameters:

cypher
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = $actorName
AND m.title = $movieName
RETURN p, m

Viewing parameters

If you want to view the current parameters and their values, simply type:

cypher
:params

Removing parameters

If you want to remove an existing parameter from your session, you do so by using the JSON-style syntax and exclude the parameter for your session.

If you want to clear all parameters, you can simply type:

cypher
:params {}

Check your understanding

1. What parameters to use?

Suppose we have set the following parameters:

cypher
:params {actorName: 'Tom Cruise', movieName: 'Top Gun', l:2}

Here is a query to return the names of the actors in a particular movie that is parameterized. The number of results returned is also parameterized. How would you complete this query in a Neo4j Browser session?

Once you have selected your option, click the Check Results query button to continue.

cypher
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
/*select:WHERE m.title = $movieName
RETURN p.name LIMIT $l*/

  • ❏ WHERE m.title = #movieName RETURN p.name LIMIT #l

  • ❏ WHERE m.title = movieName RETURN p.name LIMIT l

  • ❏ WHERE m.title = @movieName RETURN p.name LIMIT @l

  • ✓ WHERE m.title = $movieName RETURN p.name LIMIT $l

Hint

What is the special character to indicate a parameter in a Cypher statement?

Solution

The correct answer is: WHERE m.title = $movieName RETURN p.name LIMIT $l. You use the "$" to indicate that it will be substituted with parameter values when the query executes.

None of the other choices use "$" to indicate parameters.

2. Parameters for the session?

What command in Neo4j Browser returns all parameters set for the session?

  • ❏ :parameters

  • ❏ :show parameters

  • ✓ :params

  • ❏ :show params

Hint

It is a very short one-word command.

Solution

The correct answer is: :params.

3. Setting Integers

Which command would you use to ensure that the value of the myNumber parameter is cast as an integer?

  • ❏ :param myNumber: 10 AS integer

  • ✓ :param myNumber ⇒ 10

  • ❏ :param myNumber: integer ⇒ 10

  • ❏ :param myNumber ⇒ integer(10)

Hint

The Cypher type is implied using this operator when the right-hand-side value is an integer.

Solution

The correct answer is: :param myNumber ⇒ 10. When using the ⇒ operator, the type is implied by the value specified.

You do not use AS to cast a value to an integer.

Summary

In this lesson, you learned how to set parameter values in your Neo4j Browser session and to use parameters in queries. In the next challenge, you will practice setting parameters.