JasonWarrenUK Neo4j/Cypher Mastery
Comprehensive guide to Neo4j graph database and Cypher query language. Covers fundamental concepts, common patterns, performance optimization, schema design, and integration with PostgreSQL/Supabase.
When This Skill Applies
Use this skill when:
- Writing Cypher queries
- Designing graph schemas
- Optimizing graph traversals
- Building recommendation systems
- Modeling hierarchies or networks
- Integrating Neo4j with relational databases
- Questions about graph database patterns
Core Concepts
Nodes, Relationships, Properties
Nodes - Entities (nouns):
// Simple node
CREATE (u:User)
// Node with properties
CREATE (u:User {
id: 'user-123',
name: 'Alice',
email: 'alice@example.com'
})
// Multiple labels
CREATE (p:Person:Developer {name: 'Bob'})
Relationships - Connections (verbs):
// Simple relationship
CREATE (a)-[:FOLLOWS]->(b)
// Relationship with properties
CREATE (a)-[:FOLLOWS {since: date(), strength: 'strong'}]->(b)
// Relationship types are UPPERCASE by convention
CREATE (a)-[:MEMBER_OF {role: 'admin'}]->(org)
Properties - Attributes (key-value pairs):
// Node properties
{
id: 'user-123',
name: 'Alice',
age: 30,
verified: true,
createdAt: datetime()
}
// Relationship properties
{
since: date(),
weight: 0.85,
type: 'professional'
}
Graph Thinking
Relational mindset:
-- Joins and foreign keys
SELECT * FROM users u
JOIN follows f ON f.follower_id = u.id
JOIN users u2 ON f.followed_id = u2.id
WHERE u.id = '123';
Graph mindset:
// Pattern matching
MATCH (u:User {id: '123'})-[:FOLLOWS]->(friend)
RETURN friend;
Key difference: Relationships are first-class citizens in graphs.
Cypher Fundamentals
MATCH - Finding Patterns
Basic pattern:
// Find all users
MATCH (u:User)
RETURN u;
// Find users with specific property
MATCH (u:User {name: 'Alice'})
RETURN u;
// Find users matching condition
MATCH (u:User)
WHERE u.age > 25
RETURN u;
Relationship patterns:
// Outgoing relationship
MATCH (a)-[:FOLLOWS]->(b)
RETURN a, b;
// Incoming relationship
MATCH (a)<-[:FOLLOWS]-(b)
RETURN a, b;
// Any direction
MATCH (a)-[:FOLLOWS]-(b)
RETURN a, b;
// Multiple relationships
MATCH (a)-[:FOLLOWS]->(b)-[:FOLLOWS]->(c)
RETURN a, b, c;
// Variable length
MATCH (a)-[:FOLLOWS*1..3]->(b)
RETURN a, b;
CREATE - Adding Data
Create nodes:
// Single node
CREATE (u:User {id: 'user-123', name: 'Alice'})
RETURN u;
// Multiple nodes
CREATE
(a:User {name: 'Alice'}),
(b:User {name: 'Bob'}),
(c:User {name: 'Charlie'});
Create relationships:
// Find existing nodes, create relationship
MATCH (a:User {name: 'Alice'})
MATCH (b:User {name: 'Bob'})
CREATE (a)-[:FOLLOWS]->(b);
// Create nodes and relationships together
CREATE (a:User {name: 'Alice'})-[:FOLLOWS]->(b:User {name: 'Bob'});
MERGE - Create or Match
Create if not exists:
// Create user only if doesn't exist
MERGE (u:User {id: 'user-123'})
ON CREATE SET u.name = 'Alice', u.createdAt = datetime()
ON MATCH SET u.lastSeen = datetime()
RETURN u;
// Create relationship only if doesn't exist
MATCH (a:User {id: 'user-123'})
MATCH (b:User {id: 'user-456'})
MERGE (a)-[r:FOLLOWS]->(b)
ON CREATE SET r.since = datetime()
RETURN r;
Important: MERGE matches on entire pattern:
// This matches on ALL properties
MERGE (u:User {id: 'user-123', name: 'Alice'})
// Better: Match on unique constraint only
MERGE (u:User {id: 'user-123'})
SET u.name = 'Alice'
SET - Updating Properties
// Set single property
MATCH (u:User {id: 'user-123'})
SET u.name = 'Alicia'
RETURN u;
// Set multiple properties
MATCH (u:User {id: 'user-123'})
SET u.name = 'Alicia', u.verified = true
RETURN u;
// Set properties from map
MATCH (u:User {id: 'user-123'})
SET u += {name: 'Alicia', age: 31}
RETURN u;
// Add label
MATCH (u:User {id: 'user-123'})
SET u:Verified
RETURN u;
DELETE - Removing Data
// Delete node (only if no relationships)
MATCH (u:User {id: 'user-123'})
DELETE u;
// Delete node and all relationships
MATCH (u:User {id: 'user-123'})
DETACH DELETE u;
// Delete relationship only
MATCH (a:User)-[r:FOLLOWS]->(b:User)
WHERE a.id = 'user-123' AND b.id = 'user-456'
DELETE r;
// Delete properties
MATCH (u:User {id: 'user-123'})
REMOVE u.age, u.verified
RETURN u;
RETURN - Formatting Results
// Return nodes
MATCH (u:User)
RETURN u;
// Return specific properties
MATCH (u:User)
RETURN u.id, u.name;
// Alias properties
MATCH (u:User)
RETURN u.name AS userName, u.email AS userEmail;
// Return count
MATCH (u:User)
RETURN count(u) AS totalUsers;
// Return distinct
MATCH (u:User)-[:FOLLOWS]->(friend)
RETURN DISTINCT friend.name;
Additional resources
Worked query patterns and mechanical detail, loaded only when needed:
- query-patterns.md: social graph (followers, blocking), hierarchy (org charts, categories), recommendation (collaborative/content-based filtering), path-finding (shortest path, Dijkstra), access control
- performance-and-schema.md: indexes/constraints, PROFILE-driven optimisation tips, batch operations with UNWIND/APOC, schema modelling guidelines (relationships vs properties, multiple labels)
- postgres-integration.md: shared-key and event-driven sync patterns with Supabase, hybrid query examples
Success Criteria
Neo4j implementation is successful when:
- Queries leverage graph traversal strengths
- Indexes on frequently queried properties
- Bounded traversals (not unbounded
*) - Clear distinction between nodes/relationships/properties
- Integration with relational database clean
- Performance acceptable for use case
- Schema supports future requirements