Parameters

This section describes parameterized quering.

1. 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

  • labels

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:

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.

The old parameter syntax {param} was deprecated in Neo4j 3.0 and removed entirely in Neo4j 4.0. Using it will result in a syntax error. However, it is still possible to use it, with warnings, if you prefix the query with CYPHER 3.5. See Cypher Compatibility for further information.

2. Auto-parameterization

When a query does not use parameters, 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.

If at least one parameter is used in the query, auto-parameterization is turned off for that query. This means that any remaining literals will not be turned into parameters.

3. String literal

Parameters
{
  "name" : "Johan"
}
Query
MATCH (n:Person)
WHERE n.name = $name
RETURN n

You can use parameters in this syntax as well:

Parameters
{
  "name" : "Johan"
}
Query
MATCH (n:Person {name: $name})
RETURN n

4. Regular expression

Parameters
{
  "regex" : ".*h.*"
}
Query
MATCH (n:Person)
WHERE n.name =~ $regex
RETURN n.name

5. Case-sensitive string pattern matching

Parameters
{
  "name" : "Michael"
}
Query
MATCH (n:Person)
WHERE n.name STARTS WITH $name
RETURN n.name

6. Create node with properties

Parameters
{
  "props" : {
    "name" : "Andy",
    "position" : "Developer"
  }
}
Query
CREATE ($props)

7. Create multiple nodes with properties

Parameters
{
  "props" : [ {
    "awesome" : true,
    "name" : "Andy",
    "position" : "Developer"
  }, {
    "children" : 3,
    "name" : "Michael",
    "position" : "Developer"
  } ]
}
Query
UNWIND $props AS properties
CREATE (n:Person)
SET n = properties
RETURN n

8. Setting all properties on a node

Note that this will replace all the current properties.

Parameters
{
  "props" : {
    "name" : "Andy",
    "position" : "Developer"
  }
}
Query
MATCH (n:Person)
WHERE n.name = 'Michaela'
SET n = $props

9. SKIP and LIMIT

Parameters
{
  "s" : 1,
  "l" : 1
}
Query
MATCH (n:Person)
RETURN n.name
SKIP $s
LIMIT $l

10. Node id

Parameters
{
  "id" : 0
}
Query
MATCH (n)
WHERE id(n) = $id
RETURN n.name

11. Multiple node ids

Parameters
{
  "ids" : [ 0, 1, 2 ]
}
Query
MATCH (n)
WHERE id(n) IN $ids
RETURN n.name

12. Calling procedures

Parameters
{
  "indexname" : "My index"
}
Query
CALL db.resampleIndex($indexname)