Why are vector results slow after adding a metadata filter?
Quick answer: The usual symptom is a short answer rather than a slow one, and nothing reports it. Measure the row count rather than the milliseconds, then read
EXPLAINto see which plan you actually got, because the same query can take an approximate path or an exact one and only one of them can come up short. Then fix it in this order: a partial index if the predicate is one you query constantly, the iterative scan setting for your index type otherwise, and a btree on the filter column as the plan that cannot truncate. A largeref_searchis not on the list.
What is the problem?
Section titled “What is the problem?”pgvector’s README states the mechanism in one sentence.
“With approximate indexes, filtering is applied after the index is scanned.” (pgvector README, read on 2026-09-20)
So an HNSW scan collects its candidates without knowing your WHERE clause, and
whatever survives the filter is your result. If that is fewer rows than your
LIMIT, the query still succeeds.
The result is short rather than slow, and nothing in it says so.
The bench
Section titled “The bench”Everything below was measured on 2026-09-20 on PostgreSQL 17.11 with pgvector
0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, on a host with 8 vCPUs and
62 GB of RAM running Linux 6.17.0-1022-azure under Docker 29.1.3, at the image’s
default server settings.
The corpus loaded on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container is 100,000 rows of vector(768). It is
synthetic: 100 cluster centres drawn from a standard normal distribution, each
row its centre plus normal scatter with a standard deviation of 0.4 per
dimension. The tenant column was assigned at random and independently of the
cluster, so a filter on it is a real filter and not a disguised cluster
selection.
Counted on 2026-09-20 in that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17
container, tenant = 7 matches 5,074 rows, 5.07% of the table, and a rare flag
matches 100 rows, 0.1%.
The two tables every block below uses:
CREATE TABLE items ( id bigserial PRIMARY KEY, tenant int NOT NULL DEFAULT 1, rare bool NOT NULL DEFAULT false, embedding vector(768));
CREATE TABLE queries ( qid int PRIMARY KEY, q vector(768));There are 200 query vectors from the same generator, and they are not corpus rows, so nothing is guaranteed a distance-zero hit. Ground truth for each is the exact top 10 by L2 distance from a sequential scan. Recall@10 below is the fraction of those 2,000 exact neighbours the approximate scan also returned.
Every query time on this page is a mean over those same 200 queries, taken
inside the server around each execution. That is one basis for every comparison
here, which matters because a single run and a 200 query mean can rank two plans
in opposite orders. They also all come from one contiguous run: on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container, 2026-09-20, the same plan measured
0.391, 0.517 and 0.662 ms in three separate sessions on this shared host, and
two such runs printed side by side read as a contradiction. The few single
EXPLAIN (ANALYZE) runs quoted below are labelled where they appear, and they
are there to show which plan was chosen rather than to be compared on time. Index
build times are stated as build times and are not query times.
These were the settings that image reported, and they are the numbers the rest of this page moves:
| setting | observed default |
|---|---|
hnsw.ef_search | 40 |
hnsw.iterative_scan | off |
hnsw.max_scan_tuples | 20000 |
hnsw.scan_mem_multiplier | 1 |
ivfflat.probes | 1 |
ivfflat.iterative_scan | off |
ivfflat.max_probes | 32768 |
Measure the count, not the time
Section titled “Measure the count, not the time”CREATE INDEX items_hnsw ON items USING hnsw (embedding vector_l2_ops);Run the query 200 times and count rows. Measured on 2026-09-20 on that
PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, with no index on the
filter column so the HNSW path is the one under test:
hnsw.iterative_scan | ef_search | mean rows for LIMIT 10 | minimum | queries getting all 10 | recall@10 | mean ms |
|---|---|---|---|---|---|---|
off | 40 | 2.06 | 0 | 0 of 200 | 0.202 | 3.189 |
off | 100 | 10.00 | 10 | 200 of 200 | 1.000 | 32.996 |
off | 400 | 10.00 | 9 | 199 of 200 | 0.982 | 5.155 |
relaxed_order | 40 | 10.00 | 10 | 200 of 200 | 0.972 | 4.712 |
strict_order | 40 | 10.00 | 10 | 200 of 200 | 0.939 | 4.820 |
relaxed_order | 400 | 10.00 | 10 | 200 of 200 | 0.983 | 5.216 |
The table shows two more things.
Full rows and imperfect recall are different questions. Measured on
2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container,
the strict_order row returned all ten rows on every one of the 200 queries and
still missed 6.1% of the exact neighbours. A row count of 10 is not evidence the
search was good, so do not treat “I got my LIMIT back” as the end of the
tuning. Count rows to find
the silent truncation, then measure recall against an exact answer to find out
whether the rows are the right ones.
relaxed_order measured better on recall than strict_order on 2026-09-20
on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, 0.972 against
0.939 at the same ef_search. That is the direction pgvector’s own README
describes, and it surprises people who read “strict” as “more correct”.
“Relaxed allows results to be slightly out of order by distance, but provides better recall.” (pgvector README, read on 2026-09-20)
“Strict ensures results are in the exact order by distance.” (pgvector README, read on 2026-09-20)
“Slightly out of order” is something to plan for. Measured on
2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container,
under relaxed_order 39 of the 200 queries returned at least one pair of rows in
the wrong distance order. If your application shows the results ranked, re-sort
them:
WITH relaxed AS MATERIALIZED ( SELECT id, embedding <-> (SELECT q FROM queries WHERE qid = 3) AS distance FROM items WHERE tenant = 7 ORDER BY distance LIMIT 10)SELECT id, distance FROM relaxed ORDER BY distance + 0;MATERIALIZED stops the planner folding the inner query back into the outer
one. The + 0 is what keeps the re-sort on PostgreSQL 17 and later: pgvector’s
README says it is needed there, and without it the planner drops the outer sort.
Read the plan before you believe the fix
Section titled “Read the plan before you believe the fix”The ef_search = 100 row above returned all ten rows at recall 1.000, which
looks like the tuning working, but it is not. Measured on 2026-09-20 on that
PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, EXPLAIN (ANALYZE)
on the same query at three settings:
ef_search | plan chosen | rows | time, one EXPLAIN run |
|---|---|---|---|
| 40 | Index Scan using items_hnsw | 2 | 5.990 ms |
| 100 | Seq Scan on items plus a top-N heapsort | 5074 | 81.232 ms |
| 400 | Index Scan using items_hnsw | 10 | 7.776 ms |
Those three times are single EXPLAIN (ANALYZE) runs, on 2026-09-20 on that
PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, and they are the only
single runs on this page. Read the plan column rather than the time column: the
200 query mean for the middle row is the 32.996 ms in the table above, and
comparing a single run against a mean is how two plans end up ranked in opposite
orders on the same page.
At ef_search 100 the planner costed the index scan higher than reading the
whole table, took the exact path, and returned a perfect answer by not using the
vector index at all. The recall of 1.000 is a sign of that exact path rather
than of a successful search.
More generally, a filtered vector query has several plans available to it, and the one you get depends on statistics, selectivity and which indexes exist. Confirm the plan rather than assuming the mechanism.
The exact plan cannot come up short, and it is not always fast
Section titled “The exact plan cannot come up short, and it is not always fast”Put an ordinary btree index on the filter column and the planner will often stop
approximating altogether. Measured on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container, with a btree on tenant:
Limit (rows=10) -> Sort (Sort Method: top-N heapsort) -> Bitmap Heap Scan on items (Heap Blocks: exact=942) -> Bitmap Index Scan on items_tenantBuffers: shared hit=31443All 200 queries returned 10 rows at recall 1.000 on 2026-09-20 on that
PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, because there is
nothing approximate left in that plan. It reads 5,074 rows and sorts them
exactly.
Be careful what you conclude from that. Measured on 2026-09-20 on that
PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, exact is not the same
as fast: at this selectivity it is the slowest of the three plans in the table
below, at a mean of 26.645 ms over the 200 queries.
It is not the slowest exact plan on this page. On 2026-09-20 on that PostgreSQL
17.11 pgvector/pgvector:0.8.6-pg17 container, the sequential scan the planner
chose at ef_search 100 is exact at the same selectivity and means 32.996 ms
over the same 200 queries. Budget with the larger of the two, because going
exact means accepting whichever the planner picks.
Measured on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container, the three ways of answering the 5.07% query:
| plan | mean rows | recall@10 | mean ms over 200 queries |
|---|---|---|---|
| btree plus top-N heapsort, exact | 10.00 | 1.000 | 26.645 |
HNSW with relaxed_order at ef_search 40 | 10.00 | 0.972 | 4.712 |
| a partial HNSW index on the same predicate | 10.00 | 1.000 | 0.536 |
So the btree buys correctness, not speed, when 5.07% of the table matches,
measured on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container. It reads 5,074 rows to return 10. What it does guarantee is that the query cannot come up
short, which is the failure this page is about.
At 0.1% selectivity the planner stops using the vector index whichever indexes
exist, and what is left is how fast it reaches the 100 rows. Measured on 2026-09-20 on
that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, with the rare
predicate matching 100 rows:
| available indexes | plan chosen | mean rows | mean ms over 200 queries |
|---|---|---|---|
| btree on the flag plus HNSW | Index Scan on the btree, top-N heapsort | 10.00 | 0.561 |
| HNSW only | Seq Scan plus top-N heapsort | 10.00 | 8.956 |
Both are exact, and neither used the vector index. Scanning 100,000 rows to sort
100 was cheaper than walking the graph on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container.
Taken together, measured on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container: the btree path answers the 0.1%
filter in 0.561 ms, faster than the other plan measured there, and the 5.07%
filter in 26.645 ms, which is the slower end of the three-plan table above rather
than of everything measured at 5.07%: the sequential scan at ef_search 100
means 32.996 ms. It is the only one of those three that cannot truncate. Index the metadata column so the planner has it available, then read
the plan to find out whether it took it:
CREATE INDEX items_tenant ON items (tenant);When the approximate path is forced, there is a budget
Section titled “When the approximate path is forced, there is a budget”If the planner does take the HNSW scan on a very selective filter, iterative scans do not rescue it, because they stop at a limit.
“Specify the max number of tuples to visit (20,000 by default)” (pgvector README, read on 2026-09-20)
Measured on 2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17
container, with enable_seqscan off and no metadata index so the HNSW scan is
the only path, relaxed_order on, and the 0.1% predicate:
hnsw.max_scan_tuples | mean rows for LIMIT 10 | queries getting all 10 |
|---|---|---|
| 500 | 0.10 | 2 of 200 |
| 20000 (default) | 1.70 | 33 of 200 |
| 200000 | 2.48 | 47 of 200 |
Ten times the budget bought less than one extra row on average. That is the
constraint on this corpus: for a rare value, raising
max_scan_tuples did not find enough matching neighbours, and raising
ef_search is not the answer either. The scan is also bounded by memory, and pgvector’s README
says to try raising hnsw.scan_mem_multiplier if raising hnsw.max_scan_tuples
does not improve recall.
Partial indexes, and the way they quietly stop working
Section titled “Partial indexes, and the way they quietly stop working”For a predicate you query constantly, index only those rows. Measured on
2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, a
partial HNSW index over the 5,074 rows of tenant = 7 was 20 MB against 391 MB
for the full index, built in 1.870 seconds, and returned all 10 rows on every
one of the 200 queries at a mean of 0.536 ms, against 4.712 ms for the iterative
scan and 26.645 ms for the btree on the same filter.
CREATE INDEX items_hnsw_t7 ON items USING hnsw (embedding vector_l2_ops) WITH (m = 16, ef_construction = 64) WHERE tenant = 7;The catch is that PostgreSQL uses a partial index only when it can prove your
WHERE clause implies the index predicate, and a parameter is not a proof.
Measured on 2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17
container, the same query prepared two ways under plan_cache_mode = force_generic_plan:
| how the predicate is written | index chosen | mean rows for LIMIT 10 | mean ms over 200 queries |
|---|---|---|---|
WHERE tenant = 7 | items_hnsw_t7, the partial index | 10.00 | 0.351 |
WHERE tenant = $1 | items_hnsw, the full index | 2.06 | 2.969 |
The index on disk, the data and the parameter value at execution are identical
in both rows. The generic
plan is built without knowing $1 will be 7, so it cannot use an index defined
only for rows where it is. The custom plan for the same prepared statement did
use the partial index and returned all 10 rows on every one of the 200 queries,
at a mean of 0.539 ms, measured on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container.
Some of what separates the three partial-index figures on this page is how often
the plan is built, not how fast the index is. The 0.536 ms above and the
0.539 ms here rebuild the plan on every one of the 200 calls and the timer is
around the whole call; the 0.351 ms reuses one generic plan and skips that work.
Measured as a separate control on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container, eight interleaved repetitions of each,
every figure a mean over the same 200 queries: the same statement on the same
index cost 0.284 to 0.380 ms with the plan reused and 0.383 to 0.427 ms with it
rebuilt, with no overlap between the two sets. Non-overlapping is the whole
result of that 2026-09-20 control on the PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17 container. Those eight repetitions were kept as
ranges rather than as paired means,
so they show that rebuilding the plan costs something and they do not say how
much: the separation between the two sets is anywhere from 0.003 to 0.143 ms,
and this page does not apportion its own 0.185 ms gap from them.
This is how a partial index stops working in production without anyone changing
anything: your ORM parameterises the tenant, the statement gets executed enough
times to earn a generic plan, and the results go short. If you rely on a partial
index, write the predicate as a constant, or check the plan under
force_generic_plan rather than the one you get interactively.
pgvector’s README treats partial indexing as one rung on a ladder rather than the answer.
“If filtering by only a few distinct values, consider partial indexing.” (pgvector README, read on 2026-09-20)
For many distinct values the ladder continues to partitioning. A single index shared across tenants also couples one tenant’s recall and latency to another’s, which is a reason to separate them beyond query speed.
IVFFlat has different knobs, and ef_search is not one of them
Section titled “IVFFlat has different knobs, and ef_search is not one of them”hnsw.ef_search does nothing to an IVFFlat scan. A reader who tunes it and sees
no change concludes the problem is elsewhere. The equivalent is ivfflat.probes.
“Specify the number of probes (1 by default)” (pgvector README, read on 2026-09-20)
Measured on 2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17
container, an IVFFlat index with lists = 316 over the same corpus, against the
same 5.07% filter and the same 200 queries:
| setting | mean rows for LIMIT 10 | minimum | queries getting all 10 |
|---|---|---|---|
ivfflat.probes = 1 (default) | 9.70 | 0 | 188 of 200 |
ivfflat.probes = 1, hnsw.ef_search raised to 1000 | 9.70 | 0 | 188 of 200 |
ivfflat.probes = 10 | 10.00 | 10 | 200 of 200 |
ivfflat.probes = 1, ivfflat.iterative_scan = relaxed_order | 10.00 | 10 | 200 of 200 |
All four rows are the same IVFFlat index build, because lists centroids are
chosen by k-means and a rebuild moves the numbers.
The second row is the point. Raising hnsw.ef_search by a factor of 25 changed
nothing at all: the same mean, the same minimum, the same 188 queries. The
default truncated 12 of the 200, one of them to zero rows, and only the IVFFlat
knobs fixed it. The ceiling on the iterative version is ivfflat.max_probes,
which that image reported as 32768.
Short results that are not about your filter
Section titled “Short results that are not about your filter”Two rows can go missing with no WHERE clause in sight.
“Also, note that
NULLvectors are not indexed (as well as zero vectors for cosine distance).” (pgvector README, read on 2026-09-20)
Measured on 2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17
container, on a four row table holding one ordinary vector, one other ordinary
vector, one NULL and one zero vector, asking for LIMIT 4 with no filter:
| index | rows returned out of 4 | which rows are missing |
|---|---|---|
HNSW, vector_cosine_ops | 2 | the NULL and the zero vector |
HNSW, vector_l2_ops | 3 | the NULL |
| no index, sequential scan | 4 | none |
The sequential scan shows why: the zero vector’s cosine distance came back as
NaN and the NULL row’s as NULL, so both sort to the end of an exact scan
and are absent from a cosine index entirely. If your pipeline can produce an
empty embedding, this is a silent hole in your search that no amount of
ef_search will fill. Add a CHECK constraint or filter those rows explicitly.
Why does AI-generated code cause this?
Section titled “Why does AI-generated code cause this?”The generated pattern is a vector ORDER BY with a WHERE bolted on, because
that is what the question asked and it is valid SQL. Nothing in the code says the
two clauses interact, and the failure returns fewer rows rather than an error, so
it passes any test that checks the query ran. A test asserting
len(results) == 10 catches it. Almost nobody writes that test.
How do I stop it coming back?
Section titled “How do I stop it coming back?”Assert the row count in the application. If you asked for ten and got two, that is a bug whatever the latency was.
Measure recall too, against an exact answer. Full rows and good rows are
different properties, and the strict_order row above has one without the other.
Fix it in the order the measurements support, which is the order in the quick answer at the top of this page:
- A partial index, if the predicate is one you query constantly. Measured
on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17container, 0.536 ms with all 10 rows, against 4.712 ms for the iterative scan and 26.645 ms for the btree, with the generic-plan trap below. - The iterative scan setting for your index type, otherwise.
hnsw.iterative_scanfor HNSW,ivfflat.iterative_scanandivfflat.probesfor IVFFlat. Measured on 2026-09-20 on that PostgreSQL 17.11pgvector/pgvector:0.8.6-pg17container, 4.712 ms with all 10 rows. Setting the wrong one changes nothing and looks like it should. - A btree on the filter column, as the plan that cannot truncate. Measured
on 2026-09-20 on that PostgreSQL 17.11
pgvector/pgvector:0.8.6-pg17container it answered the 0.1% filter in 0.561 ms, faster than the other plan measured there, and the 5.07% one in 26.645 ms, the slower end of the three-plan table rather than of everything measured at 5.07%, but it is the only one of the three that is exact by construction. Exact does not mean bounded: the sequential scan the planner chose atef_search100 is exact too and means 32.996 ms on the same container and day.
Check the plan under a generic plan if you use a partial index, because a parameterised predicate cannot reach it.
Read Rows Removed by Filter. It is the number that says how much of the
index’s work was thrown away.
Why does my filtered vector search return fewer rows than the LIMIT?
Because an approximate index chooses candidates first and the filter is applied to what it hands up. Measured on 2026-09-20 on PostgreSQL 17.11 with pgvector 0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, 200 queries with a predicate matching 5,074 of 100,000 rows and hnsw.ef_search at its default 40 returned a mean of 2.06 rows for a LIMIT of 10, some of them zero, and not one of the 200 got all ten. There is no error and no warning.
Does raising ef_search fix it?
It changes the plan more than it changes the search. Measured on 2026-09-20 on PostgreSQL 17.11 with pgvector 0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, ef_search 100 did return all ten rows on all 200 queries, but EXPLAIN showed the planner had abandoned the HNSW index for a sequential scan and an exact sort, meaning a mean of 32.996 ms over those 200 queries against 4.712 ms for the iterative scan. The full result came from giving up on the index, not from searching it harder.
What should I set instead?
hnsw.iterative_scan, which is pgvector 0.8 and later. Measured on 2026-09-20 on PostgreSQL 17.11 with pgvector 0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, relaxed_order at the same default ef_search 40 returned all ten rows on all 200 queries at a mean of 4.712 ms, with recall@10 of 0.972 against exact ground truth. strict_order returned all ten too, at recall 0.939, so the stricter setting measured worse on recall here.
Do the same settings work for IVFFlat?
No, and this is a common way to tune nothing. hnsw.ef_search has no effect on an IVFFlat scan. Measured on 2026-09-20 on PostgreSQL 17.11 with pgvector 0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, an IVFFlat index at the default ivfflat.probes of 1 returned a mean of 9.70 rows with a minimum of 0, and 12 of 200 queries came up short. Raising hnsw.ef_search from 40 to 1000 against that same index build changed none of those three numbers. Raising probes to 10, or setting ivfflat.iterative_scan, gave all ten every time.
Can a filtered search return fewer rows for reasons that are not about the filter?
Yes. NULL vectors are never indexed, and zero vectors are not indexed for cosine distance. Measured on 2026-09-20 on PostgreSQL 17.11 with pgvector 0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, a four row table with one NULL and one zero vector returned 2 rows through a cosine HNSW index and 3 through an L2 one, with no filter in the query at all.
Is a partial index the answer?
Often, but confirm the planner can use it. Measured on 2026-09-20 on PostgreSQL 17.11 with pgvector 0.8.6 in a pgvector/pgvector:0.8.6-pg17 container, a partial HNSW index over the 5,074 matching rows was 20 MB against 391 MB and answered in a mean of 0.536 ms with all ten rows. With the predicate written as a parameter instead of a constant, the generic plan could not prove the predicate implied the index, fell back to the full index, and returned a mean of 2.06 rows.