The heap is a critical memory area where Neo4j stores temporary data during query execution and transaction processing.
In this lesson, you’ll learn:
Understanding heap memory usage in Neo4j
How to monitor heap memory
Identifying when to scale your instance
Understanding Heap Memory
Heap memory is where Neo4j stores data during query execution and transaction processing. When you execute a read query, intermediate results accumulate in the heap until they’re ready to stream back to your application. Complex queries with many operators consume more heap memory than simple queries.
When you write data to Neo4j, the database holds changes in memory to maintain ACID guarantees. The entire unit of work stays in the heap until it’s complete and ready to write to the transaction log. This prevents transactions from accumulating too many changes in memory before commit.
The heap also stores transaction state, cached query plans, and internal data structures. The memory you need depends on your query complexity, number of concurrent queries, transaction size, and working set size.
ACID Compliance
Neo4j is an ACID compliant database. This is a key feature that helps databases maintain data integrity and consistency.
The acronym stands for:
Atomicity - All operations in a transaction succeed or every operation is rolled back.
Consistency - On the completion of a transaction, the database is structurally sound.
Isolation - Transactions do not contend with one another. Contentious access to data is moderated by the database so that transactions appear to run sequentially.
Durability - The results of applying a transaction are permanent, even in the presence of failures.
Monitoring Heap Memory
The Heap Memory metric shows the percentage of configured heap memory in use. The expected baseline is 20-50% during regular operations. Temporary spikes to 60-80% during complex queries are normal and healthy.
The key indicator of problems is sustained high usage above 80%. Short spikes are acceptable, but if heap usage stays above 80% for extended periods, you have memory pressure that will cause increased garbage collection, slower queries, and risk of Out of Memory errors.
Understanding heap spikes
Occasional spikes to 70-80% are normal during complex queries. The concern is sustained high usage, not temporary peaks.
Mitigating Heap Memory Issues
When you see sustained heap usage above 80%, start by optimizing your queries. Use LIMIT clauses to avoid returning large result sets. Break complex queries into smaller operations. Use CALL { } IN TRANSACTIONS OF 1000 ROWS for batch operations to process data in smaller chunks.
Transaction management is equally important. Keep transactions short-lived and commit them promptly. Long-running transactions hold memory and prevent the garbage collector from reclaiming space. Stream results when possible using your Neo4j driver instead of collecting all results in memory.
When to Scale Your Instance
After optimizing your queries and transactions, you may still see sustained heap usage above 80%. This indicates your workload legitimately requires more memory than your current instance provides. Scaling is the right choice when optimization efforts have been exhausted.
Scale your instance when heap usage remains consistently above 80% despite query optimization. You should also scale if you’ve optimized queries but they still fail with Out of Memory errors during normal operations. Performance degradation that persists after optimization is another clear indicator.
However, always optimize first before scaling. Inefficient queries will consume any amount of memory you provide. If you scale without fixing query issues, you’ll only delay the problem and waste resources.
Optimizing queries
In the next module you will learn how to optimized query using use EXPLAIN and PROFILE to verify your queries are efficient before scaling.
Lesson Summary
In this lesson, you learned about analyzing memory usage in Neo4j Aura, including how to monitor different memory components and optimize for better memory efficiency.
In the next lesson, you will learn about database store size management and optimization.
