Neo4j Cypher Guide

Critical Sorting Rule

ALWAYS filter NULL values when sorting:

// WRONG - May include null values
MATCH (n:Node)
RETURN n.name, n.value
ORDER BY n.value

// CORRECT - Filter nulls before sorting
MATCH (n:Node)
WHERE n.value IS NOT NULL
RETURN n.name, n.value
ORDER BY n.value

Query Pattern Selection Guide

For Simple Queries

Use standard Cypher patterns with modern syntax:

MATCH (n:Label {property: value})
WHERE n.otherProperty IS :: STRING
RETURN n

For Variable-Length Paths

Consider Quantified Path Patterns (QPP) for better performance:

// Instead of: MATCH (a)-[*1..5]->(b)
// Use: MATCH (a)-[]-{1,5}(b)

// With filtering:
MATCH (a)((n WHERE n.active)-[]->(m)){1,5}(b)

For Aggregations

Use COUNT{}, EXISTS{}, and COLLECT{} subqueries:

MATCH (p:Person)
WHERE count{(p)-[:KNOWS]->()} > 5
RETURN p.name, 
       exists{(p)-[:MANAGES]->()} AS isManager

For Complex Read Operations

Use CALL subqueries for sophisticated data retrieval:

MATCH (d:Department)
CALL (d) {
  MATCH (d)<-[:WORKS_IN]-(p:Person)
  WHERE p.salary IS NOT NULL  // Filter nulls
  WITH p ORDER BY p.salary DESC
  LIMIT 3
  RETURN collect(p.name) AS topEarners
}
RETURN d.name, topEarners

Common Query Transformations

Counting Patterns

// Old: RETURN size((n)-[]->())
// Modern: RETURN count{(n)-[]->()}

Checking Existence

// Old: WHERE exists((n)-[:REL]->())
// Modern: WHERE EXISTS {MATCH (n)-[:REL]->()}
// Also valid: WHERE exists{(n)-[:REL]->()}

Element IDs

// Old: WHERE id(n) = 123
// Modern: WHERE elementId(n) = "4:abc123:456"
// Note: elementId returns a string, not integer

Sorting with Null Handling

// Always add null check
MATCH (n:Node)
WHERE n.sortProperty IS NOT NULL
RETURN n
ORDER BY n.sortProperty

// Or use NULLS LAST
MATCH (n:Node)
RETURN n
ORDER BY n.sortProperty NULLS LAST

When to Load Reference Documentation

Load the appropriate reference file when:

references/deprecated-syntax.md

• Migrating queries from older Neo4j versions
• Encountering syntax errors with legacy queries
• Need complete list of removed/deprecated features

references/subqueries.md

• Working with CALL subqueries for reads
• Using COLLECT or COUNT subqueries
• Handling complex aggregations
• Implementing sorting with null filtering

references/qpp.md

• Optimizing variable-length path queries
• Need early filtering during traversal
• Working with paths longer than 3-4 hops
• Complex pattern matching requirements

references/write-patterns.md

• MERGE-based node and relationship creation
• ON CREATE SET / ON MATCH SET guards
• Schema initialization (constraints, fulltext indexes)
• Provenance tracking with source_papers arrays
• Alias management patterns
• Dedup candidate flagging
• Node merge operations (APOC and non-APOC)

Query Generation Checklist

Before finalizing any generated query:

1. ✅ No deprecated functions (id, btree indexes, etc.)
2. ✅ Explicit grouping for aggregations
3. ✅ NULL filters for all sorted properties
4. ✅ Appropriate subquery patterns for reads
5. ✅ Consider QPP for paths with filtering needs
6. ✅ Use COUNT{} instead of size() for pattern counting
7. ✅ Variable scope clauses in CALL subqueries
8. ✅ Unique variable names for relationships

Error Resolution Patterns

"Implicit grouping key" errors

// Problem: RETURN n.prop, count(*) + n.other
// Solution: WITH n.prop AS prop, n.other AS other, count(*) AS cnt
//          RETURN prop, cnt + other

"id() function not found"

// Use elementId() but note it returns a string, not integer

"Repeated variable" errors

// Problem: MATCH (a)-[r*]->(), (b)-[r*]->()
// Solution: MATCH (a)-[r1*]->(), (b)-[r2*]->()

Performance Tips

1. Start with indexed properties - Always anchor patterns with indexed lookups
2. Filter early in QPP - Apply WHERE clauses within the pattern
3. Filter nulls before sorting - Prevent unexpected results and improve performance
4. Limit expansion depth - Use reasonable upper bounds in quantifiers
5. Use EXISTS for existence checks - More efficient than counting
6. Profile queries - Use PROFILE to identify bottlenecks

Modern Cypher Features

Label Expressions

WHERE n:Label1|Label2  // OR
WHERE n:Label1&Label2  // AND
WHERE n:!Archived      // NOT

Type Predicates

WHERE n.prop IS :: STRING
WHERE n.value IS :: INTEGER NOT NULL
WHERE n.data IS :: LIST<STRING>

Subquery Patterns for Reads

• COUNT{} - Count patterns efficiently
• EXISTS{} - Check pattern existence
• COLLECT{} - Collect complex results
• CALL{} - Execute subqueries for complex reads

Quantified Path Patterns

• Inline filtering during traversal
• Access to nodes and relationships in patterns
• Significant performance improvements (up to 1000x)
• Support for complex, multi-hop patterns

Always prefer modern syntax patterns for better performance and maintainability.