Imported from qdrant/skills (
skills/qdrant-performance-optimization/search-speed-optimization/SKILL.md). Install upstream withnpx skills add qdrant/skills --skill search-speed-optimization. Copyright stays with the author.
Diagnose a problem
There are multiple possible reasons for search performance degradation. The most common ones are:
- Memory pressure: if the working set exceeds available RAM
- Complex requests (e.g. high
hnsw_ef, complex filters without payload index) - Competing background processes (e.g. optimizer still running after bulk upload)
- Problem with the cluster (e.g. network issues, hardware degradation)
Single Query Too Slow (Latency)
Use when: individual queries take too long regardless of load.
Diagnostic steps:
- Read the slow request log (v1.16+, always on, per node) to find the slowest unique operations over 50 ms Slow request log
- Check if second run of the same request is significantly faster (indicates memory pressure)
- Try the same query with
with_payload: falseandwith_vectors: falseto see if payload retrieval is the bottleneck - If request uses filters, try to remove them one by one to identify if a specific filter condition is the bottleneck
Common fixes:
- Tune HNSW parameters: Fine-tuning search
- Enable in-memory quantization: Scalar quantization
- On v1.19+, store vectors as
datatype: turbo4(4-bit, about 8x smaller) to cut disk reads. Lossy: the originals are no longer full precision, so check recall. Set it when creating the collection or adding a new named vector, so existing data must be re-ingested turbo4 - Reduce Vector Dimensionality with Matryoshka Models: Matryoshka Models
- Use oversampling + rescore for high-dimensional vectors Search with quantization
- Enable async I/O (
io_uring) for disk-heavy workloads on Linux:storage.performance.io_uring: autoon Qdrant 1.19 or newer,async_scorer: trueon 1.18 or older Async I/O
Can't Handle Enough QPS (Throughput)
Use when: system can't serve enough queries per second under load.
- Reduce segment count (
default_segment_numberto 2) Maximizing throughput - Use batch search API instead of single queries Batch search
- Enable quantization to reduce CPU cost Scalar quantization
- Add replicas to distribute read load Replication
Filtered Search Is Slow
Use when: filtered search is significantly slower than unfiltered. Most common SA complaint after memory.
- Create payload index on the filtered field Payload index
- Use
is_tenant=truefor primary filtering condition: Tenant index - Try ACORN algorithm for complex filters: ACORN
nestedfilter conditions check each remaining candidate's payload element by element, which is slow when many candidates remain. On Qdrant 1.20 or newer, create per-element indexes (thenestedparameter of the payload index) on every field the nested filter uses, so Qdrant answers it from the indexes without reading payload Per-element index.- Substring match (
matchwithsubstring, 1.20+) is expensive: it checks every distinct value of the field, and Qdrant rejects it whenever strict mode is enabled (the Qdrant Cloud default). Prefer prefix match (keyword index withprefix: true) or full-text match where the use case allows. A keyword index, especially withprefix, speeds it up; a full-text index doesn't help Substring match - If payload index was added after HNSW build, trigger re-index to create filterable subgraph links
Optimize search performance with parallel updates
Diagnostic steps
- Try to run the same query with
indexed_only=trueparameter, if the query is significantly faster, it means that the optimizer is still running and has not yet indexed all segments. - If CPU or IO usage is high even with no queries, it also indicates that the optimizer is still running.
Recommended configuration changes
- reduce
optimizer_cpu_budgetto reserve more CPU for queries - As an alternative to
indexed_only, setprevent_unoptimized: true(v1.17.1+, experimental) to prevent searching over unindexed data. When it's on, setwait=falseon all write requests, or writes block until indexing catches up.
Learn more in the read-write contention guide
What NOT to Do
- Set quantization to not stay in RAM (disk thrashing on every search): avoid
memory: cold/cachedon Qdrant 1.19 or newer; on 1.18 or older, avoid leavingalways_ramfalse or unset while the original vectors areon_disk: true - Put HNSW on disk for latency-sensitive production (only for cold storage)
- Increase segment count for throughput (opposite: fewer = better)
- Create payload indexes on every field (wastes memory)
- Blame Qdrant before checking optimizer status
