How to Query Graphs with Cypher: Complete Tutorial

Cypher is the declarative query language designed to interact with graph databases such as Neo4j (Official site). It enables you to perform complex queries on graph data structures intuitively and efficiently. In this tutorial, we will guide you through the fundamentals and practical usage of Cypher to query graphs effectively.

Prerequisites

A basic understanding of graph databases and graph theory concepts.
Neo4j or a compatible graph database installation. See our How to Create Graphs in Neo4j: A Step-by-Step Tutorial for getting started.
Access to Neo4j Browser or any graph data visualization/query interface.
Familiarity with basic database querying concepts is helpful but not required.

1. Understanding Cypher Syntax and Structure

Cypher queries are built around pattern matching. Patterns represent graph structures using ASCII-art-like syntax where nodes, relationships, and properties are specified.

// Basic pattern: Match a node
MATCH (n:Person)
RETURN n

This query finds all nodes labeled Person and returns them.

Nodes and Relationships

Node: Denoted by parentheses ( ). Labels are prefixed with a colon: (name:Label).
Relationship: Denoted by square brackets [ ] inside arrows which specify direction: -->, <--, or undirected --.

// Match a pattern with relationship
MATCH (a:Person)-[r:KNOWS]->(b:Person)
RETURN a, r, b

2. Writing Queries to Retrieve Graph Data

Cypher allows you to query nodes, their properties, and the relationships between them with simple clauses:

MATCH: Identifies patterns
WHERE: Filters nodes or relationships
RETURN: Specifies what to output

Example: Find all people older than 30

MATCH (p:Person)
WHERE p.age > 30
RETURN p.name, p.age

3. Filtering and Conditions

Using the WHERE clause you can refine queries imposing conditions on node labels, properties, or relationship attributes.

// Find people named 'Alice' who know someone
MATCH (a:Person {name: 'Alice'})-[r:KNOWS]->(b)
RETURN b.name

4. Aggregation and Counts

Cypher supports aggregation functions such as count(), avg(), sum(), and others useful for summarizing data.

// Count number of friends for each person
MATCH (p:Person)-[:KNOWS]->(friend)
RETURN p.name, count(friend) AS friendCount
ORDER BY friendCount DESC

5. Advanced Pattern Matching

Using variable length paths lets you search relationships with varying hops.

// Find friends of friends up to 3 hops away
MATCH (p:Person {name: 'Alice'})-[:KNOWS*1..3]->(foaf)
RETURN DISTINCT foaf.name

6. Creating and Modifying Data

Besides querying, Cypher supports data creation and updates. Examples:

// Create a new person node
CREATE (p:Person {name: 'Bob', age: 25})

// Create a KNOWS relationship
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS]->(b)

7. Troubleshooting Common Issues

No results returned: Verify your patterns are correct and data exists.
Syntax errors: Cypher is case-insensitive for keywords but check parentheses, brackets, and commas carefully.
Performance: Large pattern matches can be optimized by adding indexes on frequently queried properties.