Add clarification that query caches are part of the JVM heap allocation by renetapopova · Pull Request #1673 · neo4j/docs-cypher

renetapopova · 2026-09-29T11:52:30Z

renetapopova · 2026-09-29T12:44:28Z

Hey @JPryce-Aklundh, could you please take a look at this? I am not sure why it shows a conflict.
When I tried to rebase the branch, I got:

➜  docs-cypher git:(dev-query-caches) git rebase dev
Current branch dev-query-caches is up to date.
error: refs/remotes/upstream/add-syntax-snippets-2026.09 does not point to a valid object!

Relates to: neo4j/docs-cypher#1673

…t database or DBMS

henriknyman · 2026-10-09T09:33:44Z

-
-Query caches may consume a lot of memory, especially when running many active databases.
-To tackle this and improve predictability on memory consumption, you can configure the DBMS to use only one set of caches for all databases.
+By default, the set of query caches is *per database*, which means that the memory allocated for query caches for each database is part of the JVM heap of that database.


"which means that the memory allocated for query caches for each database is part of the JVM heap of that database."

There is not really anything like "a part of the JVM heap of that database". I think it may be unnecessary to mention this part about the heap, or alternatively just have a generic note "query caches are allocated on the JVM heap" somewhere.

The request was to explicitly state that query caches are part of the JVM heap, and given that they are per database, I assumed that the memory allocated for query caches for each database is part of the JVM heap for that database.
If they are not part of the JVM heap for each of the databases, that means that the diagram here is not correct https://github.com/neo4j/docs-operations/pull/3330/changes.

Ok, as a reference to the diagram I guess it could work conceptually.

Is the diagram correct or should I replace it with something like

henriknyman · 2026-10-09T09:40:17Z

+For more information, see link:{neo4j-docs-base-uri}/operations-manual/current/performance/memory-configuration/[Operations Manual -> Memory configuration].
+
+Query caches can use significant memory, especially when running many active databases.
+The amount of memory consumed by query caches depends on the available heap size, the nature of the queries, and the number of unique queries executed. +


"depends on the available heap size" is incorrect, the amount of memory consumed never depends on the available heap size.
What I meant when we chatted about this was that if query cache memory usage is even a problem to worry about depends on the available heap size. E.g. if you are running the smallest Aura Free instance the heap usage of the query cache could be a problem (if some of the other conditions also apply), but if you are running a larger instance with a larger heap you most likely never have to worry about query cache size since it is such a small fraction of the total heap size.

I am not sure I understand you. "depends on the available heap size, the nature of the queries, and the number of unique queries executed." means exactly what you explain. For example, if you don't have enough heap size, and you run many unique queries, you might have a problem.

I'll try to rewrite it.

henriknyman · 2026-10-09T09:46:16Z

+In many cases, executing the queries itself consumes much more memory, as heap usage can scale with the amount of data.
+This is particularly evident in multi-tenant scenarios where numerous databases run workloads of programmatically generated queries without appropriate parameterization.


I think the ordering of these two sentences introduces confusion. The second statement is referring to the earlier section of the conditions when query cache memory usage can become a problem and should come first.
The first statement is a general principle and a reason why query caches is not the first place to consider when tuning memory usage: heap usage of executing queries can scale with the amount of data, but the heap usage of query caches cannot.

henriknyman · 2026-10-09T09:55:37Z

+The amount of memory consumed by query caches depends on the available heap size, the nature of the queries, and the number of unique queries executed. +
+In many cases, executing the queries itself consumes much more memory, as heap usage can scale with the amount of data.
+This is particularly evident in multi-tenant scenarios where numerous databases run workloads of programmatically generated queries without appropriate parameterization.
+To tackle this and improve predictability of memory consumption, you can configure the DBMS to use a single set of caches for all databases.


We could clarify this with "improve predictability of memory consumption in multi-tenant use-cases ...", as with a single database or even in most use-cases with multiple databases used for data federation (composite database) this setting doesn't do anything useful.
The difference between a federated and a multi-tenancy usecase is that the latter has many copies of the "same" database (same schema/data model) running the same queries.

henriknyman · 2026-10-09T10:03:02Z

+By default, the set of query caches is *per database*, which means that the memory allocated for query caches for each database is part of the JVM heap of that database.
+For more information, see link:{neo4j-docs-base-uri}/operations-manual/current/performance/memory-configuration/[Operations Manual -> Memory configuration].
+
+Query caches can use significant memory, especially when running many active databases.


Maybe it is more helpful to state that "Query caches can use significant memory in certain conditions" and then go on to list the conditions? This phrasing with "especially" suggests to me that query cache memory usage is something I should be worried about when in many use cases I don't need to.

This sentence existed before. I just changed "a lot of" with "significant".

Yes I know. It was not about your specific change but mostly that I don't think what existed before was very helpful.

renetapopova · 2026-10-09T13:29:55Z

-
-Query caches may consume a lot of memory, especially when running many active databases.
-To tackle this and improve predictability on memory consumption, you can configure the DBMS to use only one set of caches for all databases.
+By default, the set of query caches is *per database*, which means that the memory allocated for query caches for each database is part of the JVM heap of that database.


Suggested change

By default, the set of query caches is *per database*, which means that the memory allocated for query caches for each database is part of the JVM heap of that database.

By default, the set of query caches is *per database*, and their memory is allocated on the JVM heap.

neo4j-docops-agent · 2026-10-09T13:57:21Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-cypher-1673.surge.sh

Updated pages:

Query caches

renetapopova requested a review from JPryce-Aklundh September 29, 2026 11:52

renetapopova added cherry-pick-to-cypher-25 cherry-pick-to-cypher-5 labels Sep 29, 2026

renetapopova changed the title ~~Dev query caches~~ Add clarification that query caches are part of the JVM heap allocation Sep 29, 2026

renetapopova closed this Sep 29, 2026

renetapopova force-pushed the dev-query-caches branch from 18eba41 to e19e9ca Compare September 29, 2026 14:07

renetapopova reopened this Sep 29, 2026

renetapopova commented Sep 29, 2026

View reviewed changes

Comment thread modules/ROOT/pages/planning-and-tuning/caching.adoc

renetapopova mentioned this pull request Sep 29, 2026

Improve doc related to query cache and memory allocation neo4j/docs-operations#3315

Merged

JPryce-Aklundh approved these changes Sep 30, 2026

View reviewed changes

renetapopova added a commit to neo4j/docs-operations that referenced this pull request Oct 5, 2026

Improve doc related to query cache and memory allocation (#3315)

7670d1b

Relates to: neo4j/docs-cypher#1673

renetapopova mentioned this pull request Oct 5, 2026

Improve doc related to query cache and memory allocation (#3315) neo4j/docs-operations#3329

Merged

renetapopova commented Oct 5, 2026

View reviewed changes