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.haltOnError​

  • Default: false
  • Reloadable: no

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