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.

Live views

These settings control live view SQL support, the refresh worker pool, and the background refresh job that maintains live views incrementally. For a conceptual overview, see Live views.

Live view refresh runs on its own worker pool, separate from the materialized view refresh pool. Size it with live.view.refresh.worker.count.

cairo.live.view.checkpoint.compaction.interval​

  • Default: 0 (disabled)
  • Reloadable: no

Number of checkpoint seals between physical compaction attempts. Compaction repacks live state pages from sparse data segments so obsolete segments can be reclaimed. A value of 0 disables compaction. Without compaction, a superseded page is reclaimed only once its whole segment becomes unreferenced, so dead bytes left behind by out-of-order repairs can accumulate. Enable it for views that receive frequent out-of-order corrections.

cairo.live.view.checkpoint.max.duration.micros​

  • Default: 300000000 (5 minutes)
  • Reloadable: no

Maximum wall-clock interval, in microseconds, between head-checkpoint writes. This caps restart and out-of-order replay work for low-rate views that do not reach the row-count trigger.

cairo.live.view.checkpoint.purge.interval​

  • Default: 1
  • Reloadable: no

Number of checkpoint seals between sweeps that delete checkpoint segments no longer referenced by any checkpoint generation. A value of 0 disables the periodic sweep. Unreferenced segments are then reclaimed only by the sweep that runs once per server start, so their disk space is not released until a restart.

cairo.live.view.checkpoint.repair.replay.max.rows​

  • Default: 1000000
  • Reloadable: no

Maximum base rows a localized out-of-order repair replays in one refresh turn. A larger repair pauses at a timestamp-group boundary and continues in a later turn without publishing partial output. The refresh-turn duration limit also applies. A value of 0 or less disables this row budget.

cairo.live.view.checkpoint.repair.scan.max.keys​

  • Default: 100000
  • Reloadable: no

Maximum partition keys inspected while planning a localized ROWS repair. If planning crosses the limit, QuestDB uses an unlocalized repair instead. A value of 0 or less disables this key budget.

cairo.live.view.checkpoint.repair.scan.max.rows​

  • Default: 1000000
  • Reloadable: no

Maximum base rows scanned while discovering the bounds of a localized ROWS repair. This includes rows later discarded by the view's WHERE filter. If the limit is crossed, QuestDB uses the conservative unlocalized bound. A value of 0 or less disables this scan budget.

cairo.live.view.checkpoint.rows​

  • Default: 1000000
  • Reloadable: no

Number of live view output rows applied since the previous head checkpoint after which the refresh worker writes a new one. Smaller values shorten restart and out-of-order replay at the cost of more checkpoint writes. The value is also the per-turn row budget of the initial seed sweep, so lowering it also shortens each seed turn.

cairo.live.view.enabled​

  • Default: true
  • Reloadable: no

Enables or disables SQL support and the refresh job for live views. When disabled, CREATE LIVE VIEW fails with live views are disabled, and existing live views are neither refreshed nor listed in live_views(). They stay queryable as plain tables without their in-memory tier, and the base table's WAL is no longer retained on their behalf. Re-enabling live views rebuilds each existing view from the applied base table without invalidating it.

cairo.live.view.flush.retry.max​

  • Default: 5
  • Reloadable: no

Maximum number of consecutive failed refresh cycles, such as a failed flush to the view's disk tier, before the view is marked invalid. The view is invalidated as soon as either this count or cairo.live.view.flush.retry.max.duration.micros is exhausted. Failures caused by a transiently missing base table count only against the duration budget. A breach of cairo.live.view.refresh.memory.limit.bytes invalidates the view without any retry.

cairo.live.view.flush.retry.max.duration.micros​

  • Default: 60000000 (60 seconds)
  • Reloadable: no

Maximum time, in microseconds, that a view may keep failing refresh cycles before it is marked invalid. See cairo.live.view.flush.retry.max for how the two budgets interact.

cairo.live.view.in.memory.buffer.growth.bytes​

  • Default: 16777216 (16 MiB)
  • Reloadable: no

Bytes of aged rows that the in-memory tier may hold before a refresh compacts it. Aged rows are rows already flushed to disk and older than the view's IN MEMORY window. Until this many bytes of aged rows accumulate, refresh keeps appending in place; once they do, it swaps to a compacted buffer that evicts them. The value therefore bounds how much RAM the tier holds beyond the IN MEMORY window. A value of 0 or less compacts on every publish. Accepts a size suffix such as 16M.

cairo.live.view.in.memory.buffer.initial.bytes​

  • Default: 65536 (64 KiB)
  • Reloadable: no

Initial size of each column buffer in the in-memory tier. The tier keeps two buffer slots, and each slot holds one buffer per output column. Accepts a size suffix such as 64K.

cairo.live.view.in.memory.max​

  • Default: 3600000000 (60 minutes)
  • Reloadable: no

Upper bound on the IN MEMORY retention window. A CREATE LIVE VIEW whose IN MEMORY (or defaulted FLUSH EVERY) exceeds this value is rejected.

cairo.live.view.partition.compact.threshold​

  • Default: 100000
  • Reloadable: no

Threshold for the sweep that drops anchored-window partition state left behind the previous anchor boundary. The sweep runs only when all of the following hold: the anchor map has more partitions than this value, at least this many of them are reclaimable, and the reclaimable partitions make up at least half of the map. Only anchors that return TIMESTAMP and advance with the designated timestamp compact. An anchor value that is not monotonic or is NULL, and any ANCHOR EXPRESSION that returns LONG or INT, never compacts.

cairo.live.view.refresh.memory.limit.bytes​

  • Default: 0 (unlimited)
  • Reloadable: yes

Per-live-view limit on tracked native memory. It covers persistent window state, the IN MEMORY recent-row tier, staging memory, and transient buffers such as Parquet row-group decode buffers. Exceeding the limit invalidates the view immediately; recovery requires dropping and recreating it. Process-wide out-of-memory errors are not limit breaches and are retried instead.

This is one of the four workload memory limits and counts tracked native allocations only. A view acquires the limit when it is first compiled and keeps it until it is dropped or invalidated, so the limit applies to the view's running footprint across refreshes rather than to a single cycle. Persistent state grows with the number of distinct partition keys the view has seen and does not shrink when keys go quiet, and the in-memory tier does not shrink after a burst. A limit sized from an early measurement can therefore be breached later without any change in workload. A reloaded value reaches an existing view only after it is recreated or the server restarts.

Size the limit above the refresh workload's allocation floor. In particular, a RANGE frame, or a ROWS frame or lag() with PARTITION BY, allocates at least one cairo.sql.window.store.page.size page (1 MiB by default) on its first partition, and a Parquet-backed refresh may decode a complete row group.

cairo.live.view.refresh.turn.max.commits​

  • Default: 64
  • Reloadable: no

Maximum number of base-table commits a refresh worker processes in a single turn before yielding to other views.

cairo.live.view.refresh.turn.max.duration.micros​

  • Default: 50000 (50 milliseconds)
  • Reloadable: no

Maximum wall-clock time, in microseconds, a refresh worker spends on one view per turn before yielding.

live.view.refresh.worker.affinity​

  • Default: none
  • Reloadable: no

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

live.view.refresh.worker.count​

  • Default: 2 on hosts with up to 8 CPU cores, 3 on up to 32 cores, 4 on larger hosts
  • Reloadable: no

Number of worker threads that refresh live views. A single view is refreshed by one worker at a time, so more workers help when several views are busy at once, not when one view is slow.

A value of 0 turns live view refresh off. CREATE LIVE VIEW then fails, and existing views behave as described for cairo.live.view.enabled set to false.

live.view.refresh.worker.haltOnError​

  • Default: false
  • Reloadable: no

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

live.view.refresh.worker.nap.threshold​

  • Default: 7000
  • Reloadable: no

Number of idle worker-loop iterations before a refresh worker naps.

live.view.refresh.worker.sleep.threshold​

  • Default: 10000
  • Reloadable: no

Number of idle worker-loop iterations before a refresh worker sleeps.

live.view.refresh.worker.sleep.timeout​

  • Default: 10ms
  • Reloadable: no

Sleep duration when a refresh worker has no views to refresh.

live.view.refresh.worker.yield.threshold​

  • Default: 1000
  • Reloadable: no

Number of idle worker-loop iterations before a refresh worker yields.