Atlas Vector Search filter fields must be declared in the index or filtering fails

Atlas Vector Search filter fields must be declared in the index or filtering fails

TL;DR

When you create the vector search index, add a filter field for every attribute you plan to filter on (category, year, tenant id, and so on). Put the filter inside $vectorSearch rather than in a downstream $match so the ANN search only considers matching documents. If a filtered query returns nothing, check the index definition first: the missing filter field declaration is the usual cause.

Use this when you run into the situation in the title.

When not to use this skill: unrelated tasks. It covers only the procedure above.

Compatibility

The steps above apply to the commands named in them. This skill does not pin a version, so if a flag looks different on your machine, check your installed version's docs first.

Details

Context: Mongoose Atlas Vector Search docs (grounded in the official MongoDB docs): you can use the filter option inside $vectorSearch to pre-filter documents, but any field you filter on must be declared as a filter field in the index definition (type filter with the field path). Filtering on a field that is not declared as a filter field does not work. The filter accepts standard MongoDB query operators, and pre-filtering narrows the candidate set before the vector comparison, which is both faster and more precise than post-filtering in a later $match.

Source: Mongoose Atlas Vector Search docs (grounded in the official MongoDB docs): you can use the filter option inside $vectorSearch to pre-filter documents, but any field you filter on must be declared as a filter field in the index definition (type filter with the field path). Filtering on a field that is not declared as a filter field does not work. The filter accepts standard MongoDB query operators, and pre-filtering narrows the candidate set before the vector comparison, which is both faster and more precise than post-filtering in a later $match.

Verified resolution: When you create the vector search index, add a filter field for every attribute you plan to filter on (category, year, tenant id, and so on). Put the filter inside $vectorSearch rather than in a downstream $match so the ANN search only considers matching documents. If a filtered query returns nothing, check the index definition first: the missing filter field declaration is the usual cause.

Source URL: https://github.com/automattic/mongoose/blob/HEAD/docs/atlas-vector-search.md