🧠 Neo4j Quirks: What You Should Know Before Going Graph

Intro

Neo4j is a powerful graph database, but like any tool, it comes with its own set of quirks—things that can trip up even experienced developers if they're expecting traditional RDBMS or NoSQL behavior. This post summarizes key “gotchas” you should be aware of when adopting Neo4j in real-world applications.

---

1. Relationship Directions Matter (Even When You Think They Don’t)

Neo4j relationships are directed:
(a)-[:FRIENDS_WITH]->(b) is not the same as (b)-[:FRIENDS_WITH]->(a)

Quirk:
When querying, you must match the direction unless explicitly saying otherwise:

MATCH (a)-[:FRIENDS_WITH]-(b) // direction-agnostic

Real-World Impact:
Queries may silently return nothing if you match the wrong direction.

---

2. Large Fanouts Can Kill Performance

What It Means:
A single node with thousands (or millions) of outgoing relationships becomes a performance bottleneck.

Quirk:
Even with indexes, traversals involving large fanouts are slow unless carefully limited.

Tip:
Avoid "celebrity nodes" or batch them with pagination:

MATCH (u:User)-[:FOLLOWS]->(f:User)
WHERE u.name = "Ganapathy"
RETURN f SKIP 0 LIMIT 100

---

3. Indexing Is Not as Granular as SQL

Quirk:
Neo4j indexes work only on node properties, not relationship properties or full-path matches.

Example:
You can't index a path like (a)-[:KNOWS]->(b).

Tip:
Use composite indexes or materialize paths into nodes if needed.

---

4. Orphaned Relationships Are Impossible by Design

Quirk:
You can’t create a relationship without linking it to two nodes.

Good News:
This enforces graph integrity.

Bad News:
You need to clean up nodes and relationships together:

MATCH (a)-[r]->()
DELETE r, a

---

5. Aggregations and COLLECT Can Confuse New Users

Example:

MATCH (p:Person)-[:KNOWS]->(f)
RETURN p.name, COLLECT(f.name)

Quirk:
The COLLECT() function creates lists, but mixing it with non-grouped values can lead to errors or misinterpretation.

Tip:
Always think in terms of how the result should group—Neo4j isn’t a traditional GROUP BY system.

---

6. No Strong Schema Enforcement

Quirk:
Neo4j is schema-optional—labels and property types are not strictly enforced.

Consequence:
You can accidentally insert inconsistent data (e.g., age as string vs number).

Mitigation:
Use CONSTRAINT and ASSERT where possible:

CREATE CONSTRAINT ON (p:Person) ASSERT p.id IS UNIQUE

---

7. Transactions Can Be Subtle in Cypher

Quirk:
Using the browser or driver may hide transactional nuances.

Gotcha Example:
Running CREATE in one query and expecting it to exist in a separate query in the same session may fail if autocommit isn't used.

Fix:
Wrap related operations in a transaction when using the driver:

tx := session.BeginTransaction()
tx.Run(...)
// commit explicitly

---

8. Testing and Cleanup Require Thoughtful Design

Quirk:
Neo4j's test environments don't reset easily unless you clean manually.

Tip:
Create a :TestRun node that relates to all temporary data, and clean it up:

MATCH (:TestRun)-[*]->(n)
DETACH DELETE n

---

✅ Final Thoughts

Neo4j is expressive and great for certain data models—but it’s not magic. Understanding its quirks early helps avoid performance and correctness pitfalls.

Recommended Next Steps:

• Monitor with APOC

• Use EXPLAIN / PROFILE for every query

• Design your data model with traversal in mind