Each section links to the page that explains it in full.
MATCH: pattern matching
MATCH (n)
RETURN n
MATCH (n:Person {name: 'Alice'})
RETURN n.age
MATCH (a:Person)-->(b:Company)
RETURN a.name, b.name
MATCH (a:Person)-[e:KNOWS {since: 2010}]->(b:Person)
RETURN a.name, e.since, b.name
MATCH (a)-[r:KNOWS|WORKS_AT]->(b)
RETURN a.name, type(r), b.name
MATCH (n:Person|Company)
RETURN n.name
MATCH (n:!Person)
RETURN n.name
MATCH (a:Person)-[e]-(b)
RETURN a.name, b.name
MATCH (a:Person WHERE a.age > 30)
-[r:KNOWS WHERE r.since > 2012]->(b)
RETURN b.name
MATCH (n:Person)
ORDER BY n.age LIMIT 2
RETURN n.name()is a node,[]is an edge,-ignores direction.- Node labels use
:Labeland can be stacked:(n:Person:Employee). - Edge types use
:EDGE_TYPE:-[:KNOWS]->. An edge has exactly one type, and[:A|B]matches either. - Label expressions:
(n:A|B),(n:!A),(n:A&B), also on edge types and inWHERE. - Values, labels and edge types can be parameters, see Parameters below.
RETURN ngives the internal node ID. Return properties explicitly (RETURN n.name), as a map projection (RETURN n {.name, .age}), or all of them withproperties(n).- Unknown labels and properties are forgiving: they match nothing or read as
null.
OPTIONAL MATCH
MATCH (a:Person)
OPTIONAL MATCH (a)-[:WORKS_AT]->(c:Company)
RETURN a.name, c.name
MATCH (a:Person)
OPTIONAL MATCH (a)-[:KNOWS]->(b)
RETURN a.name, count(b)WHERE: filter
MATCH (n)
WHERE n:Person
RETURN n.name
MATCH (n:Person)
WHERE n.age >= 18 AND n.city = 'London'
RETURN n.name
MATCH (n:Person)
WHERE n.name STARTS WITH 'A' OR n.name CONTAINS 'ro'
RETURN n.name
MATCH (n:Person)
WHERE n.name IN ['Alice', 'Bob']
RETURN n.name
MATCH (n:Person)
WHERE 'admin' IN n.tags
RETURN n.name
MATCH (n:Person)
WHERE n.tags IS NOT NULL
RETURN n.name
MATCH (n)-[e]->(m)
WHERE e:KNOWS AND e.since > 2012
RETURN n.name, m.name
MATCH (p:Person)
WHERE NOT (p)-[:KNOWS]->()
RETURN p.name
MATCH (p:Person)
RETURN p.name, exists((p)-[:LIKES]->()) AS likesSomething- Comparison:
= <> != < <= > >=, null testsIS NULL/IS NOT NULL, label testsn:Person/n IS Person, booleanAND OR XOR NOT. - Strings and lists:
IN,STARTS WITH,ENDS WITH,CONTAINS, concatenation with+or||. - Use
IS NOT NULLto test for a property, andexists()for a pattern.=~is not yet supported. - Integers and Doubles compare by value (
n.age = 30.0). Compare two Doubles with a range (n.score > 1.99 AND n.score < 2.01).
Lookup by native node ID
MATCH (n)
WHERE n = 0
RETURN n.name
MATCH (n)-[:KNOWS]->(m)
WHERE n = 0
RETURN m.name
UNWIND [0, 1, 2] AS x
MATCH (n)
WHERE n = x
RETURN x, n.name
UNWIND [[0, 1], [2, 3]] AS p
MATCH (a)
WHERE a = p[0]
MATCH (b)
WHERE b = p[1]
RETURN a.name, b.name
EXPLAIN MATCH (n)
WHERE n = 0
RETURN n.namen = 0,id(n) = 0andn IN [0, 1, 2]look the nodes up directly.- With a parameter, compare the node itself:
WHERE n = $id. For a list,UNWIND $ids AS x MATCH (n) WHERE n = x, sinceWHERE n IN $idschecks every node.
Parameters
client.query(
"MATCH (n:Person) WHERE n.age >= $minAge RETURN n.name",
{"minAge": 30},
)
client.query(
"MATCH (n:Person {name: $name}) RETURN n.age",
{"name": "O'Brien"},
)
client.query(
"UNWIND $rows AS row "
"CREATE (:City {name: row.name, pop: row.pop})",
{"rows": [{"name": "Brest", "pop": 139000}]},
)
client.query(
"MATCH (n:$label) RETURN n.name", {"label": "Person"}
)- A parameter holds a value anywhere an expression goes, or a label or an edge type. No quoting or escaping is needed.
SKIP,LIMITand the vector of aVECTOR SEARCHtake literals.- In the shell:
:param minAge => 30. In JavaScript:client.query(cypher, { parameters: { minAge: 30 } }).
Joins and Cartesian products
MATCH (p:Person), (c:Company)
RETURN p.name, c.name
MATCH (a:Person)-[:KNOWS]->(b), (b)-[:WORKS_AT]->(c)
RETURN a.name, b.name, c.name
MATCH (a:Person)-->(i:Interest)<--(b:Person)
WHERE a <> b
RETURN a.name, b.name, i.name
MATCH (a:Person), (b:Person)
WHERE a.city = b.city AND a <> b
RETURN a.name, b.name- A comma separates independent patterns. Shared variables create joins, unrelated patterns create Cartesian products (N × M rows).
Variable-length and quantified paths
MATCH (a:Person {name: 'Alice'})-[:KNOWS]->+(b)
RETURN DISTINCT b.name
MATCH (a:Person {name: 'Alice'})-[:KNOWS]->*(b)
RETURN DISTINCT b.name
MATCH (a:Person {name: 'Alice'})-[:KNOWS]->{1,2}(b)
RETURN DISTINCT b.name
MATCH (a:Person {name: 'Alice'})-[:KNOWS*1..3]->(b)
RETURN DISTINCT b.name
MATCH (a:Person {name: 'Alice'})
((x)-[:KNOWS]->(y) WHERE y.age > x.age)+ (b)
RETURN b.name
MATCH (a:Person {name: 'Alice'})-[e:KNOWS]->+(b)
RETURN b.name, [r IN e | r.since]
MATCH p = (a:Person {name: 'Alice'})-[:KNOWS]->+(b)
RETURN [n IN nodes(p) | n.name], length(p),
reduce(t = 0, r IN relationships(p) | t + r.since)- Postfix
->*is 0 or more hops. Bracket-[:KNOWS*]->is 1 or more. - Each edge is used at most once per path. Bound the length on large graphs.
WITH, ORDER BY, SKIP, LIMIT, UNION, NEXT, WHEN
Results and aggregation, NEXT and WHEN
MATCH (n:Person)
WITH n.city AS city, count(*) AS c
WHERE c > 1
RETURN city, c
MATCH (n:Person)
RETURN DISTINCT n.city
MATCH (n:Person)
RETURN n.name, n.age
ORDER BY n.age DESC SKIP 1 LIMIT 2
MATCH (p:Person)
RETURN p.name AS name
UNION
MATCH (c:Company)
RETURN c.name AS name
MATCH (n:Person)
RETURN n.city AS city, count(*) AS c
NEXT
RETURN max(c) AS biggest
MATCH (n:Person)
RETURN n.name AS nm, n.age AS age
NEXT
WHEN age > 30 THEN RETURN nm, 'senior' AS band
ELSE RETURN nm, 'junior' AS band
MATCH (n:Person)
WHERE n.age > 30
RETURN n AS p
NEXT
MATCH (p)-[:KNOWS]->(f)
RETURN p.name, f.name
WHEN COUNT { MATCH (n:Person) } > 3 THEN RETURN 'big' AS size
ELSE RETURN 'small' AS size- Expressions in
WITH, and in aRETURNfollowed byNEXT, must be aliased. Only the returned columns carry over aNEXT. WHENbranches return the same columns. WithoutELSE, a conditional with no matching branch returns no rows.- Nulls sort last ascending and first descending.
Aggregation
MATCH (n:Person)
RETURN count(*), count(n.age), sum(n.age),
avg(n.age), min(n.age), max(n.age)
MATCH (a:Person)-[:WORKS_AT]->(c:Company)
RETURN c.name, count(a) AS employees, collect(a.name) AS who
MATCH (n:Person)
RETURN count(DISTINCT n.city)
MATCH ()-[r]->()
RETURN type(r) AS t, count(*) AS c
ORDER BY c DESC
MATCH (n:Person)
RETURN stDev(n.age), percentileCont(n.age, 0.5) AS median- Grouping is implicit. To filter on an aggregate, compute it in a
WITHand filter afterwards.
UNWIND, lists, CASE
UNWIND [1, 2, 3] AS x
RETURN x * 10
MATCH (n:Person)
WITH collect(n.name) AS names
UNWIND names AS nm
RETURN nm
MATCH (n:Person)
UNWIND n.tags AS t
RETURN t, count(*)
RETURN [x IN range(1, 6) WHERE x % 2 = 0 | x * x]
MATCH (a:Person)
RETURN a.name, [(a)-[:KNOWS]->(b) | b.name] AS friends
MATCH (n:Person)
WHERE any(t IN n.tags WHERE t = 'vip')
RETURN n.name
RETURN reduce(total = 0, x IN [1, 2, 3] | total + x)
MATCH (n:Person)
RETURN n.name,
CASE WHEN n.age >= 35 THEN 'senior' ELSE 'junior' END AS band
MATCH (n:Person)
RETURN n {.name, .age, nextAge: n.age + 1} AS person
WITH {a: {b: 2}} AS m
RETURN m.a.b, m['a']- Map projection:
n {.name}picks properties,n {.*}takes them all,n {key: expr}adds computed entries.
Subqueries
MATCH (p:Person)
WHERE EXISTS { (p)-[:WORKS_AT]->(:Company {name: 'Acme'}) }
RETURN p.name
MATCH (p:Person)
RETURN p.name, COUNT { (p)-[:KNOWS]->() } AS outDegree
MATCH (p:Person)
RETURN p.name,
COLLECT { MATCH (p)-[:KNOWS]->(f) RETURN f.name } AS friends
MATCH (c:Company)
RETURN c.name, COLLECT {
MATCH (p:Person)-[:WORKS_AT]->(c)
RETURN p.name ORDER BY p.age DESC LIMIT 1
} AS oldest
MATCH (p:Person)
CALL (*) {
MATCH (p)-[:KNOWS]->(f)
RETURN count(f) AS deg
}
RETURN p.name, deg
MATCH (p:Person)
CALL (p) {
MATCH (p)-[:KNOWS]->(f)
RETURN f.name AS friend LIMIT 1
}
RETURN p.name, friend
MATCH (p:Person)
OPTIONAL CALL (p) {
MATCH (p)-[:WORKS_AT]->(c)
RETURN c.name AS co
}
RETURN p.name, coFunctions
| Category | Functions |
|---|---|
| Entity | id, elementId, labels, type, startNode, endNode, keys, properties |
| Path and list | nodes, relationships, length, size, head, last, tail, reverse, isEmpty, range, reduce, allReduce, coll.indexOf |
| Predicates | all, any, none, single, exists(pattern) |
| Conversion | toInteger, toFloat, toString, toBoolean, their ...OrNull forms, coalesce |
| String | toUpper, toLower, trim, ltrim, rtrim, substring, left, right, split, replace, reverse, char_length, normalize |
| Math | abs, sign, ceil, floor, round, sqrt, exp, log, log10, pi, e, sin, cos, tan, and more |
| Temporal | datetime, duration |
| Spatial | point, point.distance, point.withinBBox |
| Embedding | cosine_similarity, euclidean_distance |
| Aggregate | count, collect, sum, avg, min, max, stDev, stDevP, percentileCont, percentileDisc |
MATCH (n)-[e]->(m)
RETURN labels(n), type(e), labels(m)
RETURN datetime('2024-03-15T10:30:00Z') + duration({days: 1})
MATCH (n:Document)
RETURN n.title, cosine_similarity(n.emb, (0.4, 0.3, 0.8, 0.1))
RETURN round(point.distance(
point({latitude: 51.5074, longitude: -0.1278}),
point({latitude: 48.8566, longitude: 2.3522})
)) AS meters- Function names are case-insensitive.
- Use
type(e)for an edge’s type (it replacesedgeType()). - Read map keys with
m.key,m['key']orm[k], including maps stored as properties.
Data types
| Type | Example |
|---|---|
| String | 'hello' or "hello" |
| Integer | 30, 0x1F |
| Double | 3.14 |
| Boolean | true |
| List | [1, 'a', [2]] |
| Map | {a: 1} |
| DateTime | datetime('2024-03-15T10:30:00Z') |
| Duration | duration({days: 2}) |
| Point | point({x: 1, y: 2}), point({latitude: 51.5, longitude: -0.12}) |
| Embedding | (1.2, 2.0, 0.0) (parentheses, not brackets) |
Writing (inside a change)
CHANGE NEW
CREATE (:Person {name: 'Alice', age: 30})
CREATE (:Person {name: 'Mick'})
-[:FRIEND_OF {since: 2020}]->(:Person {name: 'John'})
COMMIT
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Mick'})
CREATE (a)-[:KNOWS]->(b)
MERGE (n:Person {name: 'Alice'})
ON CREATE SET n.created = true
ON MATCH SET n.seen = true
MATCH (n:Person {name: 'Alice'})
SET n.age = 31, n.position = 'Developer'
MATCH (n:Person {name: 'Alice'})
SET n += {city: 'Berlin', level: 2}
MATCH (n:Person {name: 'Alice'})
REMOVE n.position
MATCH (n:Person {name: 'Alice'})
DETACH DELETE n
MATCH (n:Person)-[e:KNOWS]->(m)
DELETE e
FOREACH (i IN [1, 2, 3] | CREATE (:Num {v: i}))
UNWIND [[0, 1], [2, 3]] AS p
MATCH (a)
WHERE a = p[0]
MATCH (b)
WHERE b = p[1]
CREATE (a)-[:KNOWS]->(b)
CHANGE SUBMIT- Every node needs at least one label and every edge exactly one type. Labels are set at creation.
SET n += {...}adds and updates properties,SET n = {...}replaces them all.- Run
COMMITafter creating entities that a later query mustMATCH.MERGEsees them without it, andCHANGE SUBMITcommits for you. - In the Python SDK, call
client.checkout()afterCHANGE SUBMIT. - To build a new graph from more than a few thousand entities, use
LOAD PARQUET. To add edges between existing nodes,UNWINDpairs of node IDs as above.
Procedures
| Query | Description |
|---|---|
CALL db.labels() | All node labels |
CALL db.edgeTypes() | All edge types |
CALL db.propertyTypes() | All property keys and their types |
CALL db.history() | Commit history |
CALL db.describeCommit('<hash>') | Counts for a single commit |
CALL db.getNodes([0, 1]) | Labels and all properties of specific nodes |
CALL db.procedures() | All procedures and signatures |
Outputs can be chained: CALL db.labels() YIELD label MATCH (n) WHERE label IN labels(n) RETURN label, count(n).
Graph algorithms and search
MATCH (a:Station {name: 'Ashchurch'}),
(b:Station {name: 'Pershore'})
shortestPath(a, b, distance, dist, path)
RETURN dist, path
VECTOR SEARCH IN my_index FOR 5 (1.2, 0.5, 3.0, 0.1)
YIELD ids, score
RETURN ids, scoreSee Shortest path and Vector search.
Engine commands
| Command | Description |
|---|---|
CREATE GRAPH <name> | Create a new named graph |
LOAD GRAPH <name> | Load an existing graph |
LOAD GML 'f.gml' AS g | Load a GML file as a graph (file in <turing-dir>/data) |
LOAD JSONL 'f.jsonl' AS g | Load a JSONL file as a graph, optionally WITH EMBEDDINGS, WITH DATETIMES, WITH DURATIONS |
LOAD PARQUET '<dir>' AS g | Load Parquet files as a graph |
LOAD CSV 'f.csv' [WITH HEADERS] [ON ERROR SKIP|FAIL] AS row | Stream rows from a CSV file |
LIST GRAPH / LIST AVAILABLE GRAPHS | Loaded graphs / graphs on disk |
CHANGE NEW / SUBMIT / DELETE / LIST | Create, merge, discard and list changes |
COMMIT | Seal pending writes inside a change |
LOAD COMMIT '<hash>' | Load a past commit before querying it (the shell’s and the Python SDK’s checkout do it for you) |
MERGE_DATAPARTS | Compact the graph’s DataParts into one (renumbers nodes) |
CREATE VECTOR INDEX <name> WITH DIMENSION <n> METRIC <COSINE|EUCLID> | Create a vector index |
SHOW VECTOR INDEXES / DELETE VECTOR INDEX <name> | List / delete vector indexes |
INSTALL <ext> / SHOW EXTENSIONS / SHOW PROCEDURES | Load a procedure extension / list extensions / list procedures |
EXPLAIN <query> / EXPLAIN (db) <query> | Show the query plan without running it / only the database plan |

