The optimizer merges, indexes, and vacuums segments in the background
The optimizer is the background process that keeps the segment layout healthy. It does three things: merging small segments into larger ones, building indexes (HNSW graphs and payload indexes) on segments that have grown past thresholds, and vacuuming deleted points out of segments. It runs continuously, triggered by thresholds on segment size, segment count, and deletion ratio. When it acts on a segment, it reads all the points from the source segments, builds the new consolidated structures, writes them to a new segment, and atomically replaces the old ones. This is essential for search performance - a collection with hundreds of tiny unindexed segments would have terrible query latency - but the work itself is CPU and I/O intensive.
The reason aggressive optimization hurts query latency is resource contention. Merging reads and writes large amounts of data, builds HNSW graphs (which is CPU-heavy), and touches disk. If the optimizer is running constantly because thresholds are set too low, it competes with search queries for CPU cores, memory bandwidth, and disk I/O. The most visible symptom is a p99 latency spike that correlates with optimizer activity. The second-order effect is that frequent merges mean frequent segment replacement, which invalidates the page cache for the affected data and causes cold reads on the next query. On the flip side, too-lazy optimization means many small segments, each with its own graph and overhead, so every query pays fan-out cost across more segments than necessary. The optimizer thresholds are therefore a tuning surface that balances write amplification and merge cost against query fan-out and index freshness.
deleted_threshold: fraction of deleted points above which a segment is vacuumed.
vacuum_min_vector_number: don't vacuum segments smaller than this.
default_segment_number: target number of segments at steady state.
max_segment_size: segments larger than this are split.
memmap_threshold: above this, a segment is stored on disk rather than in RAM.
indexing_threshold: above this, the optimizer builds the HNSW graph.
max_optimization_threads: bounds how much CPU the optimizer can consume.
The trade-off is index freshness and search efficiency against background resource consumption. The standard production pattern is to tune the optimizer differently for bulk load and steady state. During a bulk load, raise indexing_threshold and memmap_threshold so the optimizer does not try to build graphs on every small segment - you want to load fast, then index once at the end. After the load, lower the thresholds so the optimizer consolidates and indexes the data. The common mistake is leaving the default thresholds in place during a large bulk load, which causes the optimizer to churn constantly, slowing both the load and any concurrent queries. The second mistake is setting max_optimization_threads to a high value on a node that also serves queries - the optimizer will starve the search path. The third mistake is forgetting that deletes are not free: a segment full of tombstones still consumes disk and query time until it is vacuumed, so deleted_threshold matters for both storage and latency. Version note: the optimizer config fields and their defaults have changed across releases, and some fields (like the older indexing_threshold semantics) have been reworked. Read the effective config at runtime and re-tune after upgrades rather than assuming the old values still mean the same thing.
Version-dependent: the OptimizersConfigDiff fields have changed across releases. Some fields have been renamed, defaults have shifted, and the auto value for max_optimization_threads behaves differently depending on the number of CPU cores and the version. In recent releases, some thresholds are interpreted per-segment rather than per-collection, which changes the tuning math. Always inspect the effective optimizer config after collection creation rather than assuming the values you passed are the values in effect.
0-2 years experience
2-5 years experience
5-8 years experience
8+ years experience
