How do oversampling and rescore in Qdrant's QuantizationSearchParams recover recall?

## The problem being solved When a Qdrant collection is quantized, the HNSW traversal computes distances on the compressed representation. Compression means the computed distance is an estimate of the true one. Two failure modes follow. First, **misordering**: the k results returned are mostly the right points, but their relative ranks are wrong, which matters when downstream logic cares about the top result or feeds scores into a reranker. Second, **misses**: a genuine nearest neighbour is estimated slightly too far away and falls out of the top k entirely. No amount of re-sorting the returned k can bring it back. Oversampling addresses the misses; rescoring addresses the misordering. They are designed to be used together. ## The mechanism Both live in `models.QuantizationSearchParams`, nested inside `models.SearchParams` on the request: `client.query_points(collection_name="docs", query=vector, limit=10, search_params=models.SearchParams(quantization=models.QuantizationSearchParams(oversampling=3.0, rescore=True)))` `oversampling` is a multiplier on `limit`. With `limit=10` and `oversampling=3.0`, Qdrant collects roughly 30 candidates during the quantized traversal. The candidate net is wider, so a neighbour whose estimated distance was slightly inflated is still caught. `rescore` then loads the **original** vectors for exactly those candidates, computes true distances, sorts, and truncates to `limit`. The final ordering is therefore exact with respect to the candidate set — the only remaining error is a true neighbour that never made it into the candidates at all, which is precisely what a larger oversampling factor reduces. ## Why the cost is acceptable The expensive-looking part — reading full-precision vectors — happens for only a few dozen points, after the graph walk is done. The graph walk itself, which touches orders of magnitude more vectors, runs entirely on the compressed copy. That asymmetry is the architectural point of Qdrant's quantization design. It is what makes the canonical configuration work: `models.VectorParams(size=1536, distance=models.Distance.COSINE, on_disk=True)` for the originals, plus a quantization config with `always_ram=True`. Traversal never touches disk; rescoring touches it for a bounded, small number of random reads. On NVMe that is a few milliseconds; on network storage it is not, which is why storage class matters for this pattern. ## Tuning Oversampling is empirical and interacts with the quantization mode. Scalar quantization's error is small enough that a factor near 1.5-2.0 often suffices. Binary quantization has much coarser distances and typically needs substantially more — factors of 3 or higher are common, and it is effectively unusable with oversampling at 1.0. Product quantization sits between them and depends on the compression ratio chosen. The method mirrors any other recall tuning: sample real query vectors, get ground truth with `models.SearchParams(exact=True)`, then sweep the oversampling factor and record recall@k against p95 latency. Pick the smallest factor that clears your recall floor. Re-run when the embedding model or the quantization mode changes. ## The other switches `rescore=False` skips the full-precision pass entirely. It is the right choice only when the compressed distances are good enough on their own — plausible with mild scalar quantization on a latency-critical path, dangerous with binary. Turning it off is also how you would isolate, during debugging, how much of your recall is coming from rescoring. `ignore=True` tells the query to bypass the quantized representation and use original vectors throughout. That gives the accuracy of an unquantized collection at the cost of losing the memory-locality benefit for that query — useful for a small number of high-value queries, or for comparing quantized against unquantized behaviour on the same index without rebuilding anything. ## Common mistakes The most common is enabling quantization and never touching these parameters, then reporting that "quantization destroyed our recall". Half the recall in a well-tuned quantized setup comes from rescoring. The second is pairing binary quantization with default oversampling and concluding binary quantization does not work — the candidate net was simply too narrow for how coarse the distances are. The third is putting the original vectors on slow shared storage. Rescoring turns every query into a handful of random reads; on high-latency storage those reads dominate the request and the whole design inverts from a win into a bottleneck.