Cypher queries describe graph patterns and what to do with the nodes, relationships, and paths they find. Use this cheat sheet for common Neo4j read, write, update, delete, and tuning patterns; check your server’s Neo4j version before relying on version-specific syntax.
How to read Cypher patterns
Cypher is Neo4j’s declarative graph query language: you describe a pattern, then specify operations on the matched data. Parentheses represent nodes; square brackets represent relationships. Labels and relationship types make patterns more specific. Keywords are not case-sensitive, but variable names are case-sensitive. The current Cypher manual is the reference for syntax and behavior.
As an Amazon Associate I earn from qualifying purchases.
Find graph data with MATCH
MATCH requires the specified pattern to be present. This example finds movies acted in by a person whose name is supplied as a parameter:
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
MATCH (p:Person {name: $name})-[:ACTED_IN]->(m:Movie)
RETURN m.title AS title
ORDER BY title$name is a parameter rather than a value embedded in the query. RETURN chooses the output column, and ORDER BY sorts the results. See the manual’s MATCH clause reference.
#1 Best Overall
Match an optional pattern
Use OPTIONAL MATCH when an earlier match is required but a later pattern may be absent. Any missing optional portion is returned as null.
MATCH (p:Person {name: $name})
OPTIONAL MATCH (p)-[r:DIRECTED]->(movie)
RETURN p.name, r, movieThis query returns the person if found, even if they have no outgoing DIRECTED relationship. Put WHERE alongside the clause whose pattern it filters: it is a subclause of MATCH, OPTIONAL MATCH, or WITH, not a standalone filter in those contexts. See OPTIONAL MATCH and WHERE.
Pass, aggregate, and filter results with WITH
WITH forms a pipeline boundary: it can aggregate, calculate, rename, sort, or filter values before the next clause. Only variables named in the projection continue into the next stage, unless you use WITH *.
MATCH (c:Customer)-[:BUYS]->(p:Product)
WITH c, count(p) AS purchases
WHERE purchases > 2
RETURN c.name, purchases
ORDER BY purchases DESCHere, the query counts matched products for each customer, keeps customers with more than two purchases, then returns names and counts. Variables omitted from WITH leave scope, subject to the manual’s rules for subqueries. See WITH.
Create new data or match-or-create with MERGE
CREATE always creates the specified pattern
Use CREATE when each execution should add the specified graph pattern.
CREATE (p:Person {name: $name})
RETURN pRunning this again creates another matching node; it does not first check whether one already exists. See CREATE.
MERGE matches or creates the stated pattern
MERGE matches the whole pattern you specify, or creates it if no match exists. Choose that pattern deliberately: the identity implied by the pattern determines what is considered a match.
MERGE (p:Person {email: $email})
ON CREATE SET p.createdAt = datetime()
ON MATCH SET p.lastSeen = datetime()
RETURN pThe conditional clauses set a property on creation or on a match. MERGE by itself should not be treated as a guarantee of uniqueness in every concurrency or schema situation. See MERGE.
Rank #3
Turn a list into rows with UNWIND
UNWIND expands a list into rows. It is often useful for processing parameterized batches, as in this example:
UNWIND $rows AS row
MERGE (p:Person {id: row.id})
SET p.name = row.name
RETURN count(p) AS processedSupply $rows as a list of records with the expected fields. Validate inputs and choose a transaction strategy appropriate to the data volume; for production-scale imports, consult Neo4j’s operations documentation. See also the UNWIND reference.
Delete nodes and relationships carefully
DELETE removes a relationship or a node without relationships. To remove a node and its connected relationships, use DETACH DELETE:
MATCH (p:Person {id: $id})
DETACH DELETE pA query such as MATCH (n) DETACH DELETE n removes all graph data; run it only when that is explicitly intended. Neo4j’s cheat sheet also describes transactional batching for large deletion jobs and notes that this does not remove indexes or schema. See DELETE and the Cypher cheat sheet.
Shape and combine query results
Return only the needed output
RETURN determines the result columns. Keep it focused on the properties or values the application needs, rather than returning every node and relationship by default. To page through results, use ORDER BY with SKIP and LIMIT; pagination needs a deliberate sort if results must have a stable order. The RETURN reference covers these options.
Combine result sets with UNION
Use UNION to combine compatible result sets while removing duplicate rows; use UNION ALL to preserve duplicates. The component queries must return the same number of columns, with corresponding columns compatible in type. See UNION.
Inspect indexes and query plans
Neo4j’s cheat sheet lists range (the default), text, point, and token lookup indexes for search performance, and shows full-text and vector index syntax. An index may help a particular workload, but it does not guarantee a speedup; measure the query and data you actually use.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →EXPLAINinspects the planned query without executing it.PROFILEexecutes the query and reports runtime operators and measurements.
Use these tools to investigate how a query runs, then consult the manual’s planning and tuning guidance before changing indexes or query structure.
Best Value
Practical habits for safer, clearer queries
- Parameterize values such as names, IDs, and batches instead of building query text from user input.
- Bound variable-length patterns when the traversal depth should be limited; unbounded traversals can match far more paths than expected.
- Return only the fields needed by the caller.
- Use
EXPLAINorPROFILEto inspect plans rather than assuming an index or syntax change will be faster. - For writes, decide whether the operation should always create (
CREATE) or match-or-create the stated pattern (MERGE).
Check Cypher version compatibility
Available syntax depends on the Neo4j release. The current manual documents version prefixes including CYPHER 25 and CYPHER 5. It states that on Neo4j 2025.06 or later, CYPHER 25 selects Cypher 25 supported by the running server; CYPHER 5 selects Cypher 5 as it existed at the Neo4j 2025.06 release. Verify your deployed server’s version and consult its matching manual, especially before using newer syntax such as FILTER, dynamic labels or types, or WHEN. See the Cypher manual.
Continue learning Cypher
Neo4j’s GraphAcademy lists a free Cypher Fundamentals course covering graph reads and writes. Its course catalog also includes intermediate topics such as filtering, variable-length traversal, WITH, subqueries, UNWIND, and parameters.
For a book-length treatment, Neo4j’s recommended-books page lists Graph Data Processing with Cypher by Ravindranatha Anthapu, published by Packt, as a practical guide to building graph traversal queries with Cypher on Neo4j. Check that page for current edition and availability details: Neo4j recommended books.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
