Warm Up Your Neo4j Database with APOC

Summary

Warming up a Neo4j database adds nodes and relationships to the database’s page cache. If you are not warming up your database, query performance will suffer until the cache is built up over time during normal usage. Here are the steps to warm up a database, including all properties.

  1. Install APOC
  2. Execute the following command before issuing your queries:
CALL apoc.warmup.run(true, true)

Including the two boolean arguments will ensure that all graph properties are warmed into page cache. This will lead to a longer warmup, but for queries that rely heavily on graph properties it will yield substantial performance improvements.

Why Warm a Graph?

As a native graph database, Neo4j provides index-free adjacency whereby each node stores direct pointers to its related nodes. When traversing a graph, say through depth-first search, these direct pointers allow for graph traversals in constant time. By contrast, non-native graph databases would need to make successive O(log(n)) global index lookups at each hop between nodes. This performance benefit is especially profound when nodes and relationships are in memory in the database’s page cache.

In many Neo4j use cases, the database will enjoy high uptime and regular caching as it is used. However in applications where databases are built (or re-built) frequently, this caching is not done until the first queries are run on the database. If many inexpensive queries will be run on the database, incremental page caching may be tolerable. On the other hand, if the graph database primarily services expensive queries, then a cold database can cause a dramatic slowdown.

Include Properties in the Warmup

Neo4j provides a blog post advocating for warming up the page cache using APOC, a library of stored procedures. However, the post does not include a potentially crucial detail: there are two optional arguments to the warmup procedure that cache node and relationship properties. When queries traverse a graph informed by node or relationship properties, these optional arguments can improve performance drastically.

Until recently, the option to load a node’s properties in the warmup was not mentioned in the APOC documentation. Viewing APOC’s source code reveals the relevant arguments to do so. Thanks to the APOC team for revising the documentation to include a mention of these optional arguments!