How can I adjust heap size (memory requirements) for my persistent queries?

This guide covers tuning heap size for Persistent Queries (PQs) and Code Studios. For system service memory (DIS, TDCP, controller, tailer, etc.), see Process memory configuration. See Finding errors for information on how to find errors in the logs.

The tables generated by the performance overview methods let you look at how much memory a query is using. If the query/worker is using only a small percentage of its max heap size, you should reclaim some of that memory for other queries. On the other hand, if a query is requiring almost all the memory allocated, you should increase the heap size to prevent underperformance or failure.

If you are investigating a specific query and have concerns about heap, we recommend turning on detailed GC logging in the Persistent Query Editor, under Advanced Options (enabled by default). You can also turn on detailed GC logging when you create a new console by selecting Advanced Options and selecting Enable detailed GC logging. This creates additional lines in the Process Event Log, which you can use to analyze performance or failures.

Check current memory usage

Before changing heap, determine how much memory the query is actually using.

Option 1 — ProcessMetricsLogCoreV2 (Core+ workers): Enable this internal table by adding -DIrisLogDefaults.writeDatabaseProcessMetrics=true under Extra JVM Arguments in the PQ editor's Advanced Options. Then query from a console:

For a full PQ memory dashboard, see Monitor query performance.

Option 2 — Persistent Query State Log: The PersistentQueryStateLog records HeapSizeInGB for each PQ configuration. Compare the configured heap to observed usage in ProcessMetricsLogCoreV2 to identify over- or under-allocated queries.

Decide whether to change heap

  • Usage consistently below 50%: The query is over-allocated. Reduce heap to reclaim resources for other queries or services — the dispatcher enforces a total heap budget across all workers.
  • Usage regularly above 80–90%: The JVM is GC-ing frequently to stay within bounds. Increase heap to prevent performance degradation or OutOfMemoryError.
  • Frequent GC but low heap usage: Enable detailed GC logging (see below) to distinguish between normal collection and excessive GC pressure.

Change the heap size

Open the PQ or Code Studio editor:

  1. Go to Settings (or Advanced Options).
  2. Adjust Heap Size (GB) to the new value.
  3. Save and restart the query.

For the dispatcher-level limits that cap what any single worker can request, see Worker heap size.

Enable detailed GC logging

To add GC events to the Process Event Log, open the PQ or Code Studio editor and select Advanced Options → Enable detailed GC logging. GC log entries appear in the ProcessEventLog table and can be filtered by ProcessInfoId. Frequent GC activity — especially short intervals between full GCs — indicates the heap should be increased.