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:
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = $actorName
RETURN m.released AS releaseDate,
m.title AS title
ORDER BY m.released DESCYou 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:
:param actorName: 'Tom Hanks'After you have set the parameter, you can then successfully run the Cypher code:
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = $actorName
RETURN m.released AS releaseDate,
m.title AS title
ORDER BY m.released DESCSetting 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.
:param number: 10The Browser will output the following result, with number cast as a float.
{
"number": 10.0
}Instead, to force the number to be an integer, you can use the ⇒ operator.
:param number=> 10The Browser will output the following result, with the number cast as an integer.
{
"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:
: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.
:param number=> 10Using multiple parameters
Here is a different query that uses both parameters:
MATCH (p:Person)-[:ACTED_IN]->(m:Movie)
WHERE p.name = $actorName
AND m.title = $movieName
RETURN p, mViewing parameters
If you want to view the current parameters and their values, simply type:
:paramsRemoving 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:
:params {}Check your understanding
1. What parameters to use?
Suppose we have set the following parameters:
: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.
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.