- Article
APPLIES TO:
MongoDB vCore
Use the Integrated Vector Database in Azure Cosmos DB for MongoDB vCore to seamlessly connect your AI-based applications with your data that's stored in Azure Cosmos DB. This integration can include apps that you built by using Azure OpenAI embeddings. The natively integrated vector database enables you to efficiently store, index, and query high-dimensional vector data that's stored directly in Azure Cosmos DB for MongoDB vCore, along with the original data from which the vector data is created. It eliminates the need to transfer your data to alternative vector stores and incur additional costs.
What is a vector store?
A vector store or vector database is a database designed to store and manage vector embeddings, which are mathematical representations of data in a high-dimensional space. In this space, each dimension corresponds to a feature of the data, and tens of thousands of dimensions might be used to represent sophisticated data. A vector's position in this space represents its characteristics. Words, phrases, or entire documents, and images, audio, and other types of data can all be vectorized.
How does a vector store work?
In a vector store, vector search algorithms are used to index and query embeddings. Some well-known vector search algorithms include Hierarchical Navigable Small World (HNSW), Inverted File (IVF), DiskANN, etc. Vector search is a method that helps you find similar items based on their data characteristics rather than by exact matches on a property field. This technique is useful in applications such as searching for similar text, finding related images, making recommendations, or even detecting anomalies. It is used to query the vector embeddings (lists of numbers) of your data that you created by using a machine learning model by using an embeddings API. Examples of embeddings APIs are Azure OpenAI Embeddings or Hugging Face on Azure. Vector search measures the distance between the data vectors and your query vector. The data vectors that are closest to your query vector are the ones that are found to be most similar semantically.
In the Integrated Vector Database in Azure Cosmos DB for MongoDB vCore, embeddings can be stored, indexed, and queried alongside the original data. This approach eliminates the extra cost of replicating data in a separate pure vector database. Moreover, this architecture keeps the vector embeddings and original data together, which better facilitates multi-modal data operations, and enables greater data consistency, scale, and performance.
Create a vector index
To perform vector similiarity search over vector properties in your documents, you'll have to first create a vector index.
Create a vector index using HNSW
You can create (Hierarchical Navigable Small World) indexes on M40 cluster tiers and higher. To create the HSNW index, you need to create a vector index with the "kind" parameter set to "vector-hnsw" following the template below:
{ "createIndexes": "<collection_name>", "indexes": [ { "name": "<index_name>", "key": { "<path_to_property>": "cosmosSearch" }, "cosmosSearchOptions": { "kind": "vector-hnsw", "m": <integer_value>, "efConstruction": <integer_value>, "similarity": "<string_value>", "dimensions": <integer_value> } } ] }| Field | Type | Description |
|---|---|---|
index_name | string | Unique name of the index. |
path_to_property | string | Path to the property that contains the vector. This path can be a top-level property or a dot notation path to the property. If a dot notation path is used, then all the nonleaf elements can't be arrays. Vectors must be a number[] to be indexed and return in vector search results. |
kind | string | Type of vector index to create. The options are vector-ivf and vector-hnsw. Note vector-ivf is available on all cluster tiers and vector-hnsw is available on M40 cluster tiers and higher. |
m | integer | The max number of connections per layer (16 by default, minimum value is 2, maximum value is 100). Higher m is suitable for datasets with high dimensionality and/or high accuracy requirements. |
efConstruction | integer | the size of the dynamic candidate list for constructing the graph (64 by default, minimum value is 4, maximum value is 1000). Higher efConstruction will result in better index quality and higher accuracy, but it will also increase the time required to build the index. efConstruction has to be at least 2 * m |
similarity | string | Similarity metric to use with the index. Possible options are COS (cosine distance), L2 (Euclidean distance), and IP (inner product). |
dimensions | integer | Number of dimensions for vector similarity. The maximum number of supported dimensions is 2000. |
Perform a vector search with HNSW
To perform a vector search, use the $search aggregation pipeline stage the query with the cosmosSearch operator.
{ "$search": { "cosmosSearch": { "vector": <query_vector>, "path": "<path_to_property>", "k": <num_results_to_return>, "efSearch": <integer_value> }, } }}| Field | Type | Description |
|---|---|---|
efSearch | integer | The size of the dynamic candidate list for search (40 by default). A higher value provides better recall at the cost of speed. |
k | integer | The number of results to return. it should be less than or equal to efSearch |
Note
Creating an HSNW index with large datasets can result in your Azure Cosmos DB for MongoDB vCore resource running out of memory, or can limit the performance of other operations running on your database. If you encounter such issues, these can be mitigated by scaling your resource to a higher cluster tier, or reducing the size of the dataset.
Create an vector index using IVF
To create a vector index using the IVF (Inverted File) algorithm, use the following createIndexes template and set the "kind" paramter to "vector-ivf":
{ "createIndexes": "<collection_name>", "indexes": [ { "name": "<index_name>", "key": { "<path_to_property>": "cosmosSearch" }, "cosmosSearchOptions": { "kind": "vector-ivf", "numLists": <integer_value>, "similarity": "<string_value>", "dimensions": <integer_value> } } ]}| Field | Type | Description |
|---|---|---|
index_name | string | Unique name of the index. |
path_to_property | string | Path to the property that contains the vector. This path can be a top-level property or a dot notation path to the property. If a dot notation path is used, then all the nonleaf elements can't be arrays. Vectors must be a number[] to be indexed and return in vector search results. |
kind | string | Type of vector index to create. The options are vector-ivf and vector-hnsw. Note vector-ivf is available on all cluster tiers and vector-hnsw is available on M40 cluster tiers and higher. |
numLists | integer | This integer is the number of clusters that the inverted file (IVF) index uses to group the vector data. We recommend that numLists is set to documentCount/1000 for up to 1 million documents and to sqrt(documentCount) for more than 1 million documents. Using a numLists value of 1 is akin to performing brute-force search, which has limited performance. |
similarity | string | Similarity metric to use with the index. Possible options are COS (cosine distance), L2 (Euclidean distance), and IP (inner product). |
dimensions | integer | Number of dimensions for vector similarity. The maximum number of supported dimensions is 2000. |
Important
Setting the numLists parameter correctly is important for achieving good accuracy and performance. We recommend that numLists is set to documentCount/1000 for up to 1 million documents and to sqrt(documentCount) for more than 1 million documents.
As the number of items in your database grows, you should tune numLists to be larger in order to achieve good latency performance for vector search.
If you're experimenting with a new scenario or creating a small demo, you can start with numLists set to 1 to perform a brute-force search across all vectors. This should provide you with the most accurate results from the vector search, however be aware that the search speed and latency will be slow. After your initial setup, you should go ahead and tune the numLists parameter using the above guidance.
Perform a vector search with IVF
To perform a vector search, use the $search aggregation pipeline stage in a MongoDB query. To use the cosmosSearch index, use the new cosmosSearch operator.
{ { "$search": { "cosmosSearch": { "vector": <query_vector>, "path": "<path_to_property>", "k": <num_results_to_return>, }, "returnStoredSource": True }}, { "$project": { "<custom_name_for_similarity_score>": { "$meta": "searchScore" }, "document" : "$$ROOT" } }}To retrieve the similarity score (searchScore) along with the documents found by the vector search, use the $project operator to include searchScore and rename it as <custom_name_for_similarity_score> in the results. Then the document is also projected as nested object. Note that the similarity score is calculated using the metric defined in the vector index.
Important
Vectors must be a number[] to be indexed. Using another type, such as double[], prevents the document from being indexed. Non-indexed documents won't be returned in the result of a vector search.
Example using an HNSW index.
The following examples show you how to index vectors, add documents that have vector properties, perform a vector search, and retrieve the index configuration.
use test;db.createCollection("exampleCollection");db.runCommand({ "createIndexes": "exampleCollection", "indexes": [ { "name": "VectorSearchIndex", "key": { "contentVector": "cosmosSearch" }, "cosmosSearchOptions": { "kind": "vector-hnsw", "m": 16, "efConstruction": 64, "similarity": "COS", "dimensions": 3 } } ] });This command creates an HNSW index against the contentVector property in the documents that are stored in the specified collection, exampleCollection. The cosmosSearchOptions property specifies the parameters for the HNSW vector index. If your document has the vector stored in a nested property, you can set this property by using a dot notation path. For example, you might use text.contentVector if contentVector is a subproperty of text.
Add vectors to your database
To add vectors to your database's collection, you first need to create the embeddings by using your own model, Azure OpenAI Embeddings, or another API (such as Hugging Face on Azure). In this example, new documents are added through sample embeddings:
db.exampleCollection.insertMany([ {name: "Eugenia Lopez", bio: "Eugenia is the CEO of AdvenureWorks.", vectorContent: [0.51, 0.12, 0.23]}, {name: "Cameron Baker", bio: "Cameron Baker CFO of AdvenureWorks.", vectorContent: [0.55, 0.89, 0.44]}, {name: "Jessie Irwin", bio: "Jessie Irwin is the former CEO of AdventureWorks and now the director of the Our Planet initiative.", vectorContent: [0.13, 0.92, 0.85]}, {name: "Rory Nguyen", bio: "Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.", vectorContent: [0.91, 0.76, 0.83]},]);Perform a vector search
Continuing with the last example, create another vector, queryVector. Vector search measures the distance between queryVector and the vectors in the contentVector path of your documents. You can set the number of results that the search returns by setting the parameter k, which is set to 2 here. You can also set efSearch, which is an integer that controls the size of the candidate vector list. A higher value may improve accuracy, however the search will be slower as a result. This is an optional parameter with a default value of 40.
const queryVector = [0.52, 0.28, 0.12];db.exampleCollection.aggregate([ { "$search": { "cosmosSearch": { "vector": "queryVector", "path": "contentVector", "k": 2, "efSearch": 40 }, } }}]);In this example, a vector search is performed by using queryVector as an input via the Mongo shell. The search result is a list of two items that are most similar to the query vector, sorted by their similarity scores.
[ { similarityScore: 0.9465376, document: { _id: ObjectId("645acb54413be5502badff94"), name: 'Eugenia Lopez', bio: 'Eugenia is the CEO of AdvenureWorks.', vectorContent: [ 0.51, 0.12, 0.23 ] } }, { similarityScore: 0.9006955, document: { _id: ObjectId("645acb54413be5502badff97"), name: 'Rory Nguyen', bio: 'Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.', vectorContent: [ 0.91, 0.76, 0.83 ] } }]Get vector index definitions
To retrieve your vector index definition from the collection, use the listIndexes command:
db.exampleCollection.getIndexes();In this example, vectorIndex is returned with all the cosmosSearch parameters that were used to create the index:
[ { v: 2, key: { _id: 1 }, name: '_id_', ns: 'test.exampleCollection' }, { v: 2, key: { contentVector: 'cosmosSearch' }, name: 'vectorSearchIndex', cosmosSearch: { kind: 'vector-hnsw', m: 40, efConstruction: 64, similarity: 'COS', dimensions: 3 }, ns: 'test.exampleCollection' }]Example using an IVF Index
Inverted File (IVF) Indexing is a method that organizes vectors into clusters. During a vector search, the query vector is first compared against the centers of these clusters. The search is then conducted within the cluster whose center is closest to the query vector.
The numLists parameter determines the number of clusters to be created. A single cluster implies that the search is conducted against all vectors in the database, akin to a brute-force or kNN search. This setting provides the highest accuracy but also the highest latency.
Increasing the numLists value results in more clusters, each containing fewer vectors. For instance, if numLists=2, each cluster contains more vectors than if numLists=3, and so on. Fewer vectors per cluster speed up the search (lower latency, higher queries per second). However, this increases the likelihood of missing the most similar vector in your database to the query vector. This is due to the imperfect nature of clustering, where the search might focus on one cluster while the actual “closest” vector resides in a different cluster.
The nProbes parameter controls the number of clusters to be searched. By default, it’s set to 1, meaning it searches only the cluster with the center closest to the query vector. Increasing this value allows the search to cover more clusters, improving accuracy but also increasing latency (thus decreasing queries per second) as more clusters and vectors are being searched.
The following examples show you how to index vectors, add documents that have vector properties, perform a vector search, and retrieve the index configuration.
Create a vector index
use test;db.createCollection("exampleCollection");db.runCommand({ createIndexes: 'exampleCollection', indexes: [ { name: 'vectorSearchIndex', key: { "vectorContent": "cosmosSearch" }, cosmosSearchOptions: { kind: 'vector-ivf', numLists: 3, similarity: 'COS', dimensions: 3 } } ]});This command creates a vector-ivf index against the vectorContent property in the documents that are stored in the specified collection, exampleCollection. The cosmosSearchOptions property specifies the parameters for the IVF vector index. If your document has the vector stored in a nested property, you can set this property by using a dot notation path. For example, you might use text.vectorContent if vectorContent is a subproperty of text.
Add vectors to your database
To add vectors to your database's collection, you first need to create the embeddings by using your own model, Azure OpenAI Embeddings, or another API (such as Hugging Face on Azure). In this example, new documents are added through sample embeddings:
db.exampleCollection.insertMany([ {name: "Eugenia Lopez", bio: "Eugenia is the CEO of AdvenureWorks.", vectorContent: [0.51, 0.12, 0.23]}, {name: "Cameron Baker", bio: "Cameron Baker CFO of AdvenureWorks.", vectorContent: [0.55, 0.89, 0.44]}, {name: "Jessie Irwin", bio: "Jessie Irwin is the former CEO of AdventureWorks and now the director of the Our Planet initiative.", vectorContent: [0.13, 0.92, 0.85]}, {name: "Rory Nguyen", bio: "Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.", vectorContent: [0.91, 0.76, 0.83]},]);Perform a vector search
To perform a vector search, use the $search aggregation pipeline stage in a MongoDB query. To use the cosmosSearch index, use the new cosmosSearch operator.
{ { "$search": { "cosmosSearch": { "vector": <vector_to_search>, "path": "<path_to_property>", "k": <num_results_to_return>, }, "returnStoredSource": True }}, { "$project": { "<custom_name_for_similarity_score>": { "$meta": "searchScore" }, "document" : "$$ROOT" } }}To retrieve the similarity score (searchScore) along with the documents found by the vector search, use the $project operator to include searchScore and rename it as <custom_name_for_similarity_score> in the results. Then the document is also projected as nested object. Note that the similarity score is calculated using the metric defined in the vector index.
Query vectors and vector distances (aka similarity scores) using $search"
Continuing with the last example, create another vector, queryVector. Vector search measures the distance between queryVector and the vectors in the vectorContent path of your documents. You can set the number of results that the search returns by setting the parameter k, which is set to 2 here. You can also set nProbes, which is an integer that controls the number of nearby clusters that are inspected in each search. A higher value may improve accuracy, however the search will be slower as a result. This is an optional parameter with a default value of 1 and cannot be larger than the numLists value specified in the vector index.
const queryVector = [0.52, 0.28, 0.12];db.exampleCollection.aggregate([ { $search: { "cosmosSearch": { "vector": queryVector, "path": "vectorContent", "k": 2 }, "returnStoredSource": true }}, { "$project": { "similarityScore": { "$meta": "searchScore" }, "document" : "$$ROOT" } }]);In this example, a vector search is performed by using queryVector as an input via the Mongo shell. The search result is a list of two items that are most similar to the query vector, sorted by their similarity scores.
[ { similarityScore: 0.9465376, document: { _id: ObjectId("645acb54413be5502badff94"), name: 'Eugenia Lopez', bio: 'Eugenia is the CEO of AdvenureWorks.', vectorContent: [ 0.51, 0.12, 0.23 ] } }, { similarityScore: 0.9006955, document: { _id: ObjectId("645acb54413be5502badff97"), name: 'Rory Nguyen', bio: 'Rory Nguyen is the founder of AdventureWorks and the president of the Our Planet initiative.', vectorContent: [ 0.91, 0.76, 0.83 ] } }]Get vector index definitions
To retrieve your vector index definition from the collection, use the listIndexes command:
db.exampleCollection.getIndexes();In this example, vectorIndex is returned with all the cosmosSearch parameters that were used to create the index:
[ { v: 2, key: { _id: 1 }, name: '_id_', ns: 'test.exampleCollection' }, { v: 2, key: { vectorContent: 'cosmosSearch' }, name: 'vectorSearchIndex', cosmosSearch: { kind: 'vector-ivf', numLists: 3, similarity: 'COS', dimensions: 3 }, ns: 'test.exampleCollection' }]Filtered vector search (preview)
You can now execute vector searches with any supported query filter such as $lt, $lte, $eq, $neq, $gte, $gt, $in, $nin, and $regex. Enable the "filtering vector search" feature in the "Preview Features" tab of your Azure Subscription. Learn more about preview features here.
First, you'll need to define an index for your filter in addition to a vector index. For example, you can define the filter index on a property
db.runCommand({ "createIndexes": "<collection_name", "indexes": [ { "key": { "<property_to_filter>": 1 }, "name": "<name_of_filter_index>" } ] });Next, you can add the "filter" term to your vector search as shown below. In this example the filter is looking for documents where the "title" property is not in the list of ["not in this text", "or this text"].
db.exampleCollection.aggregate([ { '$search': { "cosmosSearch": { "vector": "<query_vector>", "path": <path_to_vector>, "k": num_results, "filter": {<property_to_filter>: {"$nin": ["not in this text", "or this text"]}} }, "returnStoredSource": True }}, {'$project': { 'similarityScore': { '$meta': 'searchScore' }, 'document' : '$$ROOT' }}]);Important
While in preview, filtered vector search may require you to adjust your vector index parameters to achieve higher accuracy. For example, increasing m, efConstruction, or efSearch when using HNSW, or numLists, or nProbes when using IVF, may lead to better results. You should test your configuration before use to ensure that the results are satisfactory.
Use as a vector database with Semantic Kernel
Use Semantic Kernel to orchestrate your information retrieval from Azure Cosmos DB for MongoDB vCore and your LLM. Learn more here.
Use as a vector database with LangChain
Use LangChain to orchestrate your information retrieval from Azure Cosmos DB for MongoDB vCore and your LLM. Learn more here.
Use as a semantic cache with LangChain
Use LangChain and Azure Cosmos DB for MongoDB (vCore) to orchestrate Semantic Caching, using previously recocrded LLM respones that can save you LLM API costs and reduce latency for responses. Learn more here
Features and limitations
- Supported distance metrics: L2 (Euclidean), inner product, and cosine.
- Supported indexing methods: IVFFLAT (GA), and HSNW (preview)
- Indexing vectors up to 2,000 dimensions in size.
- Indexing applies to only one vector per path.
- Only one index can be created per vector path.
Summary
This guide demonstrates how to create a vector index, add documents that have vector data, perform a similarity search, and retrieve the index definition. By using our integrated vector database, you can efficiently store, index, and query high-dimensional vector data directly in Azure Cosmos DB for MongoDB vCore. It enables you to unlock the full potential of your data via vector embeddings, and it empowers you to build more accurate, efficient, and powerful applications.
Related content
- .NET RAG Pattern retail reference solution
- .NET tutorial - recipe chatbot
- C# RAG pattern - Integrate Open AI Services with Cosmos
- Python RAG pattern - Azure product chatbot
- Python notebook tutorial - Vector database integration through LangChain
- Python notebook tutorial - LLM Caching integration through LangChain
- Python - LlamaIndex integration
- Python - Semantic Kernel memory integration
Next step
Create a lifetime free-tier vCore cluster for Azure Cosmos DB for MongoDB
