3.2.4. Parameters

3.2.4.1. Introduction

Cypher supports querying with parameters. This means developers don’t 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
  • for explicit indexes only: index values and queries

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.

For details on using parameters via the Neo4j REST API, see Section 5.1, “Transactional Cypher HTTP endpoint”.

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.

It is recommended that the new parameter syntax $param is used, as the old syntax {param} is deprecated and will be removed altogether in a later release.

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

3.2.4.3. Regular expression

Parameters. 

{
  "regex" : ".*h.*"
}

Query. 

MATCH (n:Person)
WHERE n.name =~ $regex
RETURN n.name

3.2.4.4. Case-sensitive string pattern matching

Parameters. 

{
  "name" : "Michael"
}

Query. 

MATCH (n:Person)
WHERE n.name STARTS WITH $name
RETURN n.name

3.2.4.5. Create node with properties

Parameters. 

{
  "props" : {
    "name" : "Andres",
    "position" : "Developer"
  }
}

Query. 

CREATE ($props)

3.2.4.6. Create multiple nodes with properties

Parameters. 

{
  "props" : [ {
    "awesome" : true,
    "name" : "Andres",
    "position" : "Developer"
  }, {
    "children" : 3,
    "name" : "Michael",
    "position" : "Developer"
  } ]
}

Query. 

UNWIND $props AS properties
CREATE (n:Person)
SET n = properties
RETURN n

3.2.4.7. Setting all properties on a node

Note that this will replace all the current properties.

Parameters. 

{
  "props" : {
    "name" : "Andres",
    "position" : "Developer"
  }
}

Query. 

MATCH (n:Person)
WHERE n.name='Michaela'
SET n = $props

3.2.4.8. SKIP and LIMIT

Parameters. 

{
  "s" : 1,
  "l" : 1
}

Query. 

MATCH (n:Person)
RETURN n.name
SKIP $s
LIMIT $l

3.2.4.9. Node id

Parameters. 

{
  "id" : 0
}

Query. 

MATCH (n)
WHERE id(n)= $id
RETURN n.name

3.2.4.10. Multiple node ids

Parameters. 

{
  "ids" : [ 0, 1, 2 ]
}

Query. 

MATCH (n)
WHERE id(n) IN $ids
RETURN n.name

3.2.4.11. Calling procedures

Parameters. 

{
  "indexname" : ":Person(name)"
}

Query. 

CALL db.resampleIndex($indexname)

3.2.4.12. Index value (explicit indexes)

Parameters. 

{
  "value" : "Michaela"
}

Query. 

START n=node:people(name = $value)
RETURN n

3.2.4.13. Index query (explicit indexes)

Parameters. 

{
  "query" : "name:Andreas"
}

Query. 

START n=node:people($query)
RETURN n