Neo4j’s reliance on in-memory data management makes swap largely irrelevant and potentially counterproductive in dedicated environments. By ensuring sufficient RAM and disabling or minimising swap, organisations may optimise Neo4j’s performance and avoid unnecessary operational concerns. For mixed-use systems or constrained environments, careful memory planning and monitoring are critical.

Problem Statement

Running Neo4j on Linux VMs, may require swap-memory optimisations, largely due to conflicting operational policies or concerns about swap usage, especially in memory-intensive environments. Misconfigured swap settings may lead to unintended performance issues, such as excessive paging, memory contention, or suboptimal database operations.

Impact

Improper swap configuration on systems running Neo4j can result in:

1. Increased Query Latency: Unpredictable delays due to pages being swapped out of memory.

2. Memory Contention: Neo4j’s memory management may conflict with the operating system’s swapping behaviour.

3. Resource Mismanagement: Organisations monitoring swap usage may be alarmed by high swap utilisation, even when it does not indicate active swapping.

4. Potential Data Processing Issues: Critical pages used by Neo4j may be swapped to disk, impacting real-time performance.

 

Discussion

Neo4j is primarily an in-memory database, relying on efficient memory management to handle graph data. It uses a page cache to store frequently accessed data and ensures critical database operations stay memory-resident.

OS swap paging is transparent to Neo4j, which may result in situations where a query has no page-cache faults (misses) yet none of the pages the query needed were actually in RAM. There may then be another query that showed 50% of page-cache accesses were misses, but executes faster because the page hits were actually in RAM. In such case, we would have the opposite trend in the results (more page faults goes faster), which may seem counter-intuitive. In essence, there is no expected benefit from having memory swap on a machine running an in-memory database. If Neo4j requires paging out from cache, then it will do so. Note that in general, Neo4j’s BlockStore format (introduced in version 5.x) performs much better compared to RecordStore (version 4.x)

1. In-memory Nature of Neo4j:

• Neo4j requires sufficient RAM to store both the graph and associated page cache.

• OS-level swapping can interfere with Neo4j’s internal memory management.

2. Swap Usage Insights:

• Swap was historically used in systems where memory was a limiting factor.

• Modern systems often allocate small swap spaces relative to total RAM. High swap usage does not always equate to active swapping of memory pages.

3. OS Swapping Behaviour:

• Swapping is transparent to Neo4j and can lead to scenarios where queries show no page faults but suffer from delays due to critical pages being swapped out.

• Aggressive swap policies (e.g., high swappiness) can exacerbate these issues, especially in memory-constrained environments.

4. Customer Experiences:

• Customer cases demonstrate that excessive reliance on swap or misconfigured swappiness can lead to operational concerns. Customers often monitor swap spikes without realising their limited relevance to Neo4j’s performance.

Resolution

To ensure optimal performance for Neo4j on Linux VMs, follow these recommendations:

1. Disable Swap or minimise Swappiness:

• If the machine is dedicated to running Neo4j, it is best to disable swap entirely or set the swappiness parameter to 0:

sysctl vm.swappiness=0 (this configuration may be persisted by editing /etc/sysctl.conf)

2. Ensure Sufficient RAM:

• Allocate enough physical memory to host the entire graph and additional system processes. The recommended setup includes:

• Adequate memory for the Neo4j page cache.

• Additional headroom for the operating system and other services.

3. Monitor Memory Usage:

• Examine memory pressure metrics like vmstat si (swap in) and so (swap out) rather than absolute swap utilisation.

Further reading about Neo4j memory tuning can be found here.