Parameters
This page describes parameterized querying.
Introduction
Cypher® supports querying with parameters. A parameterized query is a query in which placeholders are used for parameters and the parameter values are supplied at execution time. This means developers do not have to resort to string building to create a query. Additionally, parameters make caching of execution plans much easier for Cypher, thus leading to faster query execution times.
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; so
MATCH (n) WHERE n.$param = 'something'
is invalid -
relationship types; so
MATCH (n)-[:$param]→(m)
is invalid -
labels; so
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.
Setting parameters when running a query is dependent on the client environment. For example:
-
To set a parameter in Cypher Shell use
:param name => 'Joe'
. For more information refer to Operations Manual → Cypher Shell - Query Parameters. -
For Neo4j Browser use the same syntax as Cypher Shell,
:param name => 'Joe'
. -
When using drivers, the syntax is dependent on the language choice. See the examples in Transactions in the Neo4j Driver manuals.
-
For usage via the Neo4j HTTP API, see the HTTP API documentation.
We provide below a comprehensive list of examples of parameter usage. In these examples, parameters are given in JSON; the exact manner in which they are to be submitted depends upon the driver being used.
Auto-parameterization
From Neo4j 5 onwards, even when a query is partially parameterized, Cypher will try to infer parameters anyway. Each literal in the query is replaced with a parameter. This increases the re-usability of the computed plan for queries that are identical except for the literals. It is not recommended to rely on this behavior - users should rather use parameters where they think it is appropriate.
String literal
{
"name": "Johan"
}
MATCH (n:Person)
WHERE n.name = $name
RETURN n
You can use parameters in this syntax as well:
{
"name": "Johan"
}
MATCH (n:Person {name: $name})
RETURN n
Regular expression
{
"regex": ".*h.*"
}
MATCH (n:Person)
WHERE n.name =~ $regex
RETURN n.name
Case-sensitive STRING
pattern matching
{
"name": "Michael"
}
MATCH (n:Person)
WHERE n.name STARTS WITH $name
RETURN n.name
Create node with properties
{
"props": {
"name": "Andy",
"position": "Developer"
}
}
CREATE ($props)
Create multiple nodes with properties
{
"props": [ {
"awesome": true,
"name": "Andy",
"position": "Developer"
}, {
"children": 3,
"name": "Michael",
"position": "Developer"
} ]
}
UNWIND $props AS properties
CREATE (n:Person)
SET n = properties
RETURN n
Setting all properties on a node
Note that this will replace all the current properties.
{
"props": {
"name": "Andy",
"position": "Developer"
}
}
MATCH (n:Person)
WHERE n.name = 'Michaela'
SET n = $props
Node id
{
"id" : "4:1fd57deb-355d-47bb-a80a-d39ac2d2bcdb:0"
}
MATCH (n)
WHERE elementId(n) = $id
RETURN n.name