Skip to content

Why are vector results slow after adding a metadata filter?

Last updated

View as Markdown

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 EXPLAIN to 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 larger ef_search is not on the list.

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.

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:

settingobserved default
hnsw.ef_search40
hnsw.iterative_scanoff
hnsw.max_scan_tuples20000
hnsw.scan_mem_multiplier1
ivfflat.probes1
ivfflat.iterative_scanoff
ivfflat.max_probes32768
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_scanef_searchmean rows for LIMIT 10minimumqueries getting all 10recall@10mean ms
off402.0600 of 2000.2023.189
off10010.0010200 of 2001.00032.996
off40010.009199 of 2000.9825.155
relaxed_order4010.0010200 of 2000.9724.712
strict_order4010.0010200 of 2000.9394.820
relaxed_order40010.0010200 of 2000.9835.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.

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_searchplan chosenrowstime, one EXPLAIN run
40Index Scan using items_hnsw25.990 ms
100Seq Scan on items plus a top-N heapsort507481.232 ms
400Index Scan using items_hnsw107.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_tenant
Buffers: shared hit=31443

All 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:

planmean rowsrecall@10mean ms over 200 queries
btree plus top-N heapsort, exact10.001.00026.645
HNSW with relaxed_order at ef_search 4010.000.9724.712
a partial HNSW index on the same predicate10.001.0000.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 indexesplan chosenmean rowsmean ms over 200 queries
btree on the flag plus HNSWIndex Scan on the btree, top-N heapsort10.000.561
HNSW onlySeq Scan plus top-N heapsort10.008.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_tuplesmean rows for LIMIT 10queries getting all 10
5000.102 of 200
20000 (default)1.7033 of 200
2000002.4847 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 writtenindex chosenmean rows for LIMIT 10mean ms over 200 queries
WHERE tenant = 7items_hnsw_t7, the partial index10.000.351
WHERE tenant = $1items_hnsw, the full index2.062.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:

settingmean rows for LIMIT 10minimumqueries getting all 10
ivfflat.probes = 1 (default)9.700188 of 200
ivfflat.probes = 1, hnsw.ef_search raised to 10009.700188 of 200
ivfflat.probes = 1010.0010200 of 200
ivfflat.probes = 1, ivfflat.iterative_scan = relaxed_order10.0010200 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 NULL vectors 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:

indexrows returned out of 4which rows are missing
HNSW, vector_cosine_ops2the NULL and the zero vector
HNSW, vector_l2_ops3the NULL
no index, sequential scan4none

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.

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.

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:

  1. 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-pg17 container, 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.
  2. The iterative scan setting for your index type, otherwise. hnsw.iterative_scan for HNSW, ivfflat.iterative_scan and ivfflat.probes for IVFFlat. Measured on 2026-09-20 on that PostgreSQL 17.11 pgvector/pgvector:0.8.6-pg17 container, 4.712 ms with all 10 rows. Setting the wrong one changes nothing and looks like it should.
  3. 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-pg17 container 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 at ef_search 100 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.