The Cypher query language is composed of a variety of clauses. These are similar to verbs in a natural language, describing what action to take on the data. Each clause serves a unique purpose and has a specific syntax. This guide will cover the most common and useful clauses in Cypher.
MATCH
The MATCH clause is used to identify a pattern within the graph database. It is primarily used when reading or querying data.
MATCH (p:Person { name: 'John Doe' })
RETURN p
OPTIONAL MATCH
OPTIONAL MATCH keeps each input row when its pattern has no match. Previously bound variables retain their values and variables introduced by the optional pattern receive null. As the first clause, OPTIONAL MATCH starts with one input row, so an empty graph still yields one row with null bindings. When an earlier clause yields zero rows, a later OPTIONAL MATCH receives zero input rows.
MATCH (a:Person)
OPTIONAL MATCH (a)-[r:KNOWS]->(b)
WHERE r.since >= 2020
RETURN a.name AS person, b.name AS acquaintance
The WHERE attached to OPTIONAL MATCH qualifies its matches. If no relationship from a meets that condition, the row still contains a.name and the acquaintance is null. A later WITH … WHERE filters the rows produced by the optional match.
Comma-separated patterns in a single OPTIONAL MATCH must match together. In this example, both b and c are null for a person if the combined pattern has no match. Use separate OPTIONAL MATCH clauses when each pattern should preserve its own successful bindings.
MATCH (a:Person)
OPTIONAL MATCH (a)-[:KNOWS]->(b), (a)-[:WORKS_WITH]->(c)
RETURN a.name AS person, b.name AS acquaintance, c.name AS colleague
WHERE
WHERE checks candidate patterns in a MATCH or OPTIONAL MATCH. A candidate satisfies the condition only when it evaluates to true. A comparison with a missing property can produce null.
MATCH (p:Person)
WHERE p.age > 30
RETURN p.name
You can also write a predicate inside a node or relationship pattern in a matching clause, such as (p:Person WHERE p.age > 30).
RETURN
RETURN specifies the query’s output. Use AS to assign a column name. Unaliased expressions use their source text as the column name, and each output column name must be unique. RETURN * expands the visible variables in name order. RETURN DISTINCT removes duplicate rows before sorting or paging.
MATCH (p:Person)
WHERE p.age > 30
RETURN p.name
CREATE
The CREATE clause is used to create data (nodes and relationships) in the database.
CREATE (p:Person { name: 'John Doe', age: 32 })
CREATE runs for each incoming row. It can reuse a bound node as an endpoint via its variable and can name a created path for RETURN. When creating a relationship, describe one relationship with a direction and a single type. Put variable-length patterns and inline WHERE predicates in the matching clauses. To change the labels or properties of a bound node, use SET.
Use the graph property value rules for node and relationship properties. An invalid property type aborts the write.
DELETE
DELETE removes bound nodes, relationships, or the nodes and relationships in a named path. To delete a connected node, include all of its incident relationships in the deletion. They can be selected in the same DELETE clause in any target order, removed by an earlier write, or removed automatically using DETACH DELETE. When paths share elements, a delete operation handles each element once.
MATCH (p:Person)
WHERE p.name = 'John Doe'
DELETE p
DELETE and DETACH DELETE preserve the input row and skip a null node, relationship, or path from an unmatched OPTIONAL MATCH. A later RETURN can still project a previously bound property of a deleted element.
SET
SET updates the properties of a node or relationship and can add labels to a node.
MATCH (p:Person { name: 'John Doe' })
SET p.age = 33
| Assignment | Effect |
|---|---|
SET n.age = 33 |
Set one property. Assign null to remove it. |
SET n = {name: 'Alice'} |
Replace the entire property map. |
SET n = source |
Replace all properties with a copy of the properties on the bound node or relationship source. |
SET n = {} |
Remove all properties. |
SET n += {name: 'Alice', age: null} |
Update the supplied keys and remove those assigned null. Keep the other properties. |
SET n:Employee:Mentor |
Add both labels. Each label occurs once. |
Values assigned to properties follow the graph property value rules. SET preserves the input row and skips a null target from OPTIONAL MATCH. WITH can project a property’s original value before an update so RETURN can show both the original value and the updated property.
REMOVE
REMOVE removes properties from nodes or relationships and labels from nodes. Removing an absent property or label has no effect. A null target from OPTIONAL MATCH leaves the row and the graph unchanged.
MATCH (p:Person { name: 'John Doe' })
REMOVE p.age
ORDER BY
The ORDER BY clause sorts rows in ascending order (ASC) by default. Use DESC for descending order. Null values sort last in ascending order and first in descending order.
MATCH (p:Person)
RETURN p.name
ORDER BY p.age DESC
A projection without DISTINCT or aggregation can sort by an earlier binding such as p.age, which the example leaves out of the result. With distinct or grouped results, sort by projected values or available grouping keys. Give a compound grouping key an alias when combining it with an aggregate in the sort expression. Ordering takes place before SKIP and LIMIT.
LIMIT
LIMIT caps the number of rows produced by a RETURN or WITH projection. Pair it with ORDER BY to choose which rows the projection keeps.
MATCH (p:Person)
RETURN p.name AS name
ORDER BY name
LIMIT 10
LIMIT on the RETURN after CREATE, SET, REMOVE, or DELETE restricts the returned rows. For example, RETURN p LIMIT 0 after SET p.active = true still applies the update to every input row. To limit the write’s input, put WITH … ORDER BY … LIMIT before the write.
SKIP
SKIP discards the first rows of a RETURN or WITH projection. It can be used on its own or combined with LIMIT for pagination. Use ORDER BY to define which rows to skip.
MATCH (p:Person)
RETURN p.name AS name
ORDER BY name
SKIP 10 LIMIT 10
SKIP and LIMIT accept integer literals, constant integer arithmetic, and named integer parameters. For example, use SKIP 1 + 1 LIMIT 10 or SKIP $offset LIMIT $pageSize. The evaluated values must be non-negative integers within the range 0 to 2147483647.
UNION
The UNION clause is used to combine the results of two or more MATCH queries. It does not remove duplicates.
MATCH (p:Person { name: 'John Doe' })
RETURN p
UNION
MATCH (p:Person { name: 'Jane Doe' })
RETURN p
MERGE
The MERGE clause is used to ensure that a certain pattern exists in the graph. If it does not exist, MERGE will create it.
MERGE (p:Person { name: 'John Doe' })
WITH
WITH projects the values available to later clauses. Give any expression other than a plain variable an alias with AS. Use WITH * to pass all visible variables and WITH DISTINCT to remove duplicate rows.
MATCH (p:Person)
WITH p
ORDER BY p.name ASC
RETURN p
A WHERE attached to WITH can refer to projected values. A WITH without DISTINCT or aggregation also lets its own WHERE refer to incoming variables. In this example, p.age is available to the filter, and RETURN uses the projected name person.
MATCH (p:Person)
WITH p.name AS person
WHERE p.age >= 18 AND person STARTS WITH 'A'
RETURN person
UNWIND
UNWIND expands each input list into rows, one for each element occurrence. An empty list or a null list yields zero rows. A list that contains a null element produces a row with that null. When the preceding match yields zero rows, UNWIND receives no input and later clauses have nothing to process. For nested lists, use a second UNWIND to expand the inner lists.
WITH [1, 2, 3] AS list
UNWIND list AS number
RETURN number
FOREACH
The FOREACH clause is used to update data within a list, whether that data is a set of nodes, relationships, or a path.
MATCH (p:Person { name: 'John Doe' })
FOREACH (n IN ['Jane', 'Bob', 'Alice'] |
CREATE (p)-[:KNOWS]->(:Person { name: n }))
CASE
The CASE clause allows for conditional logic in queries. It’s similar to IF-THEN-ELSE statements in other programming languages.
MATCH (p:Person)
RETURN p.name,
CASE WHEN p.age >= 18 THEN 'Adult'
ELSE 'Minor'
END AS status