Write Coalescing

ConvergeDB does not flush every write to disk immediately. Instead, the server accumulates writes within a configurable coalescing window and flushes them as a single atomic batch.

How coalescing works

1. As ASSERT, PATCH, and RETRACT operations arrive from sources, the server marks the affected entities as dirty in the accumulator.
2. At the end of each coalescing window (default: 20ms), the server flushes all dirty entities in a single atomic batch:
   • Append the batch to the WAL and fsync.
   • Update the in-memory entity table.
   • Emit subscriber notifications.

If the same entity is written multiple times within a single window, only the net result of all operations is flushed. This is the coalescing effect.

Why coalescing matters

Reduced I/O

Without coalescing, a hot entity updated 100 times per second would require 100 WAL writes and 100 subscriber notifications per second. With a 20ms coalescing window, those 100 updates collapse into roughly 50 flushes (2 per window), and many of those may be deduplicated if the data converges to the same value.

Bounded notification latency

Subscriber notification latency is bounded by the coalescing window. The worst case is one full window duration from the last ASSERT to the notification delivery. For the default 20ms window, subscribers see updates within 20ms of the last write.

Throughput target

The coalescing window is a key factor in achieving the target throughput of 200,000 ASSERT operations per second per partition. At 20ms windows, the server flushes 50 times per second. With 200K incoming asserts per second, each flush batch handles roughly 4,000 operations on average, but many of those operations target the same entity and are collapsed by the accumulator.

Tuning the coalescing window

Window size	Trade-off
Shorter (e.g., 5ms)	Lower notification latency, less coalescing benefit, more WAL writes per second.
Longer (e.g., 100ms)	Higher coalescing ratio for hot entities, fewer WAL writes, but higher notification latency.
Default (20ms)	Good balance for most workloads.

The optimal window depends on your workload:

• If your entities are updated rarely (less than once per second), coalescing provides little benefit. The window mainly determines the maximum notification delay.
• If your entities are updated frequently (hundreds of times per second), a longer window produces significantly fewer flush writes and notifications.

Interaction with client-side batching

Client-side batching reduces the number of TCP writes. Server-side coalescing reduces the number of WAL writes and notifications. They are complementary:

• Client-side batching sends many operations in a single TCP write, reducing network overhead.
• Server-side coalescing merges operations targeting the same entity within a time window, reducing disk I/O and notification volume.

Both can be active simultaneously for maximum throughput.