Fast filtered vector search in Elasticsearch: kNN filters and ACORN
A filter beside the knn query runs after the vector search, so a 1% filter keeps about 1% of k. We ran every filter placement at seven selectivities on Elasticsearch 9.5.5, with ACORN on and off, and logged hits and recall.
An Elasticsearch knn filter belongs inside the knn clause, in its filter parameter. There it is a pre-filter: HNSW only collects documents that match, so you get k hits whenever k documents match. A bool filter wrapped around the knn query, or a post_filter, runs after the vector search and keeps only the share of the k neighbours that happen to match, so a 1% filter returns about 0.1 hits out of 10. ACORN, the default filtered-HNSW strategy since 9.1, makes restrictive pre-filters cheaper, but at default num_candidates it also lowered recall in our tests, so set num_candidates yourself and measure.
Everything below ran on Elasticsearch 9.5.5 (Lucene 10.5.1), the docker.elastic.co/elasticsearch/elasticsearch:9.5.5 image, single node, security off. The corpus is BEIR FiQA: 57,638 documents embedded with BAAI/bge-small-en-v1.5 (384 dimensions, normalized, cosine). Each document got a random integer bucket from 0 to 999, independent of its vector, so bucket < N matches about N/10 percent of the index. Two indices, hnsw (float) and the default bbq_hnsw, each one shard, force-merged to one segment. Every number is an average over the first 200 FiQA queries with k: 10, and recall@10 is measured against a NumPy brute-force top 10 over the filtered subset, which matched a filtered script_score query exactly on the queries we cross-checked. This is the same experiment we ran in why OpenSearch k-NN with a filter returns fewer results than k, so the two posts line up row for row.
Where the Elasticsearch knn filter goes
The knn query reference is blunt about it: pre-filtering "is supported through the filter parameter of the knn query", filters from aliases are also pre-filters, and "all other filters found in the Query DSL tree are applied as post-filters". These are the request shapes we ran:
// 1. Pre-filter: filter inside the knn query
{ "size": 10, "query": { "knn": {
"field": "emb", "query_vector": [0.0409, -0.0281, "..."], "k": 10,
"filter": { "range": { "bucket": { "lt": 10 } } } } } }
// 1b. Same pre-filter in the top-level knn search section
{ "size": 10, "knn": {
"field": "emb", "query_vector": [...], "k": 10,
"filter": { "range": { "bucket": { "lt": 10 } } } } }
// 2. bool filter around the knn query (a post-filter)
{ "size": 10, "query": { "bool": {
"must": [ { "knn": { "field": "emb", "query_vector": [...], "k": 10 } } ],
"filter": [ { "range": { "bucket": { "lt": 10 } } } ] } } }
// 3. post_filter
{ "size": 10, "query": { "knn": { "field": "emb", "query_vector": [...], "k": 10 } },
"post_filter": { "range": { "bucket": { "lt": 10 } } } }
The bool version is the one that catches people, because in every other Elasticsearch query a bool.filter narrows what the query can match. Around knn it narrows only what knn already returned.
| Placement | Filter runs | Can return k hits? |
|---|---|---|
knn.filter (query or top-level section) | During the HNSW search | Yes, if k docs match |
| Filtered alias | During the HNSW search | Yes |
bool.filter around knn | After the search | Only for mild filters |
post_filter | After the search | Only for mild filters |
Hit counts at seven filter selectivities
On the float hnsw index with default settings (ACORN on, num_candidates defaulting to 1.5 × k = 15), hits and recall@10 per query:
| Filter | Matching docs | knn.filter | bool filter | post_filter | post_filter, k: 100 |
|---|---|---|---|---|---|
bucket < 700 | 40,403 (70.1%) | 10.00, recall 0.853 | 6.97, 0.639 | 6.97, 0.639 | 10.00, 0.976 |
bucket < 500 | 28,864 (50.1%) | 10.00, 0.768 | 5.07, 0.482 | 5.07, 0.482 | 10.00, 0.964 |
bucket < 400 | 23,139 (40.1%) | 10.00, 0.741 | 3.97, 0.387 | 3.97, 0.387 | 10.00, 0.962 |
bucket < 300 | 17,470 (30.3%) | 10.00, 0.751 | 2.90, 0.285 | 2.90, 0.285 | 10.00, 0.951 |
bucket < 100 | 5,848 (10.1%) | 10.00, 0.738 | 1.07, 0.107 | 1.07, 0.107 | 8.96, 0.849 |
bucket < 10 | 544 (0.94%) | 10.00, 0.456 | 0.11, 0.011 | 0.11, 0.011 | 0.85, 0.085 |
bucket < 1 | 50 (0.09%) | 10.00, 1.000 | 0.01, 0.001 | 0.01, 0.001 | 0.04, 0.004 |
The top-level knn section with a filter returned exactly the same results as the knn query with a filter at every row, on both indices. The bool filter and post_filter columns are identical to each other, which is what the docs predict.
xychart-beta
title "Average hits for k = 10, hnsw, Elasticsearch 9.5.5"
x-axis ["70.1%", "50.1%", "40.1%", "30.3%", "10.1%", "0.94%", "0.09%"]
y-axis "Hits returned" 0 --> 10
bar [10, 10, 10, 10, 10, 10, 10]
line [6.97, 5.07, 3.97, 2.90, 1.07, 0.11, 0.01]Blue bars are knn.filter, the grey line is post_filter (the bool filter line is the same), both from the table above.
The post-filter counts are plain arithmetic: the knn query hands back 10 neighbours and the filter keeps the matching fraction, so the expected count is k × selectivity. At 50.1% that is 5.01 and we measured 5.07; at 10.1% it is 1.01 and we measured 1.07. Raising k to 100 with size: 10 helps until 100 × selectivity drops near 10, and every extra unit of k is more graph work on every shard. It also raised recall on the mild rows above the knn.filter column, which says more about num_candidates: 15 being low than about post-filtering being good. More on that below.
Why filters hurt HNSW
HNSW search is a greedy walk over a proximity graph. With a restrictive filter, most of the nodes on the walk do not match. The older strategy, which Elasticsearch calls fanout, still scores every neighbour it visits and only declines to collect the non-matching ones, so it spends most of its distance computations on documents it will throw away. If it visits more nodes than the filter matches, Lucene gives up on the graph and scores the filtered documents directly.
ACORN-1, from a 2024 paper, changes the walk. Elastic's 9.1 release post puts it as "only nodes that are accepted by the filter are evaluated". When a neighbour fails the filter, the search looks through it to its neighbours instead of scoring it, which keeps the walk connected across gaps in the graph.
flowchart LR
Q(["Query vector"]) --> E["Entry point"]
E --> N1{"Neighbour<br/>matches filter?"}
N1 -- "fanout: either way" --> S1["Score it,<br/>collect only if it matches"]
N1 -- "ACORN: yes" --> S2["Score it and collect"]
N1 -- "ACORN: no" --> H["Skip scoring,<br/>expand to its neighbours"]
H --> N1
S1 --> N1
S2 --> N1Is ACORN the default, and how to turn it off
Yes, for new indices. The switch is the dynamic index setting index.dense_vector.hnsw_filter_heuristic, documented on the index settings page as "Preview since 9.1" with two values: acorn (default) and fanout. A fresh 9.5.5 index reports "index.dense_vector.hnsw_filter_heuristic": "ACORN" under GET <index>/_settings?include_defaults=true, and you can flip it on a live index:
PUT b9-hnsw/_settings
{ "index.dense_vector.hnsw_filter_heuristic": "fanout" }
The docs leave out three details we read from the 9.5.5 source of DenseVectorFieldMapper and Lucene 10.5.1:
- The default depends on the version the index was created with. Indices created before the
DEFAULT_TO_ACORN_HNSW_FILTER_HEURISTICindex version keepfanout, so an index created on 8.x and carried forward has not switched. Check the setting rather than assuming. acornmaps to Lucene'sKnnSearchStrategy.Hnsw(60)andfanouttoHnsw(0). Lucene uses the filtered searcher only when the share of the segment's graph that passes the filter is below that percentage. So ACORN applies only to filters matching under 60% of a segment. Our 70.1% row gave identical results and identical vector-operation counts under both settings, which is what that rule predicts.- It applies only where there is an HNSW graph:
hnsw,int8_hnsw,int4_hnswandbbq_hnsw.flattypes are brute force anyway, andbbq_diskis partition-based (see bbq_hnsw vs bbq_disk).
ACORN vs fanout, measured
The same knn.filter queries under each heuristic, at default settings. Recall@10 first, then the average vector_operations_count the profile API reports for the top-level knn search (a count of distance computations, which is the work ACORN is meant to cut):
| Filter | hnsw ACORN | hnsw fanout | bbq_hnsw ACORN | bbq_hnsw fanout |
|---|---|---|---|---|
| 70.1% | 0.853 / 468 | 0.853 / 468 | 0.834 / 802 | 0.834 / 802 |
| 50.1% | 0.768 / 567 | 0.865 / 551 | 0.791 / 1,002 | 0.838 / 940 |
| 30.3% | 0.751 / 521 | 0.858 / 670 | 0.779 / 910 | 0.839 / 1,078 |
| 10.1% | 0.738 / 349 | 0.775 / 779 | 0.773 / 583 | 0.821 / 1,256 |
| 0.94% | 0.456 / 175 | 1.000 / 544 | 0.548 / 238 | 0.956 / 574 |
| 0.09% | 1.000 / 50 | 1.000 / 50 | 0.999 / 80 | 0.999 / 80 |
At the 10.1% filter ACORN did 45% of fanout's distance computations on hnsw (349 against 779) and 46% on bbq_hnsw. Elastic reports "typical speedups of 5x" for ACORN in the 9.1 post; on a 57k-document index we saw about half the work, and our laptop latencies (p50 around 1 to 3 ms for every configuration, client wall time) were too small and noisy to show any difference. Treat them as relative at best.
The cost is recall at the default num_candidates. The index settings docs warn that with acorn, "num_candidates might need to be increased for exceptionally high recall requirements". On this corpus it needed increasing for ordinary ones. The 0.94% row is the clearest case: fanout ended with exactly 544 operations, one per matching document, and recall 1.0, the signature of Lucene's exact fallback after the graph walk hits its visit limit. ACORN found 10 matches within 175 operations, so it never fell back, and returned 0.456.
So we swept num_candidates on the float index:
| Filter | num_candidates | ACORN recall / ops | fanout recall / ops |
|---|---|---|---|
| 50.1% | 15 (default) | 0.768 / 567 | 0.865 / 551 |
| 50.1% | 100 | 0.937 / 1,929 | 0.963 / 1,500 |
| 50.1% | 200 | 0.962 / 2,766 | 0.977 / 2,212 |
| 10.1% | 15 (default) | 0.738 / 349 | 0.775 / 779 |
| 10.1% | 50 | 0.865 / 675 | 0.892 / 1,441 |
| 10.1% | 100 | 0.902 / 956 | 0.946 / 2,154 |
| 10.1% | 200 | 0.925 / 1,301 | 0.972 / 3,493 |
| 0.94% | 50 | 1.000 / 544 | 1.000 / 544 |
xychart-beta
title "Recall@10 at a 10.1% filter by num_candidates, hnsw, ES 9.5.5"
x-axis ["15", "50", "100", "200"]
y-axis "Recall@10" 0.7 --> 1.0
line [0.7375, 0.865, 0.902, 0.9245]
line [0.7745, 0.8915, 0.946, 0.9715]Blue is ACORN, grey is fanout, from our sweep.
At a 10.1% filter, ACORN at num_candidates: 100 (0.902, 956 operations) beat fanout at 50 (0.892, 1,441 operations). At matched recall ACORN did roughly two-thirds of the work. At a 50.1% filter it did more work than fanout for less recall at every setting we tried, which is close to the 60% line where Lucene stops using it. bbq_hnsw followed the same pattern with a lower ceiling, because only k × oversample candidates get rescored, as covered in tuning num_candidates and oversampling.
When Elasticsearch falls back to exact search
The docs do not spell this out. Elasticsearch's ESKnnFloatVectorQuery extends Lucene's KnnFloatVectorQuery without overriding the per-segment logic, so the rules are Lucene's, from AbstractKnnVectorQuery.getLeafResults in 10.5.1. Here "k" is the per-segment candidate count Elasticsearch passes down, which is num_candidates (or k × oversample on BBQ when larger):
flowchart TD
A["knn query with filter,<br/>per segment"] --> B{"Matching docs at or<br/>below num_candidates?"}
B -- yes --> X["Exact search over<br/>the matching docs"]
B -- no --> H["Filtered HNSW, visit limit<br/>= matching docs + 1"]
H --> C{"Visit limit hit, or<br/>fewer than num_candidates found?"}
C -- yes --> X
C -- no --> R["Return HNSW results"]That fits the 0.09% row: 50 matching documents is above num_candidates 15, so HNSW ran first, and both heuristics ended with an operation count equal to the 50 matching documents and recall 1.0, which is what the exact pass leaves behind. It also means the exact fallback is a small-index effect. A 1% filter on a 10M-document segment matches 100,000 documents, far above any visit limit you would set, so HNSW recall is all you get, and num_candidates is the dial. On bbq_hnsw even the exact path topped out at 0.956 at 0.94%, consistent with the exact pass scoring quantized vectors and rescoring only the top 30.
If you need exact results for a filter you know is small, say so explicitly with a script_score over a filtered bool, or a flat index type for that data.
Similarity thresholds
knn also takes similarity, a minimum on the raw similarity, not the score. For cosine, the score is (1 + cos) / 2, so a score of 0.9004 is a cosine of 0.8009. On our first query with the 10.1% filter and num_candidates: 100, similarity: 0.75 returned 2 hits and 0.8 returned 1, matching the two true cosines above 0.75 (0.8009 and 0.7567). A threshold combined with a filter can legitimately return fewer than k, so do not mistake it for a post-filter bug.
A multi-tenant filter pattern
For per-tenant search, the docs' rule that alias filters are pre-filters gives a clean pattern: one filtered alias per tenant, and the application queries the alias with no filter of its own.
POST _aliases
{ "actions": [ { "add": { "index": "b9-hnsw", "alias": "acme-docs",
"filter": { "term": { "tenant": "tenant-042" } } } } ] }
Our synthetic tenant-042 holds 581 documents (1%). Over 200 queries, knn against the alias returned 10 hits every time, identical to a knn.filter on the same term, while a bool filter on the term returned 25 hits in total, 0.125 per query. The alias also stops a client from forgetting the tenant filter. At 1% per tenant you are in ACORN's best range, so set num_candidates accordingly. If most of your tenants are tiny, a different layout may fit better; we compare the options for another engine in Qdrant multitenancy design.
What changes in 9.6
Elastic's October 2026 post, Faster kNN filters in Elasticsearch, describes Elasticsearch deciding per query whether to apply a broad filter after the vector search, with a fallback to pre-filtering so you still get k results. It is controlled by index.dense_vector.post_filter_selectivity_threshold, which the post says defaults to 0.7 and is "scheduled to be on by default in Elasticsearch 9.6". On 9.5.5 the setting exists with a default of 1.0 (off), and PUT _settings rejects it with can not update private setting [index.dense_vector.post_filter_selectivity_threshold]; this setting is managed by Elasticsearch. Your queries do not change either way: keep the filter in knn.filter and let the engine pick.
A test plan for filtered kNN
Our recommendation is to keep filters inside knn.filter or a filtered alias, keep ACORN, and set num_candidates explicitly instead of relying on 1.5 × k. Switch to fanout only if measurement on your own data shows it wins at the recall you need. To get there:
- Grep query builders for
knninside aboolwith a siblingfilter, and forknnnext to apost_filter. Move those filters intoknn.filter. - Read
index.dense_vector.hnsw_filter_heuristicwithinclude_defaults=trueon every vector index. Old indices may still be onfanout. - Bucket production filters by selectivity per segment: above 60%, 5% to 60%, and below 5%.
- Build exact ground truth for a few hundred real queries per bucket with a filtered
script_score. - Sweep
num_candidatesper bucket under both heuristics, recording recall@10,vector_operations_countfromprofileand p95 latency on production hardware. - Re-run after merges or reindexing, since segment size moves both the 60% rule and the exact fallback.
A retriever that silently returns 1 document out of 10 is a common reason an agent is only as good as its retriever. If you are choosing between engines, the filtering behaviour of each is one of the rows in our Elasticsearch vs OpenSearch comparison.
Where we can help
We audit Elasticsearch vector search for teams with filtered retrieval in production: find the queries that post-filter, then measure recall before and after moving each filter into knn.filter. Our Elasticsearch query performance work for AlphaSense made their search 90% faster; that was general query tuning, separate from filtered kNN. The same team handles this through our Elasticsearch consulting service.
Abhilash B is an advisor at Query Quotient and an information retrieval and AI expert who holds patents in the field. Abhilash brings that retrieval depth to the search, RAG and agent systems Query Quotient builds for clients.
