For AI agents: the complete documentation index is at llms.txt. Every page is also available as markdown by appending .md to its URL, or by sending an Accept: text/markdown request header.

Materialized views

These settings control materialized view SQL support and the background refresh job. Materialized views refresh on a dedicated worker pool sized by mat.view.refresh.worker.count; 0 disables refresh.

To cap the native memory a single refresh may allocate, see cairo.mat.view.refresh.memory.limit.bytes.

cairo.mat.view.enabled​

  • Default: true
  • Reloadable: no

Enables or disables SQL support and the refresh job for materialized views.

cairo.mat.view.max.refresh.retries​

  • Default: 10
  • Reloadable: yes

Maximum number of immediate retries within a single refresh attempt. A retry happens when the base table changes structurally during the refresh, when a refresh step produces an oversized transaction, or when a step fails with an out-of-memory error, including a breach of the refresh memory limit. Retries after an oversized transaction or an out-of-memory error shrink the refresh interval step; a retry after a structural change recompiles the view with the same step, and if it keeps failing the refresh is queued again. Once the out-of-memory retries are exhausted or the step cannot shrink further, the error propagates and the deferred retries governed by cairo.mat.view.refresh.busy.retry.limit take over.

cairo.mat.view.parallel.sql.enabled​

  • Default: true
  • Reloadable: no

When disabled, SQL executed by the materialized view refresh job always runs single-threaded.

cairo.mat.view.refresh.busy.retry.limit​

  • Default: 10
  • Reloadable: no

Maximum number of deferred retries after an incremental or scheduled period refresh fails with a transient error. If all retries fail, the view is invalidated. A successful refresh resets the counter; 0 disables deferred retries.

Transient errors include a busy base table or view and out-of-memory errors, including breaches of the refresh memory limit. Full refreshes and user-requested REFRESH ... RANGE FROM ... TO ... do not use these deferred retries.

cairo.mat.view.refresh.busy.retry.timeout​

  • Default: 1000
  • Reloadable: no

Delay in milliseconds before a deferred retry for an incremental or scheduled period refresh. The retry is timer-driven and does not block a refresh worker. The deprecated cairo.mat.view.refresh.oom.retry.timeout key is accepted but has no effect; deferred out-of-memory retries use this backoff.

mat.view.refresh.worker.affinity​

  • Default: none
  • Reloadable: no

Comma-separated list of numerical CPU core indexes, one per refresh worker.

mat.view.refresh.worker.count​

  • Default: 2 on hosts with up to 8 CPU cores, 3 on up to 32 cores, 4 on larger hosts. This is the same CPU-based default as wal.apply.worker.count; setting that key does not change this one.
  • Reloadable: no

Number of dedicated worker threads assigned to refresh materialized views. A value of 0 disables materialized view refresh: CREATE MATERIALIZED VIEW still succeeds, but nothing refreshes the view. Live views use their own pool, sized by live.view.refresh.worker.count.

mat.view.refresh.worker.fiber.enabled​

  • Default: true
  • Reloadable: no

Runs the materialized view refresh pool in Fiber mode, where work can suspend and release its worker instead of holding it until it finishes. Setting this to false puts the pool in legacy mode.

Unlike the pools that serve user queries, this one is not a prerequisite for QuestDB Enterprise resource groups, because materialized view refresh runs outside them.

mat.view.refresh.worker.haltOnError​

  • Default: false
  • Reloadable: no

Flag that indicates if the worker thread must stop when an unexpected error occurs.