vector-search-type

vector-search-type

For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!-- Tab options on this page. Append to the .md URL to filter: ?tabs=<id,...> select specific tabs (e.g. ?tabs=nodejs,shell) ?allTabs=true include every tab (no param) default: one tab per tabset

Available tabs: other tabs: cosine, dotproduct, euclidean, dotProduct, vib, jsonib, basic, advanced, Single Index, Multiple Indexes, async, sync, flat, nested-root, filter -->

How to Index Fields for Vector Search

To run [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch queries against data in your cluster, you must create a vectorSearch type index on each collection that you want to query. You can configure the following types for each field that you index in a vectorSearch index:

vector type to index a field containing vector embeddings that capture the semantic meaning of the text data that you want to query.
filter type to index a field for pre-filtering your data. Filtering your data is useful to narrow the scope of your semantic search, such as in a multi-tenant environment.

Note:

You can't use the [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search stage, [vectorSearch](https://www.mongodb.com/docs/search/query/operators-collectors/vectorSearch.md#std-label-fts-vectorSearch-ref operator, or the deprecated [knnBeta](https://www.mongodb.com/docs/search/query/operators-collectors/knn-beta.md#std-label-knn-beta-ref operator to query fields indexed using the vectorSearch type index definition.

autoEmbed type to index a text field for which you want MongoDB Vector Search to automatically generate vector embeddings using Voyage AI models.
filter type to index a field for pre-filtering your data. Filtering your data is useful to narrow the scope of your semantic search, such as in a multi-tenant environment.

vector type to index a field containing vector embeddings that capture the semantic meaning of the text data that you want to query.
filter type to index a field for pre-filtering your data. Filtering your data is useful to narrow the scope of your semantic search, such as in a multi-tenant environment.

Note:

Important:

Automated Embeddings is available as a Preview feature. The feature and the corresponding documentation might change at any time during the Preview period. Do not use this feature in your production environment. We do not use any customer data from this feature to train our models at this time. To learn more, see Preview Features.

autoEmbed type to index a text field for which you want MongoDB Vector Search to automatically generate vector embeddings using Voyage AI models.
filter type to index a field for pre-filtering your data. Filtering your data is useful to narrow the scope of your semantic search, such as in a multi-tenant environment.

Considerations

In a vectorSearch type index definition, you can index arrays with only a single element. You can't index embedding fields inside arrays of documents or embedding fields inside arrays of objects. You can index embedding fields inside documents using dot notation. The same embedding field can't be indexed multiple times in the same index defintion.

Before indexing your embeddings, we recommend converting your embeddings to BSON (Binary Javascript Object Notation) [BinData](https://www.mongodb.com/docs/manual/reference/method/BinData.md#std-label-server-binData-method vectors with subtype float32, int1, or int8 for efficient storage in your cluster. To learn more, see [how to convert your embeddings to BSON vectors.](https://www.mongodb.com/docs/vector-search/about/vector-quantization.md#std-label-avs-bindata-vector-subtype

When you use MongoDB Vector Search indexes, you might experience elevated resource consumption on an idle node for your Atlas cluster. This is due to the underlying [mongot](https://www.mongodb.com/docs/search/query/query-ref.md#std-label-about-mongot process, which performs various essential operations for MongoDB Vector Search. The CPU utilization on an idle node can vary depending on the number, complexity, and size of the indexes.

To learn more about sizing considerations for your indexes, see [Memory Requirements for Indexing Vectors.](https://www.mongodb.com/docs/vector-search/deployment/deployment-options.md#std-label-avs-index-memory-requirements

If you make changes to the collection for which you defined a MongoDB Vector Search index, the latest data might not be available immediately for queries. However, mongot monitors the change streams and updates stored copies of data, making MongoDB Vector Search indexes eventually consistent. You can view the number of indexed Documents in the Atlas UI to verify that changes to the collection are reflected in the index.

Alternatively, you can create a new index after adding new documents to your collection and wait for the index to become queryable. You can also implement a polling logic similar to the following to ensure that the index is ready for querying before attempting to use it.

Example:

console.log("Polling to check if the index is ready. This may take up to a minute.")
let isQueryable = false;
while (!isQueryable) {
  const cursor = collection.listSearchIndexes();
  for await (const index of cursor) {
    if (index.name === result) {
      if (index.queryable) {
        console.log(`${result} is ready for querying.`);
        isQueryable = true;
      } else {
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }
  }
}

You can configure MongoDB Vector Search to automatically generate and manage vector embeddings for the text data in your collection and run [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch queries against the generated embeddings. You can create a MongoDB Vector Search index with type autoEmbed and choose from available Voyage AI embedding models to generate embeddings, simplifying indexing, updating, and querying with vectors.

When you configure Automated Embedding, MongoDB Vector Search automatically generates embeddings using the specified embedding model at index-time for the specified text field in your collection, during updates, and at query-time for your query text against the field indexed for automated embeddings.

You can also index additional fields in your collection for [pre-filtering](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-filter-auto-embed your data. Filtering your data is useful to narrow the scope of your semantic search.

Embeddings

The embeddings are generated on the search process, which might be computationally expensive. You might have to enable auto-scaling to handle the increased load during first-time index build.

Embeddings are stored on your MongoDB cluster. The storage size of the embeddings depends on the index settings like quantization and number of dimensions. You must ensure that there is sufficient disk space available on your cluster to store the embeddings.

The embedding model inference platform runs on MongoDB's infrastructure in Google Cloud in a US region.

Billing

The pricing of embedding model used for generating embeddings is based on the number of tokens in your text field and queries. See [Billing for Automated Embedding](https://www.mongodb.com/docs/vector-search/crud-embeddings/automated-embedding/billing.md#std-label-auto-embed-billing for more details.

Querying

You must use the [$vectorSearch](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch stage to query fields indexed as the autoEmbed type.

Note:

You can't use the [$search](https://www.mongodb.com/docs/search/query/aggregation-stages/search.md#mongodb-pipeline-pipe.-search [vectorSearch](https://www.mongodb.com/docs/search/query/operators-collectors/vectorSearch.md#std-label-fts-vectorSearch-ref or the deprecated [knnBeta](https://www.mongodb.com/docs/search/query/operators-collectors/knn-beta.md#std-label-knn-beta-ref operator to query fields indexed using the vectorSearch type index definition.

See also, [Index Limitations.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-index-limitations

If your collection already has embeddings, you must use the vector type fields to index the embeddings. In a vectorSearch type index definition, you can index arrays with only a single element. You can't index embedding fields inside arrays of documents or embedding fields inside arrays of objects. You can index embedding fields inside documents using dot notation. The same embedding field can't be indexed multiple times in the same index definition.

If you make changes to the collection for which you defined a MongoDB Vector Search index, the latest data might not be available immediately for queries. However, mongot monitors the change streams and updates stored copies of data, making MongoDB Vector Search indexes eventually consistent. You can implement a polling logic similar to the following to ensure that the index is ready for querying before attempting to use it.

Example:

console.log("Polling to check if the index is ready. This may take up to a minute.")
let isQueryable = false;
while (!isQueryable) {
  const cursor = collection.listSearchIndexes();
  for await (const index of cursor) {
    if (index.name === result) {
      if (index.queryable) {
        console.log(`${result} is ready for querying.`);
        isQueryable = true;
      } else {
        await new Promise(resolve => setTimeout(resolve, 5000));
      }
    }
  }
}

If you want to generate embeddings for text data in your collection, you can use the autoEmbed type to index a field with text data. You must have a Voyage AI API (Application Programming Interface) key to generate the embeddings.

API Keys

To automatically generate embeddings for your data using state-of-the-art Voyage AI models, MongoDB Vector Search uses the API (Application Programming Interface) key that you provided during deployment of mongot to authenticate to the Voyage AI endpoint.

You can generate and manage model API keys directly from the Atlas UI. To learn more about generating and managing API (Application Programming Interface) keys including [configuring the rate limits](https://www.mongodb.com/docs/voyageai/management/rate-limits.md#std-label-voyage-rate-limits (which is a combination of TPM (Tokens Per Minute) and RPM (Requests Per Minute)) and [monitoring API key usage](https://www.mongodb.com/docs/voyageai/management/monitor-usage.md#std-label-voyage-monitor-usage, see [Model API Keys.](https://www.mongodb.com/docs/voyageai/management/api-keys.md#std-label-voyage-manage-api-keys

Alternatively, you can generate the API (Application Programming Interface) key directly from Voyage AI. If you generate Voyage AI API (Application Programming Interface) key directly from Voyage AI, to learn more about managing the API (Application Programming Interface) keys, see API Keys.

Billing

Voyage AI model pricing is usage-based, with charges billed to the account linked to the API (Application Programming Interface) key used for access. Pricing is based on the number of tokens in your text field and queries.

If you generated the API (Application Programming Interface) key using your Atlas account, you can monitor API (Application Programming Interface) key usage from the Atlas UI. To learn more, see [Billing.](https://www.mongodb.com/docs/voyageai/management/billing.md#std-label-voyage-billing

If you generated Voyage AI API (Application Programming Interface) key directly from Voyage AI, see Pricing to learn more about the charge for requests to the Voyage AI embedding endpoint.

Querying

Note:

Syntax

The following syntax defines a vector type MongoDB Vector Search index:

{
  "fields":[
    {
      "type": "vector",
      "path": "<field-to-index>",
      "numDimensions": <number-of-dimensions>,
      "similarity": "euclidean | cosine | dotProduct",
      "quantization": "none | scalar | binary",
      "indexingMethod": "flat | hnsw",
      "hnswOptions": {
        "maxEdges": <number-of-connected-neighbors>,
        "numEdgeCandidates": <number-of-nearest-neighbors>
      }
    },
    {
      "type": "filter",
      "path": "<field-to-index>"
    },
    ...
  ],
  "nestedRoot": "<embedded-document-field-name>",
  "storedSource": {
    "include|exclude": ["<field-name>",...]
  }
}

The following syntax defines a vector type MongoDB Vector Search index:

{
  "fields":[
    {
      "type": "vector",
      "path": "<field-to-index>",
      "numDimensions": <number-of-dimensions>,
      "similarity": "euclidean | cosine | dotProduct",
      "quantization": "none | scalar | binary",
      "indexingMethod": "flat | hnsw",
      "hnswOptions": {
        "maxEdges": <number-of-connected-neighbors>,
        "numEdgeCandidates": <number-of-nearest-neighbors>
      }
    },
    {
      "type": "filter",
      "path": "<field-to-index>"
    },
    ...
  ],
  "nestedRoot": "<embedded-document-field-name>",
  "storedSource": {
    "include|exclude": ["<field-name>",...]
  }
}

The following syntax defines an autoEmbed type MongoDB Vector Search index:

{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "<field-name>",
      "model": "voyage-4-large | voyage-4 | voyage-4-lite | voyage-code-4 | voyage-code-3",
      "numDimensions": 256 | 512 | 1024 | 2048,
      "quantization": "float | scalar | binary | binaryNoRescore",
      "similarity": "dotProduct | cosine | euclidean",
      "indexingMethod": "flat | hnsw",
      "hnswOptions": {
        "maxEdges": <number-of-connected-neighbors>,
        "numEdgeCandidates": <number-of-nearest-neighbors>
      }
    },
    {
      "type": "filter",
      "path": "<field-to-index>"
    },
    ...
  ],
  "nestedRoot": "<embedded-document-field-name>"
}

The following syntax defines an autoEmbed type MongoDB Vector Search index:

{
  "fields": [
    {
      "type": "autoEmbed",
      "modality": "text",
      "path": "<field-name>",
      "model": "voyage-4-large | voyage-4 | voyage-4-lite | voyage-code-3",
      "numDimensions": 256 | 512 | 1024 | 2048,
      "quantization": "float | scalar | binary | binaryNoRescore",
      "similarity": "dotProduct | cosine | euclidean",
      "indexingMethod": "flat | hnsw",
      "hnswOptions": {
        "maxEdges": <number-of-connected-neighbors>,
        "numEdgeCandidates": <number-of-nearest-neighbors>
      }
    },
    {
      "type": "filter",
      "path": "<field-to-index>"
    },
    ...
  ]
}

MongoDB Vector Search Index Fields

The MongoDB Vector Search index definition takes the following fields:

Option	Type	Necessity	Purpose
`fields`	Array of field definition documents	Required	Definitions for the vector and filter fields to index, one definition per document. Each field definition document specifies the `type`, `path`, and other configuration options for the field to index. The `fields` array must contain at least one `vector`-type field definition. You can add additional `filter`-type field definitions to your array to pre-filter your data.
fields.``type	String	Required	Field type to use to index fields for [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch. You can specify one of the following values: `vector` - for fields that contain vector embeddings.; `filter` - for additional fields to filter on. You can filter on boolean, date, objectId, numeric, string, and UUID values, including arrays of these types. To learn more, see [About the `vector` Type](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector and [About the `filter` Type.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-filter-vector
fields.``path	String	Required	Name of the field to index. For nested fields, use dot notation to specify path to embedded fields. The field must be a top-level field or a child of the field specified in the `nestedRoot` option.
fields.``numDimensions	Int	Required	Number of vector dimensions that MongoDB Vector Search enforces at index-time and query-time. You can set this field only for `vector`-type fields. You must specify a value less than or equal to `8192`. For indexing quantized vectors or [BinData](https://www.mongodb.com/docs/manual/reference/method/BinData.md#std-label-server-binData-method, you can specify one of the following values: `1` to `8192` for `int8` vectors for ingestion, unless you set `quantization` to `binary`.; Multiple of `8` for `int1` vectors for ingestion.; Multiple of `8` for `binData(int8)` vectors when you set `quantization` to `binary`.; `1` to `8192` for `binData(float32)` and `array(float32)` vectors for automatic scalar quantization.; Multiple of `8` for `binData(float32)` and `array(float32)` vectors for automatic binary quantization. The embedding model you choose determines the number of dimensions in your vector embeddings, with some models having multiple options for how many dimensions are output. To learn more, see [Choosing a Method to Create Embeddings.](https://www.mongodb.com/docs/vector-search/crud-embeddings/create-embeddings-manual.md#std-label-choose-embedding-method
fields.``similarity	String	Required	Vector similarity function to use to search for top K-nearest neighbors. You can set this field only for `vector`-type fields. You can specify one of the following values: `euclidean` - measures the distance between ends of vectors.; `cosine` - measures similarity based on the angle between vectors.; `dotProduct` - measures similarity like `cosine`, but takes into account the magnitude of the vector. To learn more, see [About the Similarity Functions.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-similarity-functions
fields.``quantization	String	Optional	Type of automatic vector quantization for your vectors. You can specify one of the following values: `none` - Indicates no automatic quantization for the vector embeddings. Use this setting if you have pre-quantized vectors for ingestion. If omitted, this is the default value.; `scalar` - Indicates scalar quantization, which transforms values to 1 byte integers. Use this value only if your embeddings are `float` or `double` vectors.; `binary` - Indicates binary quantization, which transforms values to a single bit. Use this value if your embeddings are `float` or `double` vectors, or if you ingest `binData(int8)` vectors. To use this value, `numDimensions` must be a multiple of 8.If precision is critical, select `none` or `scalar` instead of `binary`. To learn more, see [About Quantization.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-quantization
fields.``indexingMethod	String	Optional	Index structure for the vector field. Value can be: `hnsw` - for graph-based index where similar vectors are connected; `flat` - for flat, non-graph, index If omitted, defaults to `hnsw`. To learn more, see [About the Indexing Methods.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-vector-index-method This setting is not yet available in the Atlas UI Visual Editor. Use the JSON Editor instead.
fields.``hnswOptions	Object	Optional	Parameters to use for Hierarchical Navigable Small Worlds graph construction. You can specify this field only if `indexingMethod` is `hnsw`. If omitted, uses the default values for the `maxEdges` and `numEdgeCandidates` parameters. NOTE: We recommend using the default values and tuning the default settings only if you are experiencing suboptimal recall on large indexes. While higher values provide better recall, they also increase memory usage and slow down indexing and search speed. To learn more, see [About the Indexing Methods.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-vector-index-method This setting is not yet available in the Atlas UI Visual Editor. Use the JSON Editor instead.
fields.``hnswOptions.``maxEdges	Int	Optional	Maximum number of edges (or connections) that a node can have in the HNSW (Hierarchical Navigable Small Worlds) graph. Value can be between `16` and `64`, both inclusive. If omitted, defaults to `16`. For example, for a value of `16`, each node can have a maximum of sixteen outgoing edges at each layer of the Hierarchical Navigable Small Worlds graph. A higher number improves [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall (accuracy of search results) because the graph is better connected. However, this slows down query speed because of the number of neighbors to evaluate per graph node, increases the memory for the HNSW (Hierarchical Navigable Small Worlds) graph because each node stores more connections, and slows down indexing because MongoDB Vector Search evaluates more neighbors and adjusts for every new node added to the graph.
fields.``hnswOptions.``numEdgeCandidates	Int	Optional	Analogous to `numCandidates` at query-time, this parameter controls the maximum number of nodes to evaluate to find the closest neighbors to connect to a new node. Value can be between `100` and `3200`, both inclusive. If omitted, defaults to `100`. A higher number provides a graph with high-quality connections, which can improve search quality (recall), but it can also negatively affect query latency.
`nestedRoot`	String	Optional	Path to the array field for vector fields that are nested in an array of documents. If you specify a value, the value of `fields.path` must be a child of the field specified here. This setting is not yet available in the Atlas UI Visual Editor. Use the JSON Editor instead.
`storedSource`	Object	Optional	Specifies the fields in the documents to store for query-time look-ups using the `returnStoredSource` option. Value must be an object that specifies the fields to `include` or `exclude` from storage. By default, MongoDB Vector Search doesn't store any fields on `mongot`. To learn more, see [About Stored Source.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-stored-source-definition
storedSource.``include	Array of Strings	Optional	List of fields or dot-separated paths to fields to store. In addition to the specified fields, MongoDB Vector Search stores `_id` also by default. Either `include` or `exclude` is required.
storedSource.``exclude	Array of Strings	Optional	List of fields or dot-separated paths to fields to exclude from being stored. If specified, MongoDB Vector Search stores original documents except the fields listed here. Either `exclude` or `include` is required.

The MongoDB Vector Search index definition takes the following fields:

Option	Type	Necessity	Purpose
`fields`	Array of field definition documents	Required	Definitions for the vector and filter fields to index, one definition per document. Each field definition document specifies the `type`, `path`, and other configuration options for the field to index. The `fields` array must contain at least one `vector`-type field definition. You can add additional `filter`-type field definitions to your array to pre-filter your data.
fields.``type	String	Required	Field type to use to index fields for [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch. You can specify one of the following values: `vector` - for fields that contain vector embeddings.; `filter` - for additional fields to filter on. You can filter on boolean, date, objectId, numeric, string, and UUID values, including arrays of these types. To learn more, see [About the `vector` Type](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-vector and [About the `filter` Type.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-filter-vector
fields.``path	String	Required	Name of the field to index. For nested fields, use dot notation to specify path to embedded fields.
fields.``numDimensions	Int	Required	Number of vector dimensions that MongoDB Vector Search enforces at index-time and query-time. You can set this field only for `vector`-type fields. You must specify a value less than or equal to `8192`. For indexing quantized vectors or [BinData](https://www.mongodb.com/docs/manual/reference/method/BinData.md#std-label-server-binData-method, you can specify one of the following values: `1` to `8192` for `int8` vectors for ingestion, unless you set `quantization` to `binary`.; Multiple of `8` for `int1` vectors for ingestion.; Multiple of `8` for `binData(int8)` vectors when you set `quantization` to `binary`.; `1` to `8192` for `binData(float32)` and `array(float32)` vectors for automatic scalar quantization.; Multiple of `8` for `binData(float32)` and `array(float32)` vectors for automatic binary quantization. The embedding model you choose determines the number of dimensions in your vector embeddings, with some models having multiple options for how many dimensions are output. To learn more, see [Choosing a Method to Create Embeddings.](https://www.mongodb.com/docs/vector-search/crud-embeddings/create-embeddings-manual.md#std-label-choose-embedding-method
fields.``similarity	String	Required	Vector similarity function to use to search for top K-nearest neighbors. You can set this field only for `vector`-type fields. You can specify one of the following values: `euclidean` - measures the distance between ends of vectors.; `cosine` - measures similarity based on the angle between vectors.; `dotProduct` - measures similarity like `cosine`, but takes into account the magnitude of the vector. To learn more, see [About the Similarity Functions.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-similarity-functions
fields.``quantization	String	Optional	Type of automatic vector quantization for your vectors. You can specify one of the following values: `none` - Indicates no automatic quantization for the vector embeddings. Use this setting if you have pre-quantized vectors for ingestion. If omitted, this is the default value.; `scalar` - Indicates scalar quantization, which transforms values to 1 byte integers. Use this value only if your embeddings are `float` or `double` vectors.; `binary` - Indicates binary quantization, which transforms values to a single bit. Use this value if your embeddings are `float` or `double` vectors, or if you ingest `binData(int8)` vectors. To use this value, `numDimensions` must be a multiple of 8.If precision is critical, select `none` or `scalar` instead of `binary`. To learn more, see [About Quantization.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-quantization
fields.``indexingMethod	String	Optional	Index structure for the vector field. Value can be: `hnsw` - for graph-based index where similar vectors are connected; `flat` - for flat, non-graph, index If omitted, defaults to `hnsw`. To learn more, see [About the Indexing Methods.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-vector-index-method
fields.``hnswOptions	Object	Optional	Parameters to use for Hierarchical Navigable Small Worlds graph construction. You can specify this field only if `indexingMethod` is `hnsw`. If omitted, uses the default values for the `maxEdges` and `numEdgeCandidates` parameters. NOTE: We recommend using the default values and tuning the default settings only if you are experiencing suboptimal recall on large indexes. While higher values provide better recall, they also increase memory usage and slow down indexing and search speed. To learn more, see [About the Indexing Methods.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-vector-index-method
fields.``hnswOptions.``maxEdges	Int	Optional	Maximum number of edges (or connections) that a node can have in the HNSW (Hierarchical Navigable Small Worlds) graph. Value can be between `16` and `64`, both inclusive. If omitted, defaults to `16`. For example, for a value of `16`, each node can have a maximum of sixteen outgoing edges at each layer of the Hierarchical Navigable Small Worlds graph. A higher number improves [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall (accuracy of search results) because the graph is better connected. However, this slows down query speed because of the number of neighbors to evaluate per graph node, increases the memory for the HNSW (Hierarchical Navigable Small Worlds) graph because each node stores more connections, and slows down indexing because MongoDB Vector Search evaluates more neighbors and adjusts for every new node added to the graph.
fields.``hnswOptions.``numEdgeCandidates	Int	Optional	Analogous to `numCandidates` at query-time, this parameter controls the maximum number of nodes to evaluate to find the closest neighbors to connect to a new node. Value can be between `100` and `3200`, both inclusive. If omitted, defaults to `100`. A higher number provides a graph with high-quality connections, which can improve search quality (recall), but it can also negatively affect query latency.
`storedSource`	Object	Optional	Specifies the fields in the documents to store for query-time look-ups using the `returnStoredSource` option. Value must be an object that specifies the fields to `include` or `exclude` from storage. By default, MongoDB Vector Search doesn't store any fields on `mongot`. To learn more, see [About Stored Source.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-stored-source-definition
storedSource.``include	Array of Strings	Optional	List of fields or dot-separated paths to fields to store. In addition to the specified fields, MongoDB Vector Search stores `_id` also by default. Either `include` or `exclude` is required.
storedSource.``exclude	Array of Strings	Optional	List of fields or dot-separated paths to fields to exclude from being stored. If specified, MongoDB Vector Search stores original documents except the fields listed here. Either `exclude` or `include` is required.

The MongoDB Vector Search index definition takes the following fields:

Option	Type	Necessity	Purpose
`fields`	Array of field definition documents	Required	Definitions for the vector and filter fields to index, one definition per document. Each field definition document specifies the `type`, `path`, and other configuration options for the field to index. The `fields` array must contain one `autoEmbed` type field definition. You can add additional `filter`-type field definitions to your array to pre-filter your data.
fields.``type	String	Required	Field type to use to index fields for [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch. You can specify one of the following values: `autoEmbed` - for automatically generating vector embeddings.; `filter` - for pre-filtering documents by non-vector fields. You can filter on boolean, date, objectId, numeric, string, and UUID values, including arrays of these types. To learn more, see [About the `autoEmbed` Type](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-auto-embed and [About the `filter` Type.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-filter-auto-embed
fields.``modality	String	Required	Type of data in the field that you specified in the `path`. Value must be `text`.
fields.``path	String	Required	Name of the top-level or nested text field to index. For nested fields, use [dot notation](https://www.mongodb.com/docs/manual/core/document.md#std-label-document-dot-notation to specify the path to embedded fields. If the field is nested in an array of documents, the field must be a child of the field specified in the `nestedRoot` option. If the text value in the specified field exceeds 32,000 tokens, MongoDB Vector Search automatically truncates during indexing to fit the context window of the embedding model.
fields.``model	String	Required	Voyage AI embedding model to use for generating the embeddings. You can specify one of the following models: `voyage-4-lite` - Optimized for high-volume, cost-sensitive applications.; `voyage-4` - (Recommended) Balanced performance for general text search.; `voyage-4-large` - Maximum accuracy for complex semantic relationships.; `voyage-code-4` - (Recommended for code) Specialized for code search and technical documentation.; `voyage-code-3` - Legacy model specialized for code search and technical documentation. Use `voyage-code-4` instead. To learn more, see [Automated Embedding Models.](https://www.mongodb.com/docs/vector-search/crud-embeddings/automated-embedding/models.md#std-label-avs-auto-embeddings-model-ecosystem
fields.``numDimensions	Int	Optional	Number of vector dimensions that MongoDB Vector Search enforces at index-time and query-time. You can specify one of the following values: `256`; `512`; `1024`; `2048` If omitted, defaults to `1024` vector dimensions.
`nestedRoot`	String	Optional	Path to the top-level array of documents field that contains the field for which you want to configure Automated Embedding. If you specify a value, the value of `fields.path` must be a child of the field specified here. This setting is not yet available in the Atlas UI Visual Editor. Use the JSON Editor instead.
fields.``quantization	String	Optional	Data type to use to store the embeddings. You can specify one of the following values: `float` - Builds an index using float (4 bytes) vector values.; `scalar` - Builds an index using scalar (1 byte) vector values.; `binary` - Builds an index with binary (1 bit) vector values and rescores using float (full-precision) vector values.; `binaryNoRescore` - Builds an index with binary vector values. Compared to `binary` (binary quantization with rescoring), this option ensures faster query and lowers storage costs, but provides lower accuracy. If omitted, defaults to `scalar` quantization. To learn more, see [About Quantization.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-mdb-vs-quantization-auto
fields.``similarity	String	Optional	Vector similarity function to use to search for top K-nearest neighbors. You can specify one of the following values: `euclidean` - measures the distance between ends of vectors.; `cosine` - measures similarity based on the angle between vectors.; `dotProduct` - measures similarity like `cosine`, but takes into account the magnitude of the vector. To learn more, see [About the Similarity Functions.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-mdb-vs-similarity-functions-auto
fields.``indexingMethod	String	Optional	Index structure for the vector field. Value can be: `hnsw` - for graph-based index where similar vectors are connected; `flat` - for flat, non-graph, index If omitted, defaults to `hnsw`. To learn more, see [About the Indexing Methods.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-mdb-vs-indexing-method-auto
fields.``hnswOptions	Object	Optional	Parameters to use for Hierarchical Navigable Small Worlds graph construction. If omitted, uses the default values for the `maxEdges` and `numEdgeCandidates` parameters. NOTE: We recommend using the default values and tuning the default settings only if you are experiencing suboptimal recall on large indexes. While higher values provide better recall, they also increase memory usage and slow down indexing and search speed. To learn more, see [About the Indexing Methods.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-vector-index-method
fields.``hnswOptions.``maxEdges	Int	Optional	Maximum number of edges (or connections) that a node can have in the Hierarchical Navigable Small Worlds graph. Value can be between `16` and `64`, both inclusive. If omitted, defaults to `16`. For example, for a value of `16`, each node can have a maximum of sixteen outgoing edges at each layer of the Hierarchical Navigable Small Worlds graph. A higher number improves [recall](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-recall (accuracy of search results) because the graph is better connected. However, this slows down query speed because of the number of neighbors to evaluate per graph node, increases the memory for the Hierarchical Navigable Small Worlds graph because each node stores more connections, and slows down indexing because MongoDB Vector Search evaluates more neighbors and adjusts for every new node added to the graph.
fields.``hnswOptions.``numEdgeCandidates	Int	Optional	Analogous to `numCandidates` at query-time, this parameter controls the maximum number of nodes to evaluate to find the closest neighbors to connect to a new node. Value can be between `100` and `3200`, both inclusive. If omitted, defaults to `100`. A higher number provides a graph with high-quality connections, which can improve search quality (recall), but it can also negatively affect query latency.

The MongoDB Vector Search index definition takes the following fields:

Option	Type	Necessity	Purpose
`fields`	Array of field definition documents	Required	Definitions for the vector and filter fields to index, one definition per document. Each field definition document specifies the `type`, `path`, and other configuration options for the field to index. The `fields` array must contain one `autoEmbed` type field definition. You can add additional `filter`-type field definitions to your array to pre-filter your data.
fields.``type	String	Required	Field type to use to index fields for [`$vectorSearch`](https://www.mongodb.com/docs/vector-search/query/aggregation-stages/vector-search-stage.md#mongodb-pipeline-pipe.-vectorSearch. You can specify one of the following values: `autoEmbed` - for automatically generating vector embeddings.; `filter` - for pre-filtering documents by non-vector fields. You can filter on boolean, date, objectId, numeric, string, and UUID values, including arrays of these types. To learn more, see [About the `autoEmbed` Type](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-auto-embed-self-managed and [About the `filter` Type.](https://www.mongodb.com/docs/vector-search/indexes/vector-search-type.md#std-label-avs-types-filter-auto-embed-self-managed
fields.``modality	String	Required	Type of data in the field that you specified in the `path`. Value must be `text`.
fields.``path	String	Required	Name of the top-level or nested text field to index. For nested fields, use [dot notation](https://www.mongodb.com/docs/manual/core/document.md#std-label-document-dot-notation to specify the path to embedded fields. Automated embedding does not support generating vector embeddings for fields that are nested within an array of objects or subdocuments. If the text value in the specified field exceeds 32,000 tokens, MongoDB Vector Search automatically truncates during indexing to fit the context window of the embedding model.
fields.``model	String	Required	Voyage AI embedding model to use for generating the embeddings. You can specify one of the following models: `voyage-4-lite` - Optimized for high-volume, cost-sensitive applications.; `voyage-4` - (Recommended) Balanced performance for general text search.; `voyage-4-large` - Maximum accuracy for complex semantic relationships.; `voyage-code-3` - Specialized for code search and technical documentation. To learn more, see [Automated Embedding Models.](https://www.mongodb.com/docs/vector-search/crud-embeddings/automated-embedding/models.md#std-label-avs-auto-embeddings-model-ecosystem
fields.``numDimensions	Int	Optional	Number of vector dimensions that MongoDB Vector Search enforces at index-time and query-time. You can specify one of the following values: `256`; `512`; `1024`; `2048` If omitted, defaults to `1024` vector dimensions.
fields.``quantization	String	Optional	Data type to use to store the embeddings. You can specify one of the following values: `float` - Builds an index using float (4 bytes) vector values.;

（本文超出站点单文档体积上限，已截断）

range

vector-search-type

How to Index Fields for Vector Search

Considerations

Embeddings

Billing

Querying

API Keys

Billing

Querying

Syntax

MongoDB Vector Search Index Fields