Neo4j Cypher Refcard 3.0

Cypher is the declarative query language for Neo4j, the world’s leading graph database.

Key principles and capabilities of Cypher are as follows:

Cypher matches patterns of nodes and relationships in the graph, to extract information or modify the data.
Cypher has the concept of variables which denote named, bound elements and parameters.
Cypher can create, update, and remove nodes, relationships, labels, and properties.
Cypher manages indexes and constraints.

You can try Cypher snippets live in the Neo4j Console at console.neo4j.org or read the full Cypher documentation in the Neo4j Developer Manual. For live graph models using Cypher check out GraphGist.

The Cypher Refcard is also available in PDF format.

Note: {value} denotes either literals or maps, used for ad hoc Cypher queries. The usage of parameters is recommended in applications, and are denoted by $value. Neo4j properties can be strings, numbers, booleans or arrays thereof. Cypher also supports maps and lists.

Syntax

Read Query Structure
[MATCH WHERE] [OPTIONAL MATCH WHERE] [WITH [ORDER BY] [SKIP] [LIMIT]] RETURN [ORDER BY] [SKIP] [LIMIT]

Read Query Structure

[MATCH WHERE]
[OPTIONAL MATCH WHERE]
[WITH [ORDER BY] [SKIP] [LIMIT]]
RETURN [ORDER BY] [SKIP] [LIMIT]

MATCH
MATCH (n:Person)-[:KNOWS]->(m:Person) WHERE n.name = 'Alice' Node patterns can contain labels and properties.
MATCH (n)-->(m) Any pattern can be used in `MATCH`.
MATCH (n {name: 'Alice'})-->(m) Patterns with node properties.
MATCH p = (n)-->(m) Assign a path to `p`.
OPTIONAL MATCH (n)-[r]->(m) Optional pattern: `null`s will be used for missing parts.

MATCH

MATCH (n:Person)-[:KNOWS]->(m:Person)
WHERE n.name = 'Alice'

Node patterns can contain labels and properties.

MATCH (n)-->(m)

Any pattern can be used in MATCH.

MATCH (n {name: 'Alice'})-->(m)

Patterns with node properties.

MATCH p = (n)-->(m)

Assign a path to p.

OPTIONAL MATCH (n)-[r]->(m)

Optional pattern: nulls will be used for missing parts.

WHERE
WHERE n.property <> {value} Use a predicate to filter. Note that `WHERE` is always part of a `MATCH`, `OPTIONAL MATCH`, `WITH` or `START` clause. Putting it after a different clause in a query will alter what it does.

WHERE

WHERE n.property <> {value}

Use a predicate to filter. Note that WHERE is always part of a MATCH, OPTIONAL MATCH, WITH or START clause. Putting it after a different clause in a query will alter what it does.

RETURN
RETURN * Return the value of all variables.
RETURN n AS columnName Use alias for result column name.
RETURN DISTINCT n Return unique rows.
ORDER BY n.property Sort the result.
ORDER BY n.property DESC Sort the result in descending order.
SKIP {skipNumber} Skip a number of results.
LIMIT {limitNumber} Limit the number of results.
SKIP {skipNumber} LIMIT {limitNumber} Skip results at the top and limit the number of results.
RETURN count(*) The number of matching rows. See Aggregating Functions for more.

RETURN

RETURN *

Return the value of all variables.

RETURN n AS columnName

Use alias for result column name.

RETURN DISTINCT n

Return unique rows.

ORDER BY n.property

Sort the result.

ORDER BY n.property DESC

Sort the result in descending order.

SKIP {skipNumber}

Skip a number of results.

LIMIT {limitNumber}

Limit the number of results.

SKIP {skipNumber} LIMIT {limitNumber}

Skip results at the top and limit the number of results.

RETURN count(*)

The number of matching rows. See Aggregating Functions for more.

WITH
MATCH (user)-[:FRIEND]-(friend) WHERE user.name = {name} WITH user, count(friend) AS friends WHERE friends > 10 RETURN user The `WITH` syntax is similar to `RETURN`. It separates query parts explicitly, allowing you to declare which variables to carry over to the next part.
MATCH (user)-[:FRIEND]-(friend) WITH user, count(friend) AS friends ORDER BY friends DESC SKIP 1 LIMIT 3 RETURN user `ORDER BY`, `SKIP`, and `LIMIT` can also be used with `WITH`.

WITH

MATCH (user)-[:FRIEND]-(friend)
WHERE user.name = {name}
WITH user, count(friend) AS friends
WHERE friends > 10
RETURN user

The WITH syntax is similar to RETURN. It separates query parts explicitly, allowing you to declare which variables to carry over to the next part.

MATCH (user)-[:FRIEND]-(friend)
WITH user, count(friend) AS friends
ORDER BY friends DESC
  SKIP 1
  LIMIT 3
RETURN user

ORDER BY, SKIP, and LIMIT can also be used with WITH.

UNION
MATCH (a)-[:KNOWS]->(b) RETURN b.name UNION MATCH (a)-[:LOVES]->(b) RETURN b.name Returns the distinct union of all query results. Result column types and names have to match.
MATCH (a)-[:KNOWS]->(b) RETURN b.name UNION ALL MATCH (a)-[:LOVES]->(b) RETURN b.name Returns the union of all query results, including duplicated rows.

UNION

MATCH (a)-[:KNOWS]->(b)
RETURN b.name
UNION
MATCH (a)-[:LOVES]->(b)
RETURN b.name

Returns the distinct union of all query results. Result column types and names have to match.

MATCH (a)-[:KNOWS]->(b)
RETURN b.name
UNION ALL
MATCH (a)-[:LOVES]->(b)
RETURN b.name

Returns the union of all query results, including duplicated rows.

Write-Only Query Structure
(CREATE [UNIQUE] \| MERGE)* [SET\|DELETE\|REMOVE\|FOREACH]* [RETURN [ORDER BY] [SKIP] [LIMIT]]

Write-Only Query Structure

(CREATE [UNIQUE] | MERGE)*
[SET|DELETE|REMOVE|FOREACH]*
[RETURN [ORDER BY] [SKIP] [LIMIT]]

Read-Write Query Structure
[MATCH WHERE] [OPTIONAL MATCH WHERE] [WITH [ORDER BY] [SKIP] [LIMIT]] (CREATE [UNIQUE] \| MERGE)* [SET\|DELETE\|REMOVE\|FOREACH]* [RETURN [ORDER BY] [SKIP] [LIMIT]]

Read-Write Query Structure

[MATCH WHERE]
[OPTIONAL MATCH WHERE]
[WITH [ORDER BY] [SKIP] [LIMIT]]
(CREATE [UNIQUE] | MERGE)*
[SET|DELETE|REMOVE|FOREACH]*
[RETURN [ORDER BY] [SKIP] [LIMIT]]

CREATE
CREATE (n {name: {value}}) Create a node with the given properties.
CREATE (n {map}) Create a node with the given properties.
UNWIND {listOfMaps} AS properties CREATE (n) SET n = properties Create nodes with the given properties.
CREATE (n)-[r:KNOWS]->(m) Create a relationship with the given type and direction; bind a variable to it.
CREATE (n)-[:LOVES {since: {value}}]->(m) Create a relationship with the given type, direction, and properties.

CREATE

CREATE (n {name: {value}})

Create a node with the given properties.

CREATE (n {map})

Create a node with the given properties.

UNWIND {listOfMaps} AS properties
CREATE (n) SET n = properties

Create nodes with the given properties.

CREATE (n)-[r:KNOWS]->(m)

Create a relationship with the given type and direction; bind a variable to it.

CREATE (n)-[:LOVES {since: {value}}]->(m)

Create a relationship with the given type, direction, and properties.

MERGE
MERGE (n:Person {name: {value}}) ON CREATE SET n.created = timestamp() ON MATCH SET n.counter = coalesce(n.counter, 0) + 1, n.accessTime = timestamp() Match a pattern or create it if it does not exist. Use `ON CREATE` and `ON MATCH` for conditional updates.
MATCH (a:Person {name: {value1}}), (b:Person {name: {value2}}) MERGE (a)-[r:LOVES]->(b) `MERGE` finds or creates a relationship between the nodes.
MATCH (a:Person {name: {value1}}) MERGE (a)-[r:KNOWS]->(b:Person {name: {value3}}) `MERGE` finds or creates subgraphs attached to the node.

MERGE

MERGE (n:Person {name: {value}})
  ON CREATE SET n.created = timestamp()
  ON MATCH SET
    n.counter = coalesce(n.counter, 0) + 1,
    n.accessTime = timestamp()

Match a pattern or create it if it does not exist. Use ON CREATE and ON MATCH for conditional updates.

MATCH (a:Person {name: {value1}}),
      (b:Person {name: {value2}})
MERGE (a)-[r:LOVES]->(b)

MERGE finds or creates a relationship between the nodes.

MATCH (a:Person {name: {value1}})
MERGE
  (a)-[r:KNOWS]->(b:Person {name: {value3}})

MERGE finds or creates subgraphs attached to the node.

SET
SET n.property1 = {value1}, n.property2 = {value2} Update or create a property.
SET n = {map} Set all properties. This will remove any existing properties.
SET n += {map} Add and update properties, while keeping existing ones.
SET n:Person Adds a label `Person` to a node.

SET

SET n.property1 = {value1},
    n.property2 = {value2}

Update or create a property.

SET n = {map}

Set all properties. This will remove any existing properties.

SET n += {map}

Add and update properties, while keeping existing ones.

SET n:Person

Adds a label Person to a node.

DELETE
DELETE n, r Delete a node and a relationship.
DETACH DELETE n Delete a node and all relationships connected to it.
MATCH (n) DETACH DELETE n Delete all nodes and relationships from the database.

DELETE

DELETE n, r

Delete a node and a relationship.

DETACH DELETE n

Delete a node and all relationships connected to it.

MATCH (n)
DETACH DELETE n

Delete all nodes and relationships from the database.

REMOVE
REMOVE n:Person Remove a label from `n`.
REMOVE n.property Remove a property.

REMOVE

REMOVE n:Person

Remove a label from n.

REMOVE n.property

Remove a property.

FOREACH
FOREACH (r IN relationships(path) \| SET r.marked = true) Execute a mutating operation for each relationship in a path.
FOREACH (value IN coll \| CREATE (:Person {name: value})) Execute a mutating operation for each element in a list.

FOREACH

FOREACH (r IN relationships(path) |
  SET r.marked = true)

Execute a mutating operation for each relationship in a path.

FOREACH (value IN coll |
 CREATE (:Person {name: value}))

Execute a mutating operation for each element in a list.

CALL
CALL db.labels() YIELD label This shows a standalone call to the built-in procedure `db.labels` to list all labels used in the database. Note that required procedure arguments are given explicitly in brackets after the procedure name.
CALL java.stored.procedureWithArgs Standalone calls may omit `YIELD` and also provide arguments implicitly via statement parameters, e.g. a standalone call requiring one argument `input` may be run by passing the parameter map `{input: 'foo'}`.
CALL db.labels() YIELD label RETURN count(label) AS count Calls the built-in procedure `db.labels` inside a larger query to count all labels used in the database. Calls inside a larger query always requires passing arguments and naming results explicitly with `YIELD`.

CALL

CALL db.labels() YIELD label

This shows a standalone call to the built-in procedure db.labels to list all labels used in the database. Note that required procedure arguments are given explicitly in brackets after the procedure name.

CALL java.stored.procedureWithArgs

Standalone calls may omit YIELD and also provide arguments implicitly via statement parameters, e.g. a standalone call requiring one argument input may be run by passing the parameter map {input: 'foo'}.

CALL db.labels() YIELD label
RETURN count(label) AS count

Calls the built-in procedure db.labels inside a larger query to count all labels used in the database. Calls inside a larger query always requires passing arguments and naming results explicitly with YIELD.

INDEX
CREATE INDEX ON :Person(name) Create an index on the label `Person` and property `name`.
MATCH (n:Person) WHERE n.name = {value} An index can automatically be used for the equality comparison. Note that for example `toLower(n.name) = {value}` will not use an index.
MATCH (n:Person) WHERE n.name IN [{value}] An index can automatically be used for the `IN` list checks.
MATCH (n:Person) USING INDEX n:Person(name) WHERE n.name = {value} Index usage can be enforced when Cypher uses a suboptimal index, or more than one index should be used.
DROP INDEX ON :Person(name) Drop the index on the label `Person` and property `name`.

INDEX

CREATE INDEX ON :Person(name)

Create an index on the label Person and property name.

MATCH (n:Person) WHERE n.name = {value}

An index can automatically be used for the equality comparison. Note that for example toLower(n.name) = {value} will not use an index.

MATCH (n:Person)
WHERE n.name IN [{value}]

An index can automatically be used for the IN list checks.

MATCH (n:Person)
USING INDEX n:Person(name)
WHERE n.name = {value}

Index usage can be enforced when Cypher uses a suboptimal index, or more than one index should be used.

DROP INDEX ON :Person(name)

Drop the index on the label Person and property name.

CONSTRAINT
CREATE CONSTRAINT ON (p:Person) ASSERT p.name IS UNIQUE Create a unique property constraint on the label `Person` and property `name`. If any other node with that label is updated or created with a `name` that already exists, the write operation will fail. This constraint will create an accompanying index.
DROP CONSTRAINT ON (p:Person) ASSERT p.name IS UNIQUE Drop the unique constraint and index on the label `Person` and property `name`.
CREATE CONSTRAINT ON (p:Person) ASSERT exists(p.name) Create a node property existence constraint on the label `Person` and property `name`. If a node with that label is created without a `name`, or if the `name` property is removed from an existing node with the `Person` label, the write operation will fail.
DROP CONSTRAINT ON (p:Person) ASSERT exists(p.name) Drop the node property existence constraint on the label `Person` and property `name`.
CREATE CONSTRAINT ON ()-[l:LIKED]-() ASSERT exists(l.when) Create a relationship property existence constraint on the type `LIKED` and property `when`. If a relationship with that type is created without a `when`, or if the `when` property is removed from an existing relationship with the `LIKED` type, the write operation will fail.
DROP CONSTRAINT ON ()-[l:LIKED]-() ASSERT exists(l.when) Drop the relationship property existence constraint on the type `LIKED` and property `when`.

CONSTRAINT

CREATE CONSTRAINT ON (p:Person)
       ASSERT p.name IS UNIQUE

Create a unique property constraint on the label Person and property name. If any other node with that label is updated or created with a name that already exists, the write operation will fail. This constraint will create an accompanying index.

DROP CONSTRAINT ON (p:Person)
     ASSERT p.name IS UNIQUE

Drop the unique constraint and index on the label Person and property name.

CREATE CONSTRAINT ON (p:Person)
       ASSERT exists(p.name)

Create a node property existence constraint on the label Person and property name. If a node with that label is created without a name, or if the name property is removed from an existing node with the Person label, the write operation will fail.

DROP CONSTRAINT ON (p:Person)
     ASSERT exists(p.name)

Drop the node property existence constraint on the label Person and property name.

CREATE CONSTRAINT ON ()-[l:LIKED]-()
       ASSERT exists(l.when)

Create a relationship property existence constraint on the type LIKED and property when. If a relationship with that type is created without a when, or if the when property is removed from an existing relationship with the LIKED type, the write operation will fail.

DROP CONSTRAINT ON ()-[l:LIKED]-()
     ASSERT exists(l.when)

Drop the relationship property existence constraint on the type LIKED and property when.

Import
LOAD CSV FROM 'https://neo4j.com/docs/cypher-refcard/3.0/csv/artists.csv' AS line CREATE (:Artist {name: line[1], year: toInt(line[2])}) Load data from a CSV file and create nodes.
LOAD CSV WITH HEADERS FROM 'https://neo4j.com/docs/cypher-refcard/3.0/csv/artists-with-headers.csv' AS line CREATE (:Artist {name: line.Name, year: toInt(line.Year)}) Load CSV data which has headers.
LOAD CSV FROM 'https://neo4j.com/docs/cypher-refcard/3.0/csv/artists-fieldterminator.csv' AS line FIELDTERMINATOR ';' CREATE (:Artist {name: line[1], year: toInt(line[2])}) Use a different field terminator, not the default which is a comma (with no whitespace around it).

Import

LOAD CSV FROM
'https://neo4j.com/docs/cypher-refcard/3.0/csv/artists.csv' AS line
CREATE (:Artist {name: line[1], year: toInt(line[2])})

Load data from a CSV file and create nodes.

LOAD CSV WITH HEADERS FROM
'https://neo4j.com/docs/cypher-refcard/3.0/csv/artists-with-headers.csv' AS line
CREATE (:Artist {name: line.Name, year: toInt(line.Year)})

Load CSV data which has headers.

LOAD CSV FROM
'https://neo4j.com/docs/cypher-refcard/3.0/csv/artists-fieldterminator.csv'
AS line FIELDTERMINATOR ';'
CREATE (:Artist {name: line[1], year: toInt(line[2])})

Use a different field terminator, not the default which is a comma (with no whitespace around it).

Operators
General	`DISTINCT`, `.`, `[]`
Mathematical	`+`, `-`, `*`, `/`, `%`, `^`
Comparison	`=`, `<>`, `<`, `>`, `<=`, `>=`, `IS NULL`, `IS NOT NULL`
Boolean	`AND`, `OR`, `XOR`, `NOT`
String	`+`
List	`+`, `IN`, `[x]`, `[x .. y]`
Regular Expression	`=~`
String matching	`STARTS WITH`, `ENDS WITH`, `CONTAINS`

Operators

General

DISTINCT, ., []

Mathematical

+, -, *, /, %, ^

Comparison

=, <>, <, >, <=, >=, IS NULL, IS NOT NULL

Boolean

AND, OR, XOR, NOT

String

+

List

+, IN, [x], [x .. y]

Regular Expression

=~

String matching

STARTS WITH, ENDS WITH, CONTAINS

null
`null` is used to represent missing/undefined values. `null` is not equal to `null`. Not knowing two values does not imply that they are the same value. So the expression `null = null` yields `null` and not `true`. To check if an expression is `null`, use `IS NULL`. Arithmetic expressions, comparisons and function calls (except `coalesce`) will return `null` if any argument is `null`. An attempt to access a missing element in a list or a property that doesn’t exist yields `null`. In `OPTIONAL MATCH` clauses, `null`s will be used for missing parts of the pattern.

null

null is used to represent missing/undefined values.
null is not equal to null. Not knowing two values does not imply that they are the same value. So the expression null = null yields null and not true. To check if an expression is null, use IS NULL.
Arithmetic expressions, comparisons and function calls (except coalesce) will return null if any argument is null.
An attempt to access a missing element in a list or a property that doesn’t exist yields null.
In OPTIONAL MATCH clauses, nulls will be used for missing parts of the pattern.

Patterns
(n:Person) Node with `Person` label.
(n:Person:Swedish) Node with both `Person` and `Swedish` labels.
(n:Person {name: {value}}) Node with the declared properties.
(n)-->(m) Relationship from `n` to `m`.
(n)--(m) Relationship in any direction between `n` and `m`.
(n:Person)-->(m) Node `n` labeled `Person` with relationship to `m`.
(m)<-[:KNOWS]-(n) Relationship of type `KNOWS` from `n` to `m`.
(n)-[:KNOWS\|:LOVES]->(m) Relationship of type `KNOWS` or of type `LOVES` from `n` to `m`.
(n)-[r]->(m) Bind the relationship to variable `r`.
(n)-[*1..5]->(m) Variable length path of between 1 and 5 relationships from `n` to `m`.
(n)-[*]->(m) Variable length path of any number of relationships from `n` to `m`. (See Performance section.)
(n)-[:KNOWS]->(m {property: {value}}) A relationship of type `KNOWS` from a node `n` to a node `m` with the declared property.
shortestPath((n1:Person)-[*..6]-(n2:Person)) Find a single shortest path.
allShortestPaths((n1:Person)-[*..6]->(n2:Person)) Find all shortest paths.
size((n)-->()-->()) Count the paths matching the pattern.

Patterns

(n:Person)

Node with Person label.

(n:Person:Swedish)

Node with both Person and Swedish labels.

(n:Person {name: {value}})

Node with the declared properties.

(n)-->(m)

Relationship from n to m.

(n)--(m)

Relationship in any direction between n and m.

(n:Person)-->(m)

Node n labeled Person with relationship to m.

(m)<-[:KNOWS]-(n)

Relationship of type KNOWS from n to m.

(n)-[:KNOWS|:LOVES]->(m)

Relationship of type KNOWS or of type LOVES from n to m.

(n)-[r]->(m)

Bind the relationship to variable r.

(n)-[*1..5]->(m)

Variable length path of between 1 and 5 relationships from n to m.

(n)-[*]->(m)

Variable length path of any number of relationships from n to m. (See Performance section.)

(n)-[:KNOWS]->(m {property: {value}})

A relationship of type KNOWS from a node n to a node m with the declared property.

shortestPath((n1:Person)-[*..6]-(n2:Person))

Find a single shortest path.

allShortestPaths((n1:Person)-[*..6]->(n2:Person))

Find all shortest paths.

size((n)-->()-->())

Count the paths matching the pattern.

Labels

Labels
CREATE (n:Person {name: {value}}) Create a node with label and property.
MERGE (n:Person {name: {value}}) Matches or creates unique node(s) with the label and property.
SET n:Spouse:Parent:Employee Add label(s) to a node.
MATCH (n:Person) Matches nodes labeled `Person`.
MATCH (n:Person) WHERE n.name = {value} Matches nodes labeled `Person` with the given `name`.
WHERE (n:Person) Checks the existence of the label on the node.
labels(n) Labels of the node.
REMOVE n:Person Remove the label from the node.

CREATE (n:Person {name: {value}})

Create a node with label and property.

MERGE (n:Person {name: {value}})

Matches or creates unique node(s) with the label and property.

SET n:Spouse:Parent:Employee

Add label(s) to a node.

MATCH (n:Person)

Matches nodes labeled Person.

MATCH (n:Person)
WHERE n.name = {value}

Matches nodes labeled Person with the given name.

WHERE (n:Person)

Checks the existence of the label on the node.

labels(n)

Labels of the node.

REMOVE n:Person

Remove the label from the node.

Lists
['a', 'b', 'c'] AS coll Literal lists are declared in square brackets.
size({coll}) AS len, {coll}[0] AS value Lists can be passed in as parameters.
range({firstNum}, {lastNum}, {step}) AS coll `range()` creates a list of numbers (`step` is optional), other functions returning lists are: `labels()`, `nodes()`, `relationships()`, `filter()`, `extract()`.
MATCH (a)-[r:KNOWS*]->() RETURN r AS rels Relationship variables of a variable length path contain a list of relationships.
RETURN matchedNode.coll[0] AS value, size(matchedNode.coll) AS len Properties can be lists of strings, numbers or booleans.
coll[{idx}] AS value, coll[{startIdx}..{endIdx}] AS slice List elements can be accessed with `idx` subscripts in square brackets. Invalid indexes return `null`. Slices can be retrieved with intervals from `start_idx` to `end_idx`, each of which can be omitted or negative. Out of range elements are ignored.
UNWIND {names} AS name MATCH (n {name: name}) RETURN avg(n.age) With `UNWIND`, any list can be transformed back into individual rows. The example matches all names from a list of names.

Lists

['a', 'b', 'c'] AS coll

Literal lists are declared in square brackets.

size({coll}) AS len, {coll}[0] AS value

Lists can be passed in as parameters.

range({firstNum}, {lastNum}, {step}) AS coll

range() creates a list of numbers (step is optional), other functions returning lists are: labels(), nodes(), relationships(), filter(), extract().

MATCH (a)-[r:KNOWS*]->()
RETURN r AS rels

Relationship variables of a variable length path contain a list of relationships.

RETURN matchedNode.coll[0] AS value,
       size(matchedNode.coll) AS len

Properties can be lists of strings, numbers or booleans.

coll[{idx}] AS value,
coll[{startIdx}..{endIdx}] AS slice

List elements can be accessed with idx subscripts in square brackets. Invalid indexes return null. Slices can be retrieved with intervals from start_idx to end_idx, each of which can be omitted or negative. Out of range elements are ignored.

UNWIND {names} AS name
MATCH (n {name: name})
RETURN avg(n.age)

With UNWIND, any list can be transformed back into individual rows. The example matches all names from a list of names.

Maps
{name: 'Alice', age: 38, address: {city: 'London', residential: true}} Literal maps are declared in curly braces much like property maps. Lists are supported.
WITH {person: {name: 'Anne', age: 25}} AS p RETURN p.person.name Access the property of a nested map.
MERGE (p:Person {name: {map}.name}) ON CREATE SET p = {map} Maps can be passed in as parameters and used either as a map or by accessing keys.
MATCH (matchedNode:Person) RETURN matchedNode Nodes and relationships are returned as maps of their data.
map.name, map.age, map.children[0] Map entries can be accessed by their keys. Invalid keys result in an error.

Maps

{name: 'Alice', age: 38,
 address: {city: 'London', residential: true}}

Literal maps are declared in curly braces much like property maps. Lists are supported.

WITH {person: {name: 'Anne', age: 25}} AS p
RETURN p.person.name

Access the property of a nested map.

MERGE (p:Person {name: {map}.name})
  ON CREATE SET p = {map}

Maps can be passed in as parameters and used either as a map or by accessing keys.

MATCH (matchedNode:Person)
RETURN matchedNode

Nodes and relationships are returned as maps of their data.

map.name, map.age, map.children[0]

Map entries can be accessed by their keys. Invalid keys result in an error.

Relationship Functions
type(a_relationship) String representation of the relationship type.
startNode(a_relationship) Start node of the relationship.
endNode(a_relationship) End node of the relationship.
id(a_relationship) The internal id of the relationship.

Relationship Functions

type(a_relationship)

String representation of the relationship type.

startNode(a_relationship)

Start node of the relationship.

endNode(a_relationship)

End node of the relationship.

id(a_relationship)

The internal id of the relationship.

Predicates
n.property <> {value} Use comparison operators.
exists(n.property) Use functions.
n.number >= 1 AND n.number <= 10 Use boolean operators to combine predicates.
1 <= n.number <= 10 Use chained operators to combine predicates.
n:Person Check for node labels.
variable IS NULL Check if something is `null`.
NOT exists(n.property) OR n.property = {value} Either the property does not exist or the predicate is `true`.
n.property = {value} Non-existing property returns `null`, which is not equal to anything.
n["property"] = {value} Properties may also be accessed using a dynamically computed property name.
n.property STARTS WITH 'Tob' OR n.property ENDS WITH 'n' OR n.property CONTAINS 'goodie' String matching.
n.property =~ 'Tob.*' String regular expression matching.
(n)-[:KNOWS]->(m) Ensure the pattern has at least one match.
NOT (n)-[:KNOWS]->(m) Exclude matches to `(n)-[:KNOWS]->(m)` from the result.
n.property IN [{value1}, {value2}] Check if an element exists in a list.

Predicates

n.property <> {value}

Use comparison operators.

exists(n.property)

Use functions.

n.number >= 1 AND n.number <= 10

Use boolean operators to combine predicates.

1 <= n.number <= 10

Use chained operators to combine predicates.

n:Person

Check for node labels.

variable IS NULL

Check if something is null.

NOT exists(n.property) OR n.property = {value}

Either the property does not exist or the predicate is true.

n.property = {value}

Non-existing property returns null, which is not equal to anything.

n["property"] = {value}

Properties may also be accessed using a dynamically computed property name.

n.property STARTS WITH 'Tob' OR
n.property ENDS WITH 'n' OR
n.property CONTAINS 'goodie'

String matching.

n.property =~ 'Tob.*'

String regular expression matching.

(n)-[:KNOWS]->(m)

Ensure the pattern has at least one match.

NOT (n)-[:KNOWS]->(m)

Exclude matches to (n)-[:KNOWS]->(m) from the result.

n.property IN [{value1}, {value2}]

Check if an element exists in a list.

List Predicates
all(x IN coll WHERE exists(x.property)) Returns `true` if the predicate is `true` for all elements in the list.
any(x IN coll WHERE exists(x.property)) Returns `true` if the predicate is `true` for at least one element in the list.
none(x IN coll WHERE exists(x.property)) Returns `true` if the predicate is `false` for all elements in the list.
single(x IN coll WHERE exists(x.property)) Returns `true` if the predicate is `true` for exactly one element in the list.

List Predicates

all(x IN coll WHERE exists(x.property))

Returns true if the predicate is true for all elements in the list.

any(x IN coll WHERE exists(x.property))

Returns true if the predicate is true for at least one element in the list.

none(x IN coll WHERE exists(x.property))

Returns true if the predicate is false for all elements in the list.

single(x IN coll WHERE exists(x.property))

Returns true if the predicate is true for exactly one element in the list.

Functions
coalesce(n.property, {defaultValue}) The first non-`null` expression.
timestamp() Milliseconds since midnight, January 1, 1970 UTC.
id(nodeOrRelationship) The internal id of the relationship or node.
toInt({expr}) Converts the given input into an integer if possible; otherwise it returns `null`.
toFloat({expr}) Converts the given input into a floating point number if possible; otherwise it returns `null`.
keys({expr}) Returns a list of string representations for the property names of a node, relationship, or map.
properties({expr}) Returns a map containing all the properties of a node or relationship.

Functions

coalesce(n.property, {defaultValue})

The first non-null expression.

timestamp()

Milliseconds since midnight, January 1, 1970 UTC.

id(nodeOrRelationship)

The internal id of the relationship or node.

toInt({expr})

Converts the given input into an integer if possible; otherwise it returns null.

toFloat({expr})

Converts the given input into a floating point number if possible; otherwise it returns null.

keys({expr})

Returns a list of string representations for the property names of a node, relationship, or map.

properties({expr})

Returns a map containing all the properties of a node or relationship.

Path Functions
length(path) The number of relationships in the path.
nodes(path) The nodes in the path as a list.
relationships(path) The relationships in the path as a list.
extract(x IN nodes(path) \| x.prop) Extract properties from the nodes in a path.

Path Functions

length(path)

The number of relationships in the path.

nodes(path)

The nodes in the path as a list.

relationships(path)

The relationships in the path as a list.

extract(x IN nodes(path) | x.prop)

Extract properties from the nodes in a path.

Spatial Functions
point({x: {x}, y: {y}}) Returns a point in a 2D coordinate system.
distance(point({x: {x1}, y: {y1}}), point({x: {x2}, y: {y2}})) Returns a floating point number representing the geodesic distance between two points.

Spatial Functions

point({x: {x}, y: {y}})

Returns a point in a 2D coordinate system.

distance(point({x: {x1}, y: {y1}}), point({x: {x2}, y: {y2}}))

Returns a floating point number representing the geodesic distance between two points.

List Expressions
size({coll}) Number of elements in the list.
head({coll}), last({coll}), tail({coll}) `head()` returns the first, `last()` the last element of the list. `tail()` returns all but the first element. All return `null` for an empty list.
[x IN coll WHERE x.prop <> {value} \| x.prop] Combination of filter and extract in a concise notation.
extract(x IN coll \| x.prop) A list of the value of the expression for each element in the original list.
filter(x IN coll WHERE x.prop <> {value}) A filtered list of the elements where the predicate is `true`.
reduce(s = "", x IN coll \| s + x.prop) Evaluate expression for each element in the list, accumulate the results.

List Expressions

size({coll})

Number of elements in the list.

head({coll}), last({coll}), tail({coll})

head() returns the first, last() the last element of the list. tail() returns all but the first element. All return null for an empty list.

[x IN coll WHERE x.prop <> {value} | x.prop]

Combination of filter and extract in a concise notation.

extract(x IN coll | x.prop)

A list of the value of the expression for each element in the original list.

filter(x IN coll WHERE x.prop <> {value})

A filtered list of the elements where the predicate is true.

reduce(s = "", x IN coll | s + x.prop)

Evaluate expression for each element in the list, accumulate the results.

Mathematical Functions
abs({expr}) The absolute value.
rand() Returns a random number in the range from 0 (inclusive) to 1 (exclusive), `[0,1)`. Returns a new value for each call. Also useful for selecting a subset or random ordering.
round({expr}) Round to the nearest integer; `ceil()` and `floor()` find the next integer up or down.
sqrt({expr}) The square root.
sign({expr}) `0` if zero, `-1` if negative, `1` if positive.
sin({expr}) Trigonometric functions also include `cos()`, `tan()`, `cot()`, `asin()`, `acos()`, `atan()`, `atan2()`, and `haversin()`. All arguments for the trigonometric functions should be in radians, if not otherwise specified.
degrees({expr}), radians({expr}), pi() Converts radians into degrees; use `radians()` for the reverse, and `pi()` for π.
log10({expr}), log({expr}), exp({expr}), e() Logarithm base 10, natural logarithm, `e` to the power of the parameter, and the value of `e`.

Mathematical Functions

abs({expr})

The absolute value.

rand()

Returns a random number in the range from 0 (inclusive) to 1 (exclusive), [0,1). Returns a new value for each call. Also useful for selecting a subset or random ordering.

round({expr})

Round to the nearest integer; ceil() and floor() find the next integer up or down.

sqrt({expr})

The square root.

sign({expr})

0 if zero, -1 if negative, 1 if positive.

sin({expr})

Trigonometric functions also include cos(), tan(), cot(), asin(), acos(), atan(), atan2(), and haversin(). All arguments for the trigonometric functions should be in radians, if not otherwise specified.

degrees({expr}), radians({expr}), pi()

Converts radians into degrees; use radians() for the reverse, and pi() for π.

log10({expr}), log({expr}), exp({expr}), e()

Logarithm base 10, natural logarithm, e to the power of the parameter, and the value of e.

String Functions
toString({expression}) String representation of the expression.
replace({original}, {search}, {replacement}) Replace all occurrences of `search` with `replacement`. All arguments must be expressions.
substring({original}, {begin}, {subLength}) Get part of a string. The `subLength` argument is optional.
left({original}, {subLength}), right({original}, {subLength}) The first part of a string. The last part of the string.
trim({original}), lTrim({original}), rTrim({original}) Trim all whitespace, or on the left or right side.
toUpper({original}), toLower({original}) UPPERCASE and lowercase.
split({original}, {delimiter}) Split a string into a list of strings.
reverse({original}) Reverse a string.
size({string}) Calculate the number of characters in the string.

String Functions

toString({expression})

String representation of the expression.

replace({original}, {search}, {replacement})

Replace all occurrences of search with replacement. All arguments must be expressions.

substring({original}, {begin}, {subLength})

Get part of a string. The subLength argument is optional.

left({original}, {subLength}),
  right({original}, {subLength})

The first part of a string. The last part of the string.

trim({original}), lTrim({original}),
  rTrim({original})

Trim all whitespace, or on the left or right side.

toUpper({original}), toLower({original})

UPPERCASE and lowercase.

split({original}, {delimiter})

Split a string into a list of strings.

reverse({original})

Reverse a string.

size({string})

Calculate the number of characters in the string.

Aggregating Functions
count(*) The number of matching rows.
count(variable) The number of non-`null` values.
count(DISTINCT variable) All aggregating functions also take the `DISTINCT` operator, which removes duplicates from the values.
collect(n.property) List from the values, ignores `null`.
sum(n.property) Sum numerical values. Similar functions are `avg()`, `min()`, `max()`.
percentileDisc(n.property, {percentile}) Discrete percentile. Continuous percentile is `percentileCont()`. The `percentile` argument is from `0.0` to `1.0`.
stDev(n.property) Standard deviation for a sample of a population. For an entire population use `stDevP()`.

Aggregating Functions

count(*)

The number of matching rows.

count(variable)

The number of non-null values.

count(DISTINCT variable)

All aggregating functions also take the DISTINCT operator, which removes duplicates from the values.

collect(n.property)

List from the values, ignores null.

sum(n.property)

Sum numerical values. Similar functions are avg(), min(), max().

percentileDisc(n.property, {percentile})

Discrete percentile. Continuous percentile is percentileCont(). The percentile argument is from 0.0 to 1.0.

stDev(n.property)

Standard deviation for a sample of a population. For an entire population use stDevP().

CASE
CASE n.eyes WHEN 'blue' THEN 1 WHEN 'brown' THEN 2 ELSE 3 END Return `THEN` value from the matching `WHEN` value. The `ELSE` value is optional, and substituted for `null` if missing.
CASE WHEN n.eyes = 'blue' THEN 1 WHEN n.age < 40 THEN 2 ELSE 3 END Return `THEN` value from the first `WHEN` predicate evaluating to `true`. Predicates are evaluated in order.

CASE

CASE n.eyes
 WHEN 'blue' THEN 1
 WHEN 'brown' THEN 2
 ELSE 3
END

Return THEN value from the matching WHEN value. The ELSE value is optional, and substituted for null if missing.

CASE
 WHEN n.eyes = 'blue' THEN 1
 WHEN n.age < 40 THEN 2
 ELSE 3
END

Return THEN value from the first WHEN predicate evaluating to true. Predicates are evaluated in order.

Performance
Use parameters instead of literals when possible. This allows Cypher to re-use your queries instead of having to parse and build new execution plans. Always set an upper limit for your variable length patterns. It’s easy to have a query go wild and touch all nodes in a graph by mistake. Return only the data you need. Avoid returning whole nodes and relationships — instead, pick the data you need and return only that. Use `PROFILE` / `EXPLAIN` to analyze the performance of your queries. See Query Tuning for more information on these and other topics, such as planner hints.

Performance

Use parameters instead of literals when possible. This allows Cypher to re-use your queries instead of having to parse and build new execution plans.
Always set an upper limit for your variable length patterns. It’s easy to have a query go wild and touch all nodes in a graph by mistake.
Return only the data you need. Avoid returning whole nodes and relationships — instead, pick the data you need and return only that.
Use PROFILE / EXPLAIN to analyze the performance of your queries. See Query Tuning for more information on these and other topics, such as planner hints.