[ideoma]

Summary

Document adaptive WAL apply block sizing and configuration, shipping in QuestDB 10.1.0.

Source: questdb/questdb#7595

[github-actions]

🚀 Build success!

Latest successful preview: https://preview-602--questdb-documentation.netlify.app/docs/

Commit SHA: 3def001

📦 Build generates a preview & updates the link on each commit.

[ideoma]

Review: approve-with-nits

No blocking issues. Level-2 review completed with six review passes against commit 3def0010b9236a2682a73f43b7ac8aedcf4486ae.

Non-blocking

• Minor — Define the newly referenced controls (documentation/configuration/wal.md:18–23). cairo.wal.apply.look.ahead.txn.count and cairo.wal.max.lag.size have no reference entries elsewhere in the documentation. Add short definitions/defaults (200 transactions and 75M, respectively), inline or as property entries.
• Minor — Include the tuning tradeoff at the destination (documentation/configuration/wal.md:13–23). Readers entering from O3 tuning see the sizing mechanics but not the explicit tradeoff supplied by the WAL concept page. One sentence defining a block and explaining fewer O3 merges versus more memory would make the section self-contained.
• Nit — Prefer “native memory limit” over “RSS limit” (documentation/configuration/wal.md:38–40). These settings limit tracked native allocations rather than total process RSS. The implementation itself uses RSS terminology, and the exact keys make the intended reference clear, so this is not a blocker. Optionally use “process-wide native memory limit” and link the keys directly to their Cairo reference sections.
• Minor — Add a changelog entry (documentation/changelog.mdx). The new configuration properties and explanatory section meet the repository’s changelog criteria. Add one concise entry linking to adaptive WAL apply blocks.

What works

The existing WAL configuration page is the right home, and both concept pages provide useful entry points without requiring sidebar changes. Starting size, growth budget, and maximum adaptive row limit have distinct entries. The WAL concept explanation clearly states the merge-count/memory tradeoff, and all four new anchors exist in the generated HTML.

Defaults, non-reloadability, disabling, growth/reset behavior, and adaptive look-ahead agree with product merge d08635ceebb3d1b1460c092bec5a29c3bb424656.

Validation

• Read all three changed pages fully; completed technical, placement/retrieval, information-flow, cross-page, adversarial, and one-shot consumer passes.
• yarn build passed (exit 0); git diff --check origin/main...HEAD passed.
• No new SQL syntax or examples, so SQL-parser changes are not applicable.
• Product tests were inspected, not executed. No disposable running instance was available for live SHOW PARAMETERS or SQL validation; behavior was source-verified.

Downgraded and excluded findings

Four non-blocking findings retained. The initial blocking interpretation of the memory terminology was too strong. The row-cap objection is withdrawn: “cap for the starting block size and its growth” correctly describes the calculated adaptive limit. An oversized individual transaction is a separate case; mentioning it would be optional clarification, not a merge requirement.

The fresh-context adversarial pass also raised the following concerns about unchanged passages, so they are excluded from this PR’s verdict. This does not certify the old text as correct:

Concern	Why excluded
Unconditional WAL durability claim	Existing WAL capability table
tables() example using name	Existing query, unchanged
Immediate replication claim	Existing Enterprise explanation
Missing read-after-write warning	Existing asynchronous-apply discussion
Resume advice without diagnosis	Existing recovery instructions
Lag transaction count sounds like a backlog bound	Existing property description
Overbroad O3 ingestion compatibility claim	Existing compatibility section
Missing sealed-partition late-row caveat	Existing backfill/storage-policy discussion
Ingestion-time timestamps conflict with replay deduplication	Both recommendations predate this PR
“Recent activity” misstates the metrics window	Existing metrics description
UPDATE I/O attributed to write-amplification counters	Existing metrics discussion
“Cluster-wide” Prometheus label	Existing example
Invalid numerical write-amplification illustration	Existing threshold discussion
Within-batch disorder omitted from O3 definition	Existing definition
O3 memory-page default disagrees with Cairo reference	Existing cross-page discrepancy
Repartitioning migration cost omitted	Existing partition-sizing guidance
Capacity-planning thresholds conflict with O3 guidance	Both passages unchanged

The missing-property objection also included cairo.wal.segment.rollover.size; that reference is preexisting and documented under replication. Only the two newly mentioned controls are retained above.

The one-shot consumer’s other objections were not blockers:

Objection	Disposition
Cannot determine RAM-limit interaction	The existing link to Cairo memory limits leads to both RAM settings and explains their interaction
Configuration destination and installation syntax are missing	Shared prerequisites documented in Configuration overview, not introduced here
Activation instructions are missing	New entries explicitly say “Reloadable: no”; general startup/restart guidance lives in Configuration overview

An overview link or small configuration example could improve standalone usability, but neither is necessary to merge this change.