Compaction
Compaction merges SSTables to reduce read amplification and reclaim tombstone space.
Level Structure
Leveled Strategy (10x size ratio)
| Level | Max | Trigger | Action |
|---|---|---|---|
| L0 | 4 files | Overflow | All L0 → overlapping L1 |
| L1 | 256 MB | Overflow | One L1 file → overlapping L2 |
| L2 | 2.56 GB | Overflow | One L2 file → overlapping L3 |
| L3 | 25.6 GB | Timer (1h) | Drop expired tombstones |
Write Stalling
| L0 Count | Effect |
|---|---|
| ≤ 4 | Normal. Compaction triggered. |
| 5–8 | Throttled. Each write sleeps (count - 4) × 1ms. |
| 9–12 | Stalled. RESOURCE_EXHAUSTED with retry-after. |
Merge Process
SSTable Run Fragments
Compaction output is a run of smaller fragments, not a monolith:
sstables/L1/run-{id}/frag-0000.sst
sstables/L1/run-{id}/frag-0001.sst
sstables/L1/run-{id}/frag-0002.sst
Max temporary space = 2 × fragment_size instead of 2 × total_run_size.
Trivial move: If a fragment's key range doesn't overlap the next level, it's moved without re-merge. The executor physically copies the SSTable file from the source-level path to the target-level path, updates the manifest, then deletes the source. This is necessary because SSTable paths are level-encoded — a manifest-only update would leave the file at the old path, causing not-found errors on subsequent reads. For time-ordered keys, most compactions are trivial moves.
Tombstone Lifecycle
Range tombstones use a watermark protocol: only eligible for deletion when all levels below have been compacted past the tombstone's creation timestamp.