Start with EXPLAIN (ANALYZE, BUFFERS) on the slow query as it actually runs. Then check whether its SQL shape can use the vector index, whether the plan chose an appropriate exact or approximate search, and whether filters, memory use, or maintenance explain the result. Measure latency and result quality together: HNSW and IVFFlat can be faster than exact search, but they trade away perfect recall.
1. Capture the plan for the slow query
Run the query with representative parameters and data, adding EXPLAIN (ANALYZE, BUFFERS). PostgreSQL executes the statement when ANALYZE is included, so choose an appropriate environment and be mindful of any side effects. The pgvector project README recommends this plan format for diagnosing performance.
As an Amazon Associate I earn from qualifying purchases.
Read the plan for actual execution time, buffer activity, row counts, and whether PostgreSQL used the expected index. A sequential scan is not automatically a problem: for a small table, scanning the table may be cheaper than using an index. If the plan differs between test and production, compare the data volume, query parameters, filters, and settings rather than assuming the index itself is broken.
2. Check that the query matches the indexable form
For pgvector’s documented nearest-neighbor index pattern, order by a distance operator in ascending order and apply a LIMIT. For example:
#1 Best Overall
SELECT *
FROM items
ORDER BY embedding <-> '[3,1,2]'
LIMIT 5;A reformulation such as ORDER BY 1 - (embedding <=> query) DESC may express a similar ranking to a reader, but it does not match the documented indexable pattern. Keep the distance operator in the ascending ORDER BY when testing whether the vector index can serve the query.
As a diagnostic experiment, the project suggests temporarily setting enable_seqscan = off inside a transaction to encourage an index plan. Use it to determine whether the query shape can use an index; it is not a general production fix. If forcing the index changes the plan, compare execution costs and results rather than treating index use as proof of improvement.
3. Establish whether the bottleneck is exact or approximate search
pgvector performs exact nearest-neighbor search by default. Exact search returns the true nearest neighbors for the distance metric, so it provides perfect recall, but the work can grow with the dataset. HNSW and IVFFlat are approximate indexes: they can reduce query cost while returning a different set of neighbors. Benchmark both latency and recall against exact results on a representative sample.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRank #2
To obtain an exact-search comparison for an indexed query, the README describes locally disabling index scans with enable_indexscan = off. Keep that comparison scoped to diagnosis; do not assume one approximate configuration is suitable for every query or workload.
When an exact scan is slow
- For an exact scan without a vector index, the project suggests increasing
max_parallel_workers_per_gather. Treat this as a tuning experiment and check the plan and workload impact. - If all vectors are normalized to unit length, pgvector notes that inner product can perform better. This is conditional on normalization; validate that the stored vectors and query vectors meet that requirement and compare results for your application.
- For selective filters, first test whether an ordinary index on the filter column makes exact search efficient within the matching rows.
4. Tune the approximate index your plan actually uses
Do not adjust HNSW and IVFFlat controls interchangeably. Identify the index in the plan, change one relevant setting at a time, and record latency and recall against your exact-search baseline.
| Index | What to tune | Trade-off and starting point |
|---|---|---|
| HNSW | hnsw.ef_search, plus iterative-scan settings for filtered queries |
The README gives a default hnsw.ef_search of 40. Broader search can improve recall but usually costs more time. Validate against your workload. |
| IVFFlat | Number of lists at index creation and ivfflat.probes at search time |
The project’s starting heuristic is approximately rows divided by 1,000 for datasets up to one million rows, and the square root of row count above one million. It suggests beginning probes near the square root of the list count. More probes can improve recall at a speed cost. |
HNSW breadth and iterative scans
Increasing hnsw.ef_search broadens the candidate search and can improve recall, but it can also increase latency. Tune it against the result quality your application needs rather than maximizing it by default.
For filtered queries that return too few matches, the README documents hnsw.iterative_scan = strict_order and hnsw.iterative_scan = relaxed_order. Iterative scans can continue searching for matches, subject to hnsw.max_scan_tuples and available scan memory. Strict ordering preserves exact distance order; relaxed ordering can improve recall while permitting slight deviations in distance order. Check whether the application depends on strict ranking before choosing relaxed ordering.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →IVFFlat lists and probes
The list-count values above are project heuristics, not universal optima. Measure them on the actual corpus. An IVFFlat index built with too few rows for its number of lists may return fewer results; the README advises creating the index after the table has data. Increasing probes expands the search and can improve recall, at the expense of speed.
5. Diagnose filters and tenant layout
With approximate indexes, filtering is applied after the vector index scan. That can leave too few results even when the query returns quickly. As an illustration—not a performance benchmark—the project README estimates that if a filter matches 10% of rows and HNSW uses its documented default search breadth of 40, roughly four matching rows may be found on average. Actual counts vary with the data and query.
Choose the next experiment based on filter selectivity and how many distinct filter values you have:
- Highly selective filter: try an ordinary index on the filter column and exact nearest-neighbor search over the matching rows.
- Approximate search with too few filtered matches: try iterative scans, then measure returned-row counts, latency, and recall.
- A few distinct filter values: consider a partial vector index for each relevant value.
- Many filter values or tenant isolation needs: consider partitioning. The project warns that tenants sharing one approximate index can affect one another’s recall and speed; list partitioning or separate tables are named isolation approaches.
6. Reduce the working set carefully
If memory footprint is a constraint, the README points to halfvec and binary quantization with reranking as ways to reduce the working set at scale. These options can change numerical precision or search behavior. Compare their recall and output quality with the current representation before adopting them; a smaller index is not useful if it misses application-critical neighbors.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →7. Include index maintenance in the diagnosis
When HNSW vacuuming is slow
For slow HNSW vacuuming, the project suggests running REINDEX INDEX CONCURRENTLY before VACUUM. Confirm the index name and operational suitability for your PostgreSQL deployment before running maintenance commands.
When index creation is slow
PostgreSQL’s pg_stat_progress_create_index view exposes index-build progress. The pgvector README includes separate progress queries for HNSW and IVFFlat, which help identify the build phase rather than leaving index creation opaque.
8. Compare changes on the workload that matters
For each candidate change, use the same representative queries and data, and compare these outcomes:
- Query latency and buffer reads.
- Recall or application-relevant result quality against exact search.
- How many rows survive each filter.
- Index memory footprint, build time, and maintenance cost.
- Whether one tenant’s workload or filter distribution affects another’s results.
The documented defaults and feature set can vary by installed pgvector release. The guidance here reflects the project README on its moving master branch as accessed October 4, 2026; check the documentation for the release installed in your deployment before relying on a version-specific setting.
Recommended Free Tools
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
