Vector Search

Table of Contents

• Vector Search Index Definition
• Index Configuration Parameters
• Filter Fields (Pre-filtering)
• Query Construction
• Query Optimization

Vector Search Index Definition

Syntax

MongoDB Vector Search index definitions have the following structure:

Note: The exact syntax for creating indexes varies by driver/interface. The above shows the core index definition structure that applies across all methods.

Basic Definition

Most vector search indexes only need the vector field:

Index Configuration Parameters

Required: numDimensions

Definition: Number of dimensions in your vector embeddings. MongoDB enforces this at both index-time and query-time.

Constraints:

• Must be less than or equal to 8192
• For int1 (binary) vectors: MUST be a multiple of 8
• For int8 vectors: 1 to 8192
• For float32 vectors: 1 to 8192

How to Determine:

• The embedding model determines this value
• It MUST match the actual dimension count of your vectors
• Cannot be changed after index creation (requires dropping and recreating index)

Example - Voyage AI Models:

• voyage-3-large: 2048 dimensions
• voyage-4: Configurable output dimensions (256, 512, 1024, 2048, 4096)

Required: similarity

Definition: The similarity function used to compare vectors and rank results.

Available Options:

Decision Process:

1. Check your embedding model documentation for recommended similarity function
2. If model produces normalized vectors -> use dotProduct (fastest)
3. If model does NOT normalize vectors -> use cosine
4. If using binary quantization (int1) -> MUST use euclidean
5. When uncertain -> start with dotProduct and normalize your vectors

Notes:

• All functions return scores in range [0, 1] where 1 = most similar
• dotProduct is most efficient but requires normalized vectors
• Check embedding model documentation for recommendations

Optional: quantization

Definition: Automatic vector compression to reduce storage and improve query speed at the cost of some accuracy.

Syntax:

Options:

Important Rules:

• none: Default if omitted. Use for pre-quantized vectors (int1, int8)
• scalar: Transforms float32/double values to 1-byte integers
• binary: Transforms values to single bit. numDimensions MUST be multiple of 8
• Binary quantization REQUIRES euclidean similarity
• Only use with float32 or double vectors (NOT with pre-quantized int1/int8)

Example:

Optional: hnswOptions (Preview Feature)

Definition: Parameters for the Hierarchical Navigable Small Worlds graph construction algorithm.

Warning: Modifying default values might negatively impact your index and queries. Use with caution.

Syntax:

Parameters:

maxEdges (16-64, default: 16):

• Maximum number of connections per node in the graph
• Higher values:
  • Better recall (finds more relevant results)
  • Slower queries (more neighbors to evaluate)
  • More memory usage (more connections stored)
  • Slower indexing (more neighbors to adjust)

numEdgeCandidates (100-3200, default: 100):

• Maximum nodes evaluated to find best connections for new nodes
• Higher values:
  • Better graph quality (improves search accuracy)
  • Can negatively affect query latency

Recommendation: Leave at defaults unless you have specific performance requirements and understand the trade-offs.

Filter Fields (Pre-filtering)

About Filter Fields

Definition: Additional fields indexed to enable pre-filtering before vector similarity computation. This narrows the search scope and improves performance.

Use Case: Filter by specific criteria (e.g., category, date range, user ID) BEFORE computing vector similarity.

Performance: Filtering before similarity computation is much faster than post-filtering with $match.

Supported Field Types: boolean, date, objectId, numeric (int32, int64, double), string, UUID, and arrays of these types.

Syntax

When to Use Filter Fields

Use filter fields when:

• You need to filter by exact values (category = “Action”)
• You need range filtering (year >= 2020)
• Filter criteria are known at query time
• You want maximum query performance (filters before computing similarity)
• You have multi-tenant data that needs isolation

Use post-filtering ($match) when:

• Filters are ad-hoc and change frequently
• Complex aggregation logic is needed
• Fields are not worth indexing (rarely used)
• Combining with other aggregation stages

Supported Filter Operators

MongoDB Vector Search supports the following MQL operators in the filter option:

Note: Other query operators, aggregation pipeline operators, and MongoDB Search operators are NOT supported in the filter option.

Filter Examples

Index with filter fields:

Query with single filter:

Query with multiple filters using $and:

Short form of $eq (recommended):

Important Notes

Pre-filtering does NOT affect scores: The vectorSearchScore returned for documents is based only on vector similarity, not on how well they matched the filter criteria.

Filter fields must be indexed: You must add fields as type “filter” in your index definition to use them in the filter option. Fields not indexed cannot be used for pre-filtering.

Arrays are supported: You can filter on fields that contain arrays. MongoDB automatically handles array matching.

Query Construction

$vectorSearch Stage

Definition: The $vectorSearch stage performs semantic search for a query vector on indexed vector fields. It must be the first stage in an aggregation pipeline.

Requirements:

• Atlas cluster running MongoDB v6.0.11, v7.0.2, or later
• A vector search index on the collection with vector-type fields
• $vectorSearch MUST be the first stage in the pipeline

Basic Query Syntax

Required Fields

index (String, Required):

• Name of the MongoDB Vector Search index to use
• MongoDB returns no results if the index name is misspelled or doesn’t exist
• Must match the name specified when creating the index

path (String, Required):

• Name of the indexed vector field to search
• Must be a field indexed as type “vector” in your index definition
• Use dot notation for nested fields (e.g., “metadata.embedding”)

queryVector (Array of Numbers, Required):

• Array of numbers representing your query vector
• Can be float32, BSON BinData float32, or BSON BinData int1/int8
• Array size MUST match numDimensions specified in the index
• You must use the same embedding model that generated the indexed vectors

limit (Integer, Required):

• Number of documents to return in results
• Must be an integer value
• Cannot exceed numCandidates if numCandidates is specified

Conditional Fields

numCandidates (Integer, Conditional):

• Number of nearest neighbors to use during ANN search
• Required if exact is false or omitted
• Must be less than or equal to 10000
• Cannot be less than limit
• Recommended: Set to at least 20x the limit value for good recall

Example:

Optional Fields

filter (Object, Optional):

• MQL expression to pre-filter documents before vector search
• Only works with fields indexed as type “filter”
• Supported operators: $eq, $ne, $gt, $lt, $gte, $lte, $in, $nin, $exists, $and, $or, $not, $nor
• See Filter Fields section for details and examples

exact (Boolean, Optional):

• Set to true for ENN (Exact Nearest Neighbor) search
• Set to false or omit for ANN (Approximate Nearest Neighbor) search
• Default: false

ENN vs ANN:

• ANN (default): Faster, uses HNSW algorithm, good for large datasets, 90-95% recall
• ENN: Exhaustive search, guaranteed exact matches, slower, use for small datasets (less than 10K docs) or measuring accuracy baseline

Complete Query Examples

Basic ANN query:

ANN query with pre-filtering:

ENN query (exact search):

Retrieving Vector Search Scores

Use $meta: "vectorSearchScore" in a $project stage to include similarity scores:

Important:

• Scores are in range [0, 1] where 1 = most similar
• You can ONLY use vectorSearchScore after a $vectorSearch stage
• Pre-filtering does NOT affect the score (only vector similarity affects score)

Post-filtering with $match

For ad-hoc filters or complex logic not indexed as filter fields, use $match after $vectorSearch:

Performance Note: Post-filtering is slower than pre-filtering because it computes similarity for all candidates first.

Query Optimization

numCandidates Tuning

Definition: The numCandidates parameter controls the trade-off between recall (finding relevant results) and query performance in ANN searches.

Rule of Thumb: A good starting point is 20x your limit value. You can adjust between 10-20x (or higher) based on your recall and performance requirements.

Example:

When to Adjust numCandidates

Increase when:

• Search results miss relevant documents
• Large dataset (millions of vectors)
• Using quantized vectors (int8 or int1)
• Heavy pre-filtering is applied

Decrease when:

• Queries are too slow and results are already good
• Small dataset (thousands of vectors)
• Speed is more important than perfect recall

Note on low limit values: A very low limit (e.g., 5) may need proportionally higher numCandidates (e.g., 40x) to maintain recall.

Test and Measure

• Start with 20x limit and run sample queries
• Check result quality and query latency
• Adjust up or down based on your accuracy vs performance requirements

ANN vs ENN Search

ANN (Approximate Nearest Neighbor):

• Default search method
• Uses HNSW algorithm for fast approximate search
• Typically 90-95% recall (finds 90-95% of exact matches)
• Much faster than ENN for large datasets
• Requires numCandidates parameter

Use ANN when:

• You have production queries
• Dataset is large (more than 10K documents)
• 90-95% recall is acceptable
• Query speed is important

ENN (Exact Nearest Neighbor):

• Exhaustive search of all indexed vectors
• Guaranteed to find exact best matches
• Much slower than ANN
• Set exact: true in query
• Does NOT require numCandidates parameter
• Uses full-fidelity vectors even when quantization is enabled

Use ENN when:

• Measuring accuracy baseline (ground truth for testing)
• Collection has less than 10K documents
• Very selective filters (less than 5% of data matches)
• You need guaranteed best matches

Pre-filtering vs Post-filtering Performance

Pre-filtering (filter option):

• Fastest: Filters BEFORE computing similarity
• Use for exact matches, range queries, known criteria
• Requires fields indexed as type “filter”
• Limited to supported MQL operators ($eq, $ne, $gt, $lt, $gte, $lte, $in, $nin, $exists, $and, $or, $not, $nor)

Post-filtering ($match stage):

• Slower: Computes similarity for all candidates first
• Use for ad-hoc filters, complex logic, unindexed fields
• Full MQL operator support
• Can combine with other aggregation stages

Recommendation: Use pre-filtering whenever possible for best performance. Reserve post-filtering for complex or ad-hoc queries.

Parallel Query Execution

MongoDB Vector Search parallelizes query execution across segments when running on dedicated search nodes, which can improve response time for queries on large datasets.

Notes:

• Works automatically on dedicated search nodes
• High-CPU systems provide more performance improvement
• Not guaranteed for every query (e.g., when too many concurrent queries are queued)
• May cause slight inconsistencies in results for successive identical queries

If you see inconsistent results: Increase numCandidates to improve consistency.

Best Practices Summary

1. Start with numCandidates = 20x limit: Provides good balance of recall and performance
2. Use pre-filtering when possible: Index filter fields for known filtering criteria
3. Choose appropriate similarity function: Match your embedding model’s recommendations
4. Consider quantization for large datasets: Use scalar or binary quantization for 10M+ vectors
5. Use ANN for production: Reserve ENN for testing/small datasets
6. Test with your data: Run sample queries and measure recall vs latency
7. Monitor and adjust: Use query performance metrics to tune numCandidates
8. Match query vectors to index: Use the same embedding model and dimensions

Vector Search on Views

Version requirements, supported stages, limitations, and troubleshooting are identical to Atlas Search on Views — see lexical-search-indexing.md. The difference is using a vectorSearch-type index and querying with $vectorSearch.

Example: partial index (exclude documents without embeddings)