How does the filter inside an Elasticsearch knn search differ from a post_filter?

## Three places a constraint can live Given a kNN search and a constraint like `status: published`, there are three syntactically similar places to put it, and they behave completely differently. **Inside the knn clause (`knn.filter`) — a pre-filter.** The filter is evaluated during graph traversal. Only matching documents are eligible to enter the candidate queue, so the search returns k neighbours that all match. This is almost always what you want. **As `post_filter` — a post-filter.** kNN runs unconstrained, produces its k nearest neighbours, and then the filter deletes the ones that do not match. If only 20% of your corpus is published, a k of 10 typically yields around two hits, and there is no mechanism to backfill. The result count becomes a random variable driven by how the vectors happen to be distributed. **As a sibling `query` to a top-level `knn`.** This looks like an AND but is not one. The `knn` clause and the `query` clause are executed separately, their result sets are combined, and the scores are added. A document matching only the query still appears; a kNN neighbour failing the query still appears. Candidates routinely write this expecting an intersection and get a union. ## Why pre-filtering is hard, and what Lucene does about it HNSW works because the graph's edges encode proximity: a greedy walk toward the query vector converges quickly. Filtering breaks that assumption. If the eligible documents are scattered thinly across the vector space, the walk spends its budget stepping through ineligible neighbourhoods, and the bounded candidate queue fills with dead ends. Recall degrades, sometimes sharply, exactly when the filter is most selective. Lucene mitigates this with a fallback: when the filter matches few enough documents relative to the work the graph search would do, it abandons approximate search and performs an **exact** comparison over just the matching documents. Brute-forcing a few hundred vectors is cheap and gives perfect recall, so this is a strictly better outcome. The pathological zone is in between — a filter selective enough to hurt the graph walk but broad enough that brute force is still expensive. Practical consequences: - Measure recall for **filtered** traffic separately from unfiltered traffic. They are different workloads with different tuning. - Filtered searches usually need a larger `num_candidates` than unfiltered ones to hit the same recall, because non-matching candidates consume traversal budget without filling the top-k. - Very high-cardinality per-user filters (one tenant per document, thousands of tenants) are a known bad fit for a single shared graph. Routing tenants to their own shards or indices, so each graph contains mostly eligible documents, often beats fighting the filter. ## Writing the filter The `knn` filter takes a normal query, and it runs in filter context — no scoring, cacheable. Keep it to `term`, `terms`, `range` and boolean combinations over `keyword`, numeric and date fields. Putting an expensive scripted condition there means paying it during traversal, once per candidate considered, which is a very different cost profile than paying it once per matching document in a normal search. Security filters deserve a note: document-level security is applied by Elasticsearch itself and constrains what a user can see, so it behaves as a constraint on the candidate set rather than as something you can forget to add. It has the same recall implications as any other selective pre-filter. ## Diagnosing the symptom in production "The kNN search returns fewer results than k" has a short list of causes, and you can walk it quickly: 1. A `post_filter` is trimming the list — move the constraint into `knn.filter`. 2. The filter is so selective that fewer than k documents match at all — no configuration fixes that. 3. The index genuinely holds fewer than k vectors on some shards. "The kNN search returns the wrong neighbours when filtered" is the recall problem instead: compare against an exact baseline over the filtered set, raise `num_candidates`, and if that is not enough, revisit `m` and the quantization choice. ## The one-line summary Pre-filter to constrain the search, post-filter only when you deliberately want the unfiltered neighbourhood computed first (for example to keep aggregation facets over the full neighbourhood), and never assume a sibling `query` clause narrows a kNN search.