2017-04-12 16:30:09 +00:00
---
language: cypher
filename: LearnCypher.cql
contributors:
- ["Théo Gauchoux", "https://github.com/TheoGauchoux"]
---
Cypher is the Neo4j’ s query language to manipulate graphs easily. It reuses syntax from SQL and mixes it with kind of ascii-art to represent graphs.
This tutorial assumes that you already know graph concepts like nodes and relationships.
[Read more here. ](https://neo4j.com/developer/cypher-query-language/ )
Nodes
---
**Represents a record in a graph.**
2018-08-15 12:35:24 +00:00
`()`
2017-04-13 15:21:23 +00:00
It's an empty *node* , to indicate that there is a *node* , but it's not relevant for the query.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(n)`
2017-08-23 08:14:39 +00:00
It's a *node* referred by the variable **n** , reusable in the query. It begins with lowercase and uses camelCase.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(p:Person)`
2017-04-13 15:21:23 +00:00
You can add a *label* to your node, here **Person** . It's like a type / a class / a category. It begins with uppercase and uses camelCase.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(p:Person:Manager)`
2017-04-13 15:21:23 +00:00
A node can have many *labels* .
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(p:Person {name : 'Théo Gauchoux', age : 22})`
2017-04-13 15:21:23 +00:00
A node can have some *properties* , here **name** and **age** . It begins with lowercase and uses camelCase.
2017-04-12 16:30:09 +00:00
The types allowed in properties :
2017-04-13 15:21:23 +00:00
- Numeric
- Boolean
- String
- List of previous primitive types
2017-04-12 16:30:09 +00:00
2017-04-13 15:21:23 +00:00
*Warning : there isn't datetime property in Cypher ! You can use String with a specific pattern or a Numeric from a specific date.*
2018-08-15 12:35:24 +00:00
`p.name`
2017-04-13 15:21:23 +00:00
You can access to a property with the dot style.
2017-04-12 16:30:09 +00:00
Relationships (or Edges)
---
**Connects two nodes**
2018-08-15 12:35:24 +00:00
`[:KNOWS]`
2019-05-15 13:49:36 +00:00
It's a *relationship* with the *label* **KNOWS** . It's a *label* as the node's label. It begins with uppercase and use UPPER\_SNAKE\_CASE.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`[k:KNOWS]`
2017-08-23 08:14:39 +00:00
The same *relationship* , referred by the variable **k** , reusable in the query, but it's not necessary.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`[k:KNOWS {since:2017}]`
2017-04-13 15:21:23 +00:00
The same *relationship* , with *properties* (like *node* ), here **since** .
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`[k:KNOWS*..4]`
2017-04-13 15:21:23 +00:00
It's a structural information to use in a *path* (seen later). Here, ** \*..4** says "Match the pattern, with the relationship **k** which be repeated between 1 and 4 times.
2017-04-12 16:30:09 +00:00
Paths
---
**The way to mix nodes and relationships.**
2018-08-15 12:35:24 +00:00
`(a:Person)-[:KNOWS]-(b:Person)`
2017-04-13 15:21:23 +00:00
A path describing that **a** and **b** know each other.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(a:Person)-[:MANAGES]->(b:Person)`
2017-04-13 15:21:23 +00:00
A path can be directed. This path describes that **a** is the manager of **b** .
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(a:Person)-[:KNOWS]-(b:Person)-[:KNOWS]-(c:Person)`
2017-04-13 15:21:23 +00:00
You can chain multiple relationships. This path describes the friend of a friend.
2017-04-12 16:30:09 +00:00
2018-08-15 12:35:24 +00:00
`(a:Person)-[:MANAGES]->(b:Person)-[:MANAGES]->(c:Person)`
2017-04-13 15:21:23 +00:00
A chain can also be directed. This path describes that **a** is the boss of **b** and the big boss of **c** .
2017-04-12 16:30:09 +00:00
Patterns often used (from Neo4j doc) :
```
// Friend-of-a-friend
(user)-[:KNOWS]-(friend)-[:KNOWS]-(foaf)
// Shortest path
path = shortestPath( (user)-[:KNOWS*..5]-(other) )
// Collaborative filtering
(user)-[:PURCHASED]->(product)< - [ :PURCHASED ] - ( ) - [ :PURCHASED ] - > (otherProduct)
// Tree navigation
(root)< - [ :PARENT * ] - ( leaf:Category ) - [ :ITEM ] - > (data:Product)
```
2017-04-13 15:21:23 +00:00
2017-04-12 16:30:09 +00:00
Create queries
---
Create a new node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
CREATE (a:Person {name:"Théo Gauchoux"})
RETURN a
```
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
*`RETURN` allows to have a result after the query. It can be multiple, as `RETURN a, b` .*
Create a new relationship (with 2 new nodes)
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
CREATE (a:Person)-[k:KNOWS]-(b:Person)
RETURN a,k,b
```
Match queries
---
Match all nodes
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (n)
RETURN n
```
Match nodes by label
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (a:Person)
RETURN a
```
Match nodes by label and property
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (a:Person {name:"Théo Gauchoux"})
RETURN a
```
Match nodes according to relationships (undirected)
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (a)-[:KNOWS]-(b)
RETURN a,b
```
Match nodes according to relationships (directed)
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (a)-[:MANAGES]->(b)
RETURN a,b
```
Match nodes with a `WHERE` clause
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person {name:"Théo Gauchoux"})-[s:LIVES_IN]->(city:City)
WHERE s.since = 2015
RETURN p,state
```
You can use `MATCH WHERE` clause with `CREATE` clause
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (a), (b)
WHERE a.name = "Jacquie" AND b.name = "Michel"
CREATE (a)-[:KNOWS]-(b)
```
2017-04-13 15:21:23 +00:00
2017-04-12 16:30:09 +00:00
Update queries
---
Update a specific property of a node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)
WHERE p.name = "Théo Gauchoux"
SET p.age = 23
```
Replace all properties of a node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)
WHERE p.name = "Théo Gauchoux"
SET p = {name: "Michel", age: 23}
```
Add new property to a node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)
WHERE p.name = "Théo Gauchoux"
SET p + = {studies: "IT Engineering"}
```
Add a label to a node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)
WHERE p.name = "Théo Gauchoux"
SET p:Internship
```
2017-04-13 15:21:23 +00:00
2017-04-12 16:30:09 +00:00
Delete queries
---
Delete a specific node (linked relationships must be deleted before)
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)-[relationship]-()
WHERE p.name = "Théo Gauchoux"
DELETE relationship, p
```
Remove a property in a specific node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)
WHERE p.name = "Théo Gauchoux"
REMOVE p.age
```
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
*Pay attention to the `REMOVE` keyword, it's not `DELETE` !*
Remove a label from a specific node
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (p:Person)
WHERE p.name = "Théo Gauchoux"
DELETE p:Person
```
Delete entire database
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
```
MATCH (n)
OPTIONAL MATCH (n)-[r]-()
DELETE n, r
```
2024-04-06 15:33:50 +00:00
2017-04-12 16:30:09 +00:00
*Seriously, it's the `rm -rf /` of Cypher !*
2017-04-13 15:21:23 +00:00
2017-04-12 16:30:09 +00:00
Other useful clauses
---
2018-08-15 12:35:24 +00:00
`PROFILE`
2017-04-13 15:21:23 +00:00
Before a query, show the execution plan of it.
2018-08-15 12:35:24 +00:00
`COUNT(e)`
2017-04-13 15:21:23 +00:00
Count entities (nodes or relationships) matching **e** .
2018-08-15 12:35:24 +00:00
`LIMIT x`
2017-04-13 15:21:23 +00:00
Limit the result to the x first results.
2017-04-12 16:30:09 +00:00
Special hints
---
2017-04-13 15:21:23 +00:00
- There is just single-line comments in Cypher, with double-slash : // Comments
2017-08-23 08:14:39 +00:00
- You can execute a Cypher script stored in a ** .cql** file directly in Neo4j (it's an import). However, you can't have multiple statements in this file (separated by ** ;**).
2017-04-13 15:21:23 +00:00
- Use the Neo4j shell to write Cypher, it's really awesome.
- The Cypher will be the standard query language for all graph databases (known as **OpenCypher** ).