Neo4j Cypher

When to Use

Use this skill when writing, reviewing, or debugging Cypher queries for Neo4j. Covers query patterns, performance optimization, fraud-detection domain queries, and Neo4j 5+ syntax.

Core Query Patterns

MATCH and Filtering

-- Basic node match with property filter
MATCH (c:Customer {customerId: $customerId})
RETURN c

-- Relationship traversal
MATCH (c:Customer)-[:HAS_ACCOUNT]->(a:Account)
WHERE a.status = 'active'
RETURN c, a

-- Variable-length paths
MATCH path = (a:Account)-[:TRANSACTION*1..5]->(b:Account)
RETURN path

-- Multiple relationship types
MATCH (c:Customer)-[:HAS_EMAIL|HAS_PHONE|HAS_SSN]->(pii)
RETURN c, pii

OPTIONAL MATCH

Use when the related data may not exist. Without OPTIONAL, rows with no match are dropped entirely.

MATCH (c:Customer {customerId: $customerId})
OPTIONAL MATCH (c)-[:HAS_EMAIL]->(e:Email)
OPTIONAL MATCH (c)-[:HAS_PHONE]->(p:Phone)
RETURN c, collect(DISTINCT e) AS emails, collect(DISTINCT p) AS phones

WITH Chaining

Use WITH to pipe results between query stages, filter intermediate results, and control cardinality.

MATCH (c:Customer)-[:HAS_ACCOUNT]->(a:Account)
MATCH (a)-[:PERFORM]->(tx:Transaction)
WITH c, a, count(tx) AS txCount, sum(tx.amount) AS totalAmount
WHERE txCount > 10
RETURN c.customerId, a.accountNumber, txCount, totalAmount
ORDER BY totalAmount DESC

Aggregation

-- Group and aggregate
MATCH (a:Account)-[:PERFORM]->(tx:Transaction)
WITH a, count(tx) AS txCount, sum(tx.amount) AS total, avg(tx.amount) AS avgAmount
RETURN a.accountNumber, txCount, total, avgAmount
ORDER BY total DESC
LIMIT 20

-- collect() for lists — use DISTINCT to avoid duplicates from cartesian products
MATCH (c:Customer)-[:HAS_ACCOUNT]->(a:Account)
OPTIONAL MATCH (a)-[:PERFORM]->(tx:Transaction)
RETURN c.customerId,
       collect(DISTINCT a.accountNumber) AS accounts,
       count(DISTINCT tx) AS transactionCount

UNWIND

Expand a list into rows. Useful for parameterized batch operations.

UNWIND $accountNumbers AS accNum
MATCH (a:Account {accountNumber: accNum})
RETURN a

CASE Expressions

MATCH (tx:Transaction)
RETURN tx.amount,
  CASE
    WHEN tx.amount > 10000 THEN 'high'
    WHEN tx.amount > 1000 THEN 'medium'
    ELSE 'low'
  END AS riskTier

Subqueries (CALL {})

MATCH (c:Customer)
CALL (c) {
  MATCH (c)-[:HAS_ACCOUNT]->(a:Account)-[:PERFORM]->(tx:Transaction)
  RETURN sum(tx.amount) AS totalSpend
}
RETURN c.customerId, totalSpend
ORDER BY totalSpend DESC

Write Operations

CREATE and MERGE

-- CREATE always creates new
CREATE (c:Customer {customerId: $id, firstName: $first, lastName: $last})

-- MERGE finds or creates — always specify the minimal unique key
MERGE (e:Email {address: $email})
ON CREATE SET e.createdAt = datetime()
ON MATCH SET e.lastSeen = datetime()

-- MERGE relationship
MATCH (c:Customer {customerId: $customerId})
MATCH (e:Email {address: $email})
MERGE (c)-[:HAS_EMAIL]->(e)

SET and REMOVE

MATCH (a:Account {accountNumber: $accNum})
SET a.status = 'frozen', a.frozenAt = datetime(), a:Frozen
REMOVE a:Active

DELETE

-- Delete node and all its relationships
MATCH (n:TempNode {id: $id})
DETACH DELETE n

-- Delete specific relationship
MATCH (c:Customer)-[r:HAS_EMAIL]->(e:Email {address: $email})
DELETE r

Performance

Index Usage

Always create indexes on properties used in MATCH/WHERE lookups.

-- Property index (most common)
CREATE INDEX customer_id FOR (c:Customer) ON (c.customerId)

-- Composite index
CREATE INDEX account_lookup FOR (a:Account) ON (a.accountNumber, a.status)

-- Text index for CONTAINS/STARTS WITH
CREATE TEXT INDEX email_text FOR (e:Email) ON (e.address)

-- Verify indexes
SHOW INDEXES

EXPLAIN and PROFILE

-- EXPLAIN: shows plan without executing
EXPLAIN MATCH (c:Customer {customerId: '123'})-[:HAS_ACCOUNT]->(a:Account) RETURN c, a

-- PROFILE: executes and shows actual rows/db hits per operator
PROFILE MATCH (c:Customer {customerId: '123'})-[:HAS_ACCOUNT]->(a:Account) RETURN c, a

Look for:

• NodeByLabelScan → missing index, add one
• CartesianProduct → unconnected MATCH clauses, connect them or use WITH
• Eager → query plan can't stream, may cause memory issues on large datasets
• High db hits relative to result rows → inefficient traversal

Parameterized Queries

Always use parameters ($param) instead of string interpolation. This enables query plan caching and prevents injection.

-- Good
MATCH (c:Customer {customerId: $customerId}) RETURN c

-- Bad — no plan cache, injection risk
MATCH (c:Customer {customerId: '${userInput}'}) RETURN c

Avoiding Cartesian Products

-- BAD: two unconnected MATCH clauses = cartesian product
MATCH (a:Account)
MATCH (b:Bank)
RETURN a, b  -- rows = |accounts| × |banks|

-- GOOD: connect through relationships
MATCH (a:Account)-[:PERFORM]->(tx:Transaction)-[:BENEFITS_TO]->(b:Bank)
RETURN a, tx, b

-- GOOD: if truly independent, use UNION or separate queries

Limit Early, Filter Early

-- Push WHERE as early as possible
MATCH (c:Customer)
WHERE c.nationality = $country    -- filter before traversal
MATCH (c)-[:HAS_ACCOUNT]->(a:Account)-[:PERFORM]->(tx:Transaction)
WHERE tx.amount > $threshold
RETURN c, a, tx

Fraud-Domain Patterns

Shared PII Detection (Synthetic Identity)

MATCH (c1:Customer)-[:HAS_EMAIL|HAS_PHONE|HAS_SSN]->(pii)<-[:HAS_EMAIL|HAS_PHONE|HAS_SSN]-(c2:Customer)
WHERE c1 <> c2
WITH c1, c2, collect(pii) AS sharedPII, count(pii) AS sharedCount
WHERE sharedCount >= 2
RETURN c1.customerId, c2.customerId, sharedCount,
       [p IN sharedPII | labels(p)[0]] AS sharedTypes

Transaction Ring Detection

-- Circular fund flow (Neo4j 5.9+ quantified path patterns)
MATCH path = (a:Account)-[:PERFORM]->(first_tx)
  ((tx_i)-[:BENEFITS_TO]->(a_i)-[:PERFORM]->(tx_j)
   WHERE tx_i.date < tx_j.date)*
  (last_tx)-[:BENEFITS_TO]->(a)
WHERE size(apoc.coll.toSet([a] + a_i)) = size([a] + a_i)
RETURN path

Fund Flow / Money Trail

-- Trace where money went from a specific account
MATCH (source:Account {accountNumber: $accNum})
MATCH path = (source)-[:PERFORM]->(tx:Transaction)-[:BENEFITS_TO]->(dest)
RETURN dest, tx.amount, tx.date, labels(dest)[0] AS destType
ORDER BY tx.date DESC

Network Expansion (1-hop, 2-hop)

-- All entities within 2 hops of a customer
MATCH path = (c:Customer {customerId: $customerId})-[*1..2]-(connected)
RETURN path

Community Detection (with GDS)

-- Project graph
CALL gds.graph.project('fraud-network', 'Customer',
  {LINKED: {type: 'LINKED', orientation: 'UNDIRECTED'}})

-- Run Weakly Connected Components
CALL gds.wcc.stream('fraud-network')
YIELD nodeId, componentId
WITH componentId, collect(gds.util.asNode(nodeId).customerId) AS members
WHERE size(members) > 1
RETURN componentId, members, size(members) AS clusterSize
ORDER BY clusterSize DESC

-- Clean up projection
CALL gds.graph.drop('fraud-network')

Centrality (PageRank / Betweenness)

CALL gds.pageRank.stream('fraud-network')
YIELD nodeId, score
RETURN gds.util.asNode(nodeId).customerId AS customerId, score
ORDER BY score DESC
LIMIT 20

Neo4j 5+ Features

Element IDs (replaces internal integer IDs)

-- Neo4j 5+: use elementId() instead of id()
MATCH (n:Customer)
WHERE elementId(n) = $elementId
RETURN n

-- In Bloom scene actions
MATCH (n) WHERE elementId(n) IN $nodes RETURN n

Quantified Path Patterns (5.9+)

-- Match paths of variable length with inline predicates
MATCH path = (a:Account)
  (()-[:PERFORM]->(tx:Transaction)-[:BENEFITS_TO]->()
   WHERE tx.amount > 1000){2,5}
  (b:Account)
RETURN path

Temporal Types

-- datetime(), date(), time(), duration()
CREATE (tx:Transaction {
  timestamp: datetime(),
  settlementDate: date('2024-03-15'),
  processingTime: duration('PT2H30M')
})

-- Filtering by date range
MATCH (tx:Transaction)
WHERE tx.timestamp >= datetime($startDate)
  AND tx.timestamp <= datetime($endDate)
RETURN tx

-- Date arithmetic
MATCH (tx:Transaction)
WHERE tx.timestamp >= datetime() - duration({days: 30})
RETURN tx

COUNT {} and EXISTS {} Subqueries

-- Count subquery (Neo4j 5+)
MATCH (c:Customer)
WHERE COUNT {
  (c)-[:HAS_ACCOUNT]->(a:Account)-[:PERFORM]->(tx:Transaction)
  WHERE tx.amount > 10000
} > 5
RETURN c

-- EXISTS subquery
MATCH (c:Customer)
WHERE EXISTS {
  (c)-[:HAS_EMAIL]->(e:Email)<-[:HAS_EMAIL]-(other:Customer)
  WHERE c <> other
}
RETURN c

Anti-Patterns

1. Collecting without DISTINCT

When multiple OPTIONAL MATCH clauses create cartesian products between collected lists:

-- BAD: emails × phones duplicates
MATCH (c:Customer)
OPTIONAL MATCH (c)-[:HAS_EMAIL]->(e:Email)
OPTIONAL MATCH (c)-[:HAS_PHONE]->(p:Phone)
RETURN c, collect(e) AS emails, collect(p) AS phones

-- GOOD: use DISTINCT
RETURN c, collect(DISTINCT e) AS emails, collect(DISTINCT p) AS phones

2. MERGE on Too Many Properties

-- BAD: if any property differs, creates duplicate
MERGE (c:Customer {customerId: $id, firstName: $first, lastName: $last})

-- GOOD: merge on unique key, set other props
MERGE (c:Customer {customerId: $id})
ON CREATE SET c.firstName = $first, c.lastName = $last

3. Unbounded Variable-Length Paths

-- BAD: can explode on connected graphs
MATCH path = (a)-[*]->(b) RETURN path

-- GOOD: always bound the length
MATCH path = (a)-[*1..5]->(b) RETURN path

4. Using Labels in WHERE Instead of MATCH

-- BAD: scans all nodes then filters
MATCH (n) WHERE 'Customer' IN labels(n) RETURN n

-- GOOD: label in MATCH uses label index
MATCH (n:Customer) RETURN n

5. String Concatenation for Dynamic Queries

-- BAD: no plan caching, injection risk
"MATCH (n {id: '" + userId + "'}) RETURN n"

-- GOOD: use parameters
MATCH (n {id: $userId}) RETURN n

6. Loading Too Much Data

-- BAD: returns everything
MATCH (n) RETURN n

-- GOOD: limit and paginate
MATCH (n:Customer)
RETURN n
ORDER BY n.customerId
SKIP $offset
LIMIT $pageSize