Query plan cache does not auto‑invalidate after schema changes

Resolution

In current stable versions of Neo4j (including 5.x), the query plan cache does not automatically invalidate when indexes, constraints, or labels are modified. To ensure queries utilize the latest schema state, you must manually clear the cache using the following command:

CALL dbms.clearQueryCache();

Alternatively, a full restart of the Neo4j instance will clear the cache, though this is generally less desirable than the targeted procedure call.

Technical Explanation

Neo4j compiles Cypher queries into execution plans to avoid the overhead of repeated planning. These plans are stored in a cache. Because the cache is not linked to a schema-change trigger, a query that was planned before a new index was created will continue to use the old plan (e.g., performing a NodeByLabelScan instead of a NodeIndexSeek).

Behavioral Facts vs. Assumptions

• Confirmed: Stale plans typically lead to performance degradation (suboptimal execution) rather than incorrect data results.
• Confirmed: There is currently no configuration setting for selective invalidation (e.g., invalidating only plans affected by a specific index).
• Assumption: While future releases may automate this process, it is not a feature of the current stable API.

Verification Steps

To verify if a stale plan is affecting your performance, follow this sequence:

1. Profile the current plan: Run PROFILE on your target query to see if it is ignoring a newly created index.
2. Check cache stats: Use CALL dbms.queryCacheStats() to observe the current cache state.
3. Clear and re-test: Execute CALL dbms.clearQueryCache() and run the PROFILE command again. If the execution plan changes to use the new index, the cache was indeed the bottleneck.

Diagnostic Requirement

To provide a more specific recommendation regarding throughput impact, please specify your current Neo4j version and average queries-per-second (QPS). Clearing the cache in extremely high-traffic environments can cause a temporary CPU spike as the system re-plans all active queries simultaneously.