neo4j

neo4j Best Practices

This document outlines the mandatory guidelines for developing with Neo4j. Adhering to these rules ensures our Cypher queries are performant, secure, and maintainable.

1. Code Organization and Structure

1.1. Standardize Naming Conventions

Consistency is paramount. Use the recommended casing for all identifiers to prevent subtle bugs due to Cypher's case-sensitivity.

• Node Labels: PascalCase
• Relationship Types: UPPER_SNAKE_CASE
• Property Keys: camelCase
• Variables: camelCase

❌ BAD:

MATCH (p:person)-[r:friend_of]->(f:Friend)
WHERE p.first_name = 'Alice'
RETURN f.last_name

✅ GOOD:

MATCH (p:Person)-[r:FRIEND_OF]->(f:Person)
WHERE p.firstName = 'Alice'
RETURN f.lastName

1.2. Escape Special Characters Judiciously

Only use backticks (`) when an identifier must contain special characters, spaces, or start with a non-alphabetic character. Avoid them otherwise to keep queries clean.

❌ BAD:

MATCH (`my node`:`User Label`)
WHERE `my node`.`user-id` = 123
RETURN `my node`.`user-name`

✅ GOOD:

MATCH (u:User)
WHERE u.userId = 123
RETURN u.userName

If a special character is truly unavoidable:

MATCH (n:`1stUser`)
WHERE n.`user-id` = 123
RETURN n.userName

1.3. Always Use Cypher 25

New features and performance improvements are exclusively added to Cypher 25. Avoid older versions like 5.x.

2. Data Modeling

2.1. Design for Query-Ability

Model your graph around the most common traversals and business questions. Prioritize relationships that directly answer real-world queries over mimicking relational schemas.

❌ BAD: (Relational thinking, too many properties on nodes, generic relationships)

// Modeling a "User" and their "Address" as separate nodes, but linking them generically
CREATE (u:User {id: 'u1', name: 'Alice'})
CREATE (a:Address {id: 'a1', street: '123 Main St', city: 'Anytown'})
CREATE (u)-[:HAS]->(a) // Generic relationship