How do you restrict a $vectorSearch to documents matching a metadata condition?

## The stage option `$vectorSearch` accepts a `filter` field next to `path`, `queryVector`, `numCandidates` and `limit`: ```javascript { $vectorSearch: { index: "vector_index", path: "embedding", queryVector: qv, filter: { $and: [ { tenantId: "acme" }, { publishedAt: { $gte: cutoff } } ] }, numCandidates: 300, limit: 10 } } ``` The predicate is expressed in familiar MongoDB query syntax, but it is evaluated by mongot against its own index, not by `mongod` against the collection — which is why it is neither the full query language nor automatically available on every field. ## The index side: filter fields must be declared An Atlas Vector Search index definition is a `fields` array. One entry describes the vector itself — `type: "vector"`, the `path`, `numDimensions` matching the embedding model exactly, and a `similarity` of `euclidean`, `cosine` or `dotProduct`. Every metadata path you intend to filter on needs its own entry with `type: "filter"`. Filterable paths are scalar-shaped: strings, numbers, booleans, dates and objectIds (and arrays of those), which covers tenant ids, languages, statuses, tags and timestamps. Forgetting the declaration is the classic first bug: the vector index looks complete, the query looks correct, and the filter cannot be honoured. Declaring the field costs index space, so declare what you filter on, not every field in the document. ## Why it matters that filtering happens during the search This is the difference between two very different pipelines. **Filtering during the search** — the `filter` option — means the engine only ever accepts qualifying documents as candidates. Ask for `limit: 10` and you get 10 qualifying documents, assuming at least 10 exist and the search reaches them. **Filtering after the search** — a `$match` stage following `$vectorSearch` — means the engine picks its 10 nearest neighbours knowing nothing about your predicate, and then the `$match` throws away those that fail it. If 5% of the corpus belongs to the current tenant, you can expect roughly zero survivors. The failure is quiet and shape-dependent: it looks fine in a demo dataset where one tenant dominates and collapses in production. There is one legitimate use of a trailing `$match`: a predicate on a field you deliberately did not index as a filter field, applied to results you are willing to lose. Treat that as an exception with a comment, not a default. ## Multi-tenancy is an authorization boundary When the filter carries a tenant id, it stops being a relevance hint and becomes a security control. Build it server-side from the authenticated principal, never from client input, and make sure no code path can construct a `$vectorSearch` on that collection without it — a missing filter here leaks another customer's documents into a RAG answer. ## Selectivity and candidate breadth A very restrictive filter interacts with the approximate search: the traversal explores a neighbourhood in which most vectors fail the predicate, so a candidate count that was ample unfiltered can return short of `limit` or with degraded recall. The mitigation is to raise `numCandidates` for heavily filtered query classes, and to measure recall for those classes separately rather than trusting numbers from unfiltered benchmarks. Where a filter partitions the corpus permanently and coarsely, separate collections with their own indexes are sometimes a cleaner answer than one index filtered on every query. ## The parallel in Atlas Search `$search` has the same shape with different spelling: predicates belong in the `filter` clause of the `compound` operator, where mongot applies them during matching and, unlike `must` and `should`, they contribute nothing to the relevance score. Recognising these as the same idea in both stages is what an interviewer is listening for. ## What to say in an interview Name the `filter` option, state the index requirement (`type: "filter"` entries), note that only a subset of operators is supported, and explain the concrete consequence: a trailing `$match` returns fewer than `limit` because it filters a list that was already truncated.