Azure Cosmos DB

https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search
Admin
Azure Cosmos DB is a fully managed, distributed NoSQL, relational, and vector database designed for...
Tokens:28,185
Snippets:117
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Vector Search Result Example

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This is an example of the output from a vector search operation in Azure Cosmos DB. It returns a list of documents, each with a 'similarityScore' indicating its relevance to the query vector, and the 'document' itself containing the original data.

```javascript
[
  {
    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 ]
    }
  }
]

```

--------------------------------

### Perform Vector Search with DiskANN

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations

This section describes how to execute a vector similarity search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator. It includes details on parameters and an example with optional filtering.

```APIDOC
## POST /api/search (Conceptual)

### Description
Performs a vector similarity search against a collection using a pre-defined vector index.

### Method
POST (Conceptual - Typically part of an aggregation pipeline)

### Endpoint
`/<database_name>/<collection_name>/_aggregate`

### Parameters
#### Request Body (Aggregation Pipeline Stage)
- **$search** (object) - Required - The search stage.
  - **cosmosSearch** (object) - Required - Configuration for the vector search.
    - **path** (string) - Required - Path to the vector property being searched.
    - **query** (array) - Required - The query vector (e.g., `[0.1, 0.2, ..., 0.9]`).
    - **k** (integer) - Required - The number of nearest neighbor results to return.
    - **filter** (object) - Optional - A query filter to narrow down the search results (e.g., geospatial, text, or attribute-based filters).
      - Example: `{"range": {"price": {"$gte": 10}}}`
      - Example: `{"geoWithin": {"location": {"$centerSphere": [[-74.0060, 40.7128], 1000]}}}`
    - **lSearch** (integer) - Optional - Size of the dynamic candidate list for search (10-1000, default 40). Enhances recall but may reduce speed.

### Request Example
```json
{
  "$search": {
    "cosmosSearch": {
      "path": "embedding",
      "query": [0.1, 0.2, 0.3, 0.4, 0.5],
      "k": 5,
      "filter": {"$and": [
        { "category": { "$eq": "electronics" } },
        {"location": {"$geoWithin": {"$centerSphere":[[ -73.9857, 40.7484 ], 5000]}}}
      ]},
      "lSearch": 100
    }
  }
}
```

### Response
#### Success Response (200)
- Returns an array of documents that match the vector similarity search criteria, ordered by similarity.
  - Each document includes the original fields plus a `"_score"` field indicating similarity.

#### Response Example
```json
[
  {
    "_id": "doc1",
    "embedding": [0.11, 0.22, 0.33, 0.44, 0.55],
    "name": "Product A",
    "category": "electronics",
    "_score": 0.95
  },
  {
    "_id": "doc2",
    "embedding": [0.15, 0.25, 0.35, 0.45, 0.55],
    "name": "Product B",
    "category": "electronics",
    "_score": 0.92
  }
]
```
```

--------------------------------

### Example Vector Search Results (JSON)

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

Demonstrates the structure of results returned from a vector search query in Azure Cosmos DB for MongoDB. Each result includes a similarity score and the document metadata, showing how combined vector and geospatial queries work.

```json
[
  {
    "similarityScore": 0.9745354109084544,
    "document": {
      "_id": "645acb54413be5502badff94",
      "name": 'Eugenia Lopez',
      "bio": 'CEO of AdventureWorks',
      "is_open": 1,
      "location": [-118.9865, 34.0145],
      "contentVector": [0.52, 0.20, 0.23]
    }
  },
  {
    "similarityScore": 0.9006955671333992,
    "document": {
      "_id": "645acb54413be5502badff97",
      "name": 'Rory Nguyen',
      "bio": 'President of Our Planet initiative',
      "is_open": 1,
      "location": [-119.7302, 34.4005],
      "contentVector": [0.91, 0.76, 0.83]
    }
  }
]

```

--------------------------------

### Create DiskANN Vector Index

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This example demonstrates how to create a DiskANN vector index for Azure Cosmos DB for MongoDB. DiskANN is recommended for large datasets and offers efficient, high-recall vector search.

```APIDOC
## POST /api/indexes

### Description
Creates a new index for a collection, including vector indexes for similarity search.

### Method
POST

### Endpoint
`/api/indexes` (Conceptual endpoint for index creation)

### Parameters
#### Request Body
- **createIndexes** (string) - Required - The name of the collection where the index will be created.
- **indexes** (array) - Required - An array of index definitions.
  - **name** (string) - Required - The unique name of the index.
  - **key** (object) - Required - Defines the indexed field and index type.
    - **`<path_to_property>`** (string) - Required - Path to the vector property (e.g., `vector_embedding`). Must be `number[]`.
      - **`cosmosSearch`** (string) - Specifies the index type for vector search.
  - **cosmosSearchOptions** (object) - Optional - Configuration options for the `cosmosSearch` index.
    - **kind** (string) - Required - Type of vector index. Use `"vector-diskann"` for DiskANN.
    - **dimensions** (integer) - Required - The number of dimensions of the vector embeddings.
    - **similarity** (string) - Required - The similarity metric. Options: `"COS"`, `"L2"`, `"IP"`.
    - **maxDegree** (integer) - Optional - Maximum number of edges per node for DiskANN graph. Default is 32.
    - **lBuild** (integer) - Optional - Number of candidate neighbors evaluated during index construction for DiskANN. Default is 50.

### Request Example
```json
{
    "createIndexes": "myCollection",
    "indexes": [
        {
            "name": "vectorSearchIndex",
            "key": {
                "embedding": "cosmosSearch"
            },
            "cosmosSearchOptions": {
                "kind": "vector-diskann",
                "dimensions": 1536,
                "similarity": "COS",
                "maxDegree": 64,
                "lBuild": 100
            }
        }
    ]
}
```

### Response
#### Success Response (200)
Returns a confirmation of index creation.

#### Response Example
```json
{
  "_id": "vectorSearchIndex",
  "numIndexesBefore": 1,
  "numIndexesAfter": 2
}
```
```

--------------------------------

### Perform Vector Search with DiskANN

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This example shows how to perform a vector similarity search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator. It includes optional filtering capabilities.

```APIDOC
## POST /api/search

### Description
Performs a vector similarity search within a collection using a specified query vector and optional filters.

### Method
POST

### Endpoint
`/api/search` (Conceptual endpoint for search queries)

### Parameters
#### Request Body
- **$search** (object) - Required - The aggregation pipeline stage for search.
  - **cosmosSearch** (object) - Required - Configuration for the vector search.
    - **path** (string) - Required - The path to the vector property indexed with `cosmosSearch`.
    - **query** (array) - Required - The query vector (array of numbers).
    - **k** (integer) - Required - The number of nearest neighbor results to return.
    - **filter** (object) - Optional - A filter to apply to the search results. Can combine multiple conditions using `$and`.
      - Example filter: `{"genre": {"$eq": "fiction"}}`
      - Example geo filter: `{"location": {"$geoWithin": {"$centerSphere":[[<longitude>, <latitude>], <radius>]}}}

### Request Example
```json
{
  "$search": {
    "cosmosSearch": {
      "path": "embedding",
      "query": [0.1, 0.2, 0.3, ...], 
      "k": 5,
      "filter": {"$and": [
        { "category": { "$eq": "books" } },
        {"stock": {"$gt": 0}}
      ]}
    }
  }
}
```

### Response
#### Success Response (200)
Returns an array of documents that are most similar to the query vector, sorted by similarity score, and filtered according to the specified criteria.

#### Response Example
```json
[
  {
    "_id": "doc1",
    "title": "Example Document 1",
    "embedding": [0.11, 0.22, 0.33, ...],
    "category": "books",
    "stock": 10
  },
  {
    "_id": "doc2",
    "title": "Example Document 2",
    "embedding": [0.15, 0.25, 0.35, ...],
    "category": "books",
    "stock": 5
  }
]
```
```

--------------------------------

### Vector Search Result Example

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_tabs=diskann

This example shows the structure of results returned from a vector search in Azure Cosmos DB. Each result includes a similarityScore and the document itself, which contains fields like _id, name, bio, and the vectorContent.

```json
[
  {
    "similarityScore": 0.9465376,
    "document": {
      "_id": "645acb54413be5502badff94",
      "name": 'Eugenia Lopez',
      "bio": 'Eugenia is the CEO of AdvenureWorks.',
      "vectorContent": [ 0.51, 0.12, 0.23 ]
    }
  },
  {
    "similarityScore": 0.9006955,
    "document": {
      "_id": "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 ]
    }
  }
]
```

--------------------------------

### Perform Vector Search in MongoDB API

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_tabs=diskann

This JSON example illustrates how to perform a vector search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator in Azure Cosmos DB's MongoDB API. It includes placeholders for the query vector, the path to the vector property, and the number of results to return (`k`). It also shows how to project the similarity score.

```json
{
  "$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"
        }
  }
}

```

--------------------------------

### Perform a Vector Search with HNSW

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index

This example shows how to perform a vector search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator when an HNSW index is in place.

```APIDOC
## Perform a Vector Search with HNSW

### Description
To perform a vector search with an HNSW index, use the `$search` aggregation pipeline stage and query with the `cosmosSearch` operator.

### Method
```javascript
{
    "$search": {
        "cosmosSearch": {
            "vector": <query_vector>,
            "path": "<path_to_property>",
            "k": <num_results_to_return>,
            "efSearch": <integer_value>
        },
    }
}
```

### Parameters
#### Request Body Fields
- **vector** - Required - The query vector to search for.
- **path** (string) - Required - The path to the vector field in your documents.
- **k** (integer) - Required - The number of nearest neighbors to return.
- **efSearch** (integer) - Optional - The size of the dynamic candidate list for search (40 by default). A higher value provides better recall at the cost of speed.

### Request Example
```javascript
{
    "$search": {
        "cosmosSearch": {
            "vector": [0.1, 0.2, 0.3],
            "path": "contentVector",
            "k": 5,
            "efSearch": 60
        },
    }
}
```

### Response
#### Success Response (200)
Returns the top `k` nearest neighbors based on the similarity metric defined in the HNSW index.
```

--------------------------------

### Perform Vector Search in Cosmos DB

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index

This JSON example illustrates how to execute a vector search using the $search aggregation pipeline stage with the cosmosSearch operator in MongoDB. It specifies the vector to search, the property path, the number of results (k), and retrieves the similarity score using $meta 'searchScore'.

```json
{
  {
  "$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"
        }
  }
}

```

--------------------------------

### Vector Search Results Example

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations

Illustrates the structure of results returned from a vector search query. Each result includes a `similarityScore` and the `document` itself, which contains the original fields like `_id`, `name`, `bio`, and `vectorContent`.

```json
[
  {
    "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 ]
    }
  }
]

```

--------------------------------

### Create HNSW Vector Index

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This example shows how to create a Hierarchical Navigable Small World (HNSW) index on a collection in Azure Cosmos DB for MongoDB.

```APIDOC
## Create HNSW Vector Index

### Description
This endpoint describes the process of creating an HNSW (Hierarchical Navigable Small World) index on collections in Azure Cosmos DB for MongoDB, available on M30 cluster tiers and higher.

### Method
`CREATE INDEXES`

### Endpoint
`/databases/{databaseId}/collections/{collectionId}/indexes`

### Parameters
#### Request Body
```json
{
    "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>
            }
        }
    ]
}
```

#### `cosmosSearchOptions` Parameters
- **kind** (string) - Required - Set to `"vector-hnsw"` to create an HNSW index.
- **m** (integer) - Optional - The max number of connections per layer. Default is `16`. Minimum value is `2`, maximum is `100`.
- **efConstruction** (integer) - Optional - The size of the dynamic candidate list for constructing the graph. Default is `64`. Minimum value is `4`, maximum is `1000`. Must be at least `2 * m`.
- **similarity** (string) - Required - The similarity metric to use (e.g., `"COS"`, `"L2"`, `"IP"`).
- **dimensions** (integer) - Required - The dimensionality of the vectors.

### Request Example
```javascript
{
    "createIndexes": "myCollection",
    "indexes": [
        {
            "name": "myHnswIndex",
            "key": {
                "vectorField": "cosmosSearch"
            },
            "cosmosSearchOptions": {
                "kind": "vector-hnsw",
                "m": 16,
                "efConstruction": 100,
                "similarity": "COS",
                "dimensions": 3
            }
        }
    ]
}
```

### Response
#### Success Response (200)
Returns a confirmation of the index creation.

#### Response Example
```json
{
    "numIndexesBefore": 1,
    "numIndexesAfter": 2,
    "ok": 1
}
```
```

--------------------------------

### Query vectors and vector distances using $search

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index

This section demonstrates how to perform a vector search using the $search aggregation pipeline with a `cosmosSearch` operator. It includes examples of defining a query vector, setting search parameters like `k` (number of results) and `nProbes`, and projecting the similarity score along with the document.

```APIDOC
## POST /exampleCollection

### Description
Performs a vector search on a collection to find documents most similar to a given query vector.

### Method
POST

### Endpoint
`/exampleCollection` (within the context of an aggregation pipeline)

### Parameters
#### Request Body (within $search operator)
- **cosmosSearch** (object) - Required - Configuration for the vector search.
  - **vector** (array) - Required - The query vector.
  - **path** (string) - Required - The path to the vector field in the documents.
  - **k** (integer) - Optional - The number of nearest neighbors to return. Defaults to the index's k value or a system default if not specified.
  - **nProbes** (integer) - Optional - Controls the number of nearby clusters inspected. Higher values may improve accuracy but slow down the search. Must be less than or equal to `numLists` in the vector index.
  - **returnStoredSource** (boolean) - Optional - If true, returns the original source document.

#### Aggregation Pipeline Stage
- **$search** (object) - Required - The aggregation stage for search operations.
- **$project** (object) - Optional - Reshapes the output documents.
  - **similarityScore** (object) - Required for projecting the score - Uses `$meta: "searchScore"` to extract the similarity score.
  - **document** (variable) - Optional - Projects the entire document (`$$ROOT`) or specific fields.
```

```APIDOC
### Request Example
```javascript
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" 
        }
  }
]);
```
```

```APIDOC
### Response Example (Success)
```json
[
  {
    "similarityScore": 0.9465376,
    "document": {
      "_id": "645acb54413be5502badff94",
      "name": "Eugenia Lopez",
      "bio": "Eugenia is the CEO of AdvenureWorks.",
      "vectorContent": [ 0.51, 0.12, 0.23 ]
    }
  },
  {
    "similarityScore": 0.9006955,
    "document": {
      "_id": "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 ]
    }
  }
]
```
```

--------------------------------

### Create an HNSW Vector Index

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_tabs=diskann

This example shows how to create a Hierarchical Navigable Small World (HNSW) index on a collection for efficient vector searches.

```APIDOC
## POST /databases/{database}/collections/{collection}/indexes (Conceptual)

### Description
Creates a vector index using the HNSW algorithm for optimized vector similarity searches.

### Method
POST (via `createIndexes` command)

### Endpoint
`/databases/{database}/collections/{collection}/indexes`

### Parameters
#### Request Body
```json
{
    "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>
            }
        }
    ]
}
```

### Parameters Details
#### `cosmosSearchOptions`
- **kind** (string) - Must be set to `"vector-hnsw"`.
- **m** (integer) - The maximum number of connections per layer. Defaults to `16`. Minimum: `2`, Maximum: `100`.
- **efConstruction** (integer) - The size of the dynamic candidate list for constructing the graph. Defaults to `64`. Minimum: `4`, Maximum: `1000`. Must be at least `2 * m`.
- **similarity** (string) - The similarity metric to use (e.g., `"COS"`, `"L2"`, `"IP"`).
- **dimensions** (integer) - The dimensionality of the vectors.

### Request Example
```json
{
    "createIndexes": "myCollection",
    "indexes": [
        {
            "name": "vector_index_hnsw",
            "key": {
                "contentVector": "cosmosSearch"
            },
            "cosmosSearchOptions": {
                "kind": "vector-hnsw",
                "m": 16,
                "efConstruction": 100,
                "similarity": "COS",
                "dimensions": 3
            }
        }
    ]
}
```

### Response
#### Success Response (200)
- The response will typically indicate the success of the index creation operation.

#### Response Example
```json
{
    "numIndexesBefore": 1,
    "numIndexesAfter": 2,
    "ok": 1
}
```
```

--------------------------------

### Get Vector Index Definitions - JavaScript

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This JavaScript snippet shows how to retrieve the definitions of all indexes for a collection, specifically focusing on vector indexes. The 'getIndexes()' method is used to list the indexes, and the output will include details of any 'cosmosSearch' indexes.

```javascript
db.exampleCollection.getIndexes();
```

--------------------------------

### Example Vector Search Results

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_tabs=diskann

Demonstrates the structure of results returned from a vector search query in Azure Cosmos DB for MongoDB. Each result includes a similarity score and the document's metadata, showcasing the combined vector and geospatial query capabilities.

```json
[
  {
    "similarityScore": 0.9745354109084544,
    "document": {
      "_id": "645acb54413be5502badff94",
      "name": "Eugenia Lopez",
      "bio": "CEO of AdventureWorks",
      "is_open": 1,
      "location": [-118.9865, 34.0145],
      "contentVector": [0.52, 0.20, 0.23]
    }
  },
  {
    "similarityScore": 0.9006955671333992,
    "document": {
      "_id": "645acb54413be5502badff97",
      "name": "Rory Nguyen",
      "bio": "President of Our Planet initiative",
      "is_open": 1,
      "location": [-119.7302, 34.4005],
      "contentVector": [0.91, 0.76, 0.83]
    }
  }
]
```

--------------------------------

### Add Documents with Vector Embeddings to Azure Cosmos DB (JavaScript)

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index

This example shows how to insert multiple documents into the 'exampleCollection' in Azure Cosmos DB. Each document includes a 'name', 'bio', and a 'contentVector' which is an array of numbers representing a vector embedding. These vectors can then be used for vector searches.

```javascript
db.exampleCollection.insertMany([
  {name: "Eugenia Lopez", bio: "Eugenia is the CEO of AdvenureWorks.", contentVector: [0.51, 0.12, 0.23]},
  {name: "Cameron Baker", bio: "Cameron Baker CFO of AdvenureWorks.", contentVector: [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.", contentVector: [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.", contentVector: [0.91, 0.76, 0.83]},
]);

```

--------------------------------

### Perform Vector Search with DiskANN and Filtering in Azure Cosmos DB

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This code snippet illustrates how to perform a vector similarity search using the $search aggregation pipeline stage with the cosmosSearch operator in Azure Cosmos DB for MongoDB (vCore). It includes the path to the vector property, the query vector, the number of results to return (k), and an example of applying compound filters using $and, including geospatial filtering.

```javascript
{
  "$search": {
    "cosmosSearch": {
      "path": "<path_to_property>",
      "query": "<query_vector>",
      "k": <num_results_to_return>,
      "filter": {"$and": [
        { "<attribute_1>": { "$eq": <value> } },
        {"<location_attribute>": {"$geoWithin": {"$centerSphere":[[<longitude_integer_value>, <latitude_integer_value>], <radius>]}}}
      ]}
    }
  }
}
```

--------------------------------

### Get vector index definitions

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index

This section explains how to retrieve the definition of a vector index from a collection using the `getIndexes()` command. The output shows the index details, including the `cosmosSearch` parameters used during its creation.

```APIDOC
## GET /exampleCollection/indexes

### Description
Retrieves the definitions of all indexes, including vector indexes, for a specified collection.

### Method
GET

### Endpoint
`db.<collection_name>.getIndexes()` (MongoDB shell command)

### Parameters
None for the `getIndexes()` command itself.

### Request Example
```javascript
db.exampleCollection.getIndexes();
```

### Response Example (Success)
```json
[
  { "v": 2, "key": { "_id": 1 }, "name": "_id_", "ns": "test.exampleCollection" },
  {
    "v": 2,
    "key": { "vectorContent": "cosmosSearch" },
    "name": "vectorSearchIndex",
    "cosmosSearch": {
      "kind": "<index_type>", 
      "numLists": 3,
      "similarity": "COS",
      "dimensions": 3
    },
    "ns": "test.exampleCollection"
  }
]
```
*Note: `<index_type>` can be `vector-ivf`, `vector-hnsw`, or `vector-diskann`.*
```

--------------------------------

### Get vector index definitions

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations

Retrieve the definition of an existing vector index from a collection. This is useful for understanding the configuration parameters used for vector search.

```APIDOC
## GET /indexes

### Description
Retrieves the definitions of all indexes on a collection, including vector indexes.

### Method
GET

### Endpoint
`/indexes` (Conceptual endpoint for index retrieval)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```javascript
db.exampleCollection.getIndexes();
```

### Response
#### Success Response (200)
- **Array of index definitions**: Each object in the array describes an index, including its name, key, and specific configuration for vector search (`cosmosSearch`).

#### Response Example
```json
[
  { "v": 2, "key": { "_id": 1 }, "name": "_id_", "ns": "test.exampleCollection" },
  {
    "v": 2,
    "key": { "vectorContent": "cosmosSearch" },
    "name": "vectorSearchIndex",
    "cosmosSearch": {
      "kind": "<index_type>",
      "numLists": 3,
      "similarity": "COS",
      "dimensions": 3
    },
    "ns": "test.exampleCollection"
  }
]
```
```

--------------------------------

### Query vectors and vector distances using $search

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations

Perform a vector search to find documents most similar to a query vector. This example demonstrates how to use the $search aggregation stage with 'cosmosSearch' to find the top 'k' most similar documents and project their similarity scores.

```APIDOC
## POST /search

### Description
Performs a vector search operation on a collection to find documents similar to a given query vector.

### Method
POST

### Endpoint
`/search` (Conceptual endpoint for aggregation queries)

### Parameters
#### Query Parameters
None

#### Request Body
```json
[
  {
    "$search": {
      "cosmosSearch": {
        "vector": [
          0.52,
          0.28,
          0.12
        ],
        "path": "vectorContent",
        "k": 2
      },
      "returnStoredSource": true
    }
  },
  {
    "$project": {
      "similarityScore": {
        "$meta": "searchScore"
      },
      "document": "$$ROOT"
    }
  }
]
```

### Request Example
```javascript
db.exampleCollection.aggregate([
  {
    $search: {
      "cosmosSearch": {
        "vector": [0.52, 0.28, 0.12],
        "path": "vectorContent",
        "k": 2
      },
    "returnStoredSource": true }},
  {
    "$project": { "similarityScore": {
           "$meta": "searchScore" },
            "document" : "$$ROOT" 
        }
  }
]);
```

### Response
#### Success Response (200)
- **similarityScore** (float) - The similarity score between the query vector and the document vector.
- **document** (object) - The full document that matched the search query.

#### Response Example
```json
[
  {
    "similarityScore": 0.9465376,
    "document": {
      "_id": "645acb54413be5502badff94",
      "name": "Eugenia Lopez",
      "bio": "Eugenia is the CEO of AdvenureWorks.",
      "vectorContent": [ 0.51, 0.12, 0.23 ]
    }
  },
  {
    "similarityScore": 0.9006955,
    "document": {
      "_id": "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 ]
    }
  }
]
```
```

--------------------------------

### Perform Vector Search with DiskANN

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_tabs=diskann

This snippet shows how to perform a vector similarity search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator and a DiskANN index. It includes an example with optional filtering.

```APIDOC
## POST /api/search

### Description
Performs a vector similarity search using a DiskANN index in Azure Cosmos DB for MongoDB. Supports optional filtering.

### Method
POST

### Endpoint
`/api/search`

### Parameters
#### Request Body
- **$search** (object) - Required - The search operation.
  - **cosmosSearch** (object) - Required - Configuration for the vector search.
    - **path** (string) - Required - The path to the vector property to search on.
    - **query** (string) - Required - The query vector (as a JSON string representation of a number array).
    - **k** (integer) - Required - The number of search results to return. Must be less than or equal to `lSearch`.
    - **filter** (object) - Optional - A filter object to refine search results. Supports `$and` for combining conditions and geospatial filters.
      - **`<attribute_1>`** (object) - Example filter condition.
        - **`$eq`** (any) - Equality comparison.
      - **`<location_attribute>`** (object) - Example geospatial filter.
        - **`$geoWithin`** (object)
          - **`$centerSphere`** (array) - Defines a spherical region.
            - **`[<longitude_integer_value>, <latitude_integer_value>]`** (array) - Center coordinates.
            - **`<radius>`** (number) - Radius of the sphere in radians.
    - **lSearch** (integer) - Optional - Size of the dynamic candidate list for search (10-1000, default 40).

### Request Example
```json
{
  "$search": {
    "cosmosSearch": {
      "path": "myVectorField",
      "query": "[0.1, 0.2, 0.3, ...]",
      "k": 5,
      "filter": {
        "$and": [
          { "category": { "$eq": "electronics" } },
          {"location": {"$geoWithin": {"$centerSphere":[[ -73.9857, 40.7484], 0.01]}}}
        ]
      },
      "lSearch": 50
    }
  }
}
```

### Response
#### Success Response (200)
- **searchResults** (array) - An array of documents that match the vector search criteria.
  - **`_id`** (string) - The ID of the document.
  - **`score`** (number) - The similarity score of the document.
  - **`<other_fields>`** (any) - Other fields from the document.

#### Response Example
```json
{
  "searchResults": [
    {
      "_id": "doc123",
      "score": 0.95,
      "myVectorField": [0.11, 0.22, 0.33],
      "category": "electronics",
      "location": { "type": "Point", "coordinates": [-73.9857, 40.7484] }
    }
  ]
}
```
```

--------------------------------

### Perform a Vector Search with HNSW

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations&tabs=diskann

This example shows how to perform a vector search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator when an HNSW index is present.

```APIDOC
## Perform a Vector Search with HNSW

### Description
This endpoint describes how to perform a vector search using the `$search` aggregation pipeline stage with the `cosmosSearch` operator when an HNSW index has been created.

### Method
`AGGREGATE` (using `$search` pipeline)

### Endpoint
`/collectionName`

### Parameters
#### Request Body (Aggregation Pipeline)
```json
{
    "$search": {
        "cosmosSearch": {
            "vector": <query_vector>,
            "path": "<path_to_property>",
            "k": <num_results_to_return>,
            "efSearch": <integer_value>
        }
    }
}
```

#### `cosmosSearch` Parameters
- **vector** (array) - Required - The query vector for similarity search.
- **path** (string) - Required - The path to the vector field in your documents.
- **k** (integer) - Required - The number of nearest neighbors to return.
- **efSearch** (integer) - Optional - The size of the dynamic candidate list for search. Default is `40`. A higher value provides better recall at the cost of speed.

### Request Example
```javascript
// Assuming 'collection' is your MongoDB collection object
// and query_vector is defined, e.g., query_vector = [0.1, 0.2, 0.3]

// let results = collection.aggregate([
//     {
//         "$search": {
//             "cosmosSearch": {
//                 "vector": query_vector,
//                 "path": "contentVector",
//                 "k": 10,
//                 "efSearch": 80
//             }
//         }
//     }
// ]).toArray();
```

### Response
#### Success Response (200)
Returns a list of documents matching the search criteria, ordered by similarity.

#### Response Example
```json
[
  {
    "_id": "doc1",
    "contentVector": [0.11, 0.22, 0.33],
    "content": "..."
  },
  {
    "_id": "doc2",
    "contentVector": [0.15, 0.25, 0.35],
    "content": "..."
  }
]
```
```

--------------------------------

### Create a Vector Index (IVF Algorithm)

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_source=recommendations

This section details how to create a vector index using the IVF (Inverted File) algorithm in Azure Cosmos DB. It specifies the structure of the `createIndexes` command and the configuration options for the `cosmosSearch` index kind.

```APIDOC
## Create a Vector Index (IVF Algorithm)

### Description
Creates a vector index using the IVF (Inverted File) algorithm for efficient vector search. This involves defining the index name, key, and specific `cosmosSearchOptions`.

### Method
This is part of a `createIndexes` command.

### Endpoint
N/A (Operates on a collection within Azure Cosmos DB)

### Parameters
#### Request Body (for createIndexes command)
- **createIndexes** (string) - Required - The name of the collection where the index will be created.
- **indexes** (array) - Required - An array of index definitions.
  - **name** (string) - Required - The name of the index.
  - **key** (object) - Required - The key for the index.
    - **`<path_to_property>`** (string) - Required - The path to the vector property in your documents. The value should be `"cosmosSearch"`.
  - **cosmosSearchOptions** (object) - Required - Options specific to the `cosmosSearch` index kind.
    - **kind** (string) - Required - Must be set to `"vector-ivf"`.
    - **numLists** (integer) - Required - The number of clusters for the inverted file index. Recommended: `documentCount/1000` for up to 1M documents, `sqrt(documentCount)` for > 1M documents.
    - **similarity** (string) - Required - The similarity metric (e.g., "cosine", "euclidean").
    - **dimensions** (integer) - Required - The dimensionality of the vectors.

### Request Example
```json
{
  "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>
      }
    }
  ]
}
```

### Response
#### Success Response (200)
- A confirmation of index creation.

#### Response Example
(Response structure not detailed in the provided text, typically a success acknowledgement.)
```

--------------------------------

### Perform a Vector Search with Geospatial Filter

Source: https://learn.microsoft.com/en-us/azure/cosmos-db/mongodb/vcore/vector-search/index_tabs=diskann

This example demonstrates how to perform a vector similarity search while filtering results within a specific geographic radius.

```APIDOC
## POST /databases/{database}/collections/{collection}/aggregate (Conceptual)

### Description
Performs a vector similarity search and filters results based on geospatial proximity.

### Method
POST (via aggregation pipeline)

### Endpoint
`/databases/{database}/collections/{collection}/aggregate`

### Parameters
#### Request Body
```json
[
    {
        "$search": {
            "cosmosSearch": {
                "path": "contentVector",
                "vector": [0.52, 0.28, 0.12],
                "k": 5,
                "filter": {
                    "$and": [
                        {"is_open": {"$eq": 1}},
                        {"location": {"$geoWithin": {"$centerSphere": [[-119.7192861804, 34.4102485028], 100 / 3963.2]}}}
                    ]
                }
            }
        }
    }
]
```

### Request Example
```json
[
    {
        "$search": {
            "cosmosSearch": {
                "path": "contentVector",
                "vector": [0.52, 0.28, 0.12],
                "k": 5,
                "filter": {
                    "$and": [
                        {"is_open": {"$eq": 1}},
                        {"location": {"$geoWithin": {"$centerSphere": [[-119.7192861804, 34.4102485028], 100 / 3963.2]}}}
                    ]
                }
            }
        }
    }
]
```

### Response
#### Success Response (200)
- **similarityScore** (float) - The similarity score between the query vector and the document vector.
- **document** (object) - The document that matched the search criteria.
  - **_id** (ObjectId) - The unique identifier of the document.
  - **name** (string) - The name of the entity.
  - **bio** (string) - A short biography or description.
  - **is_open** (integer) - A flag indicating if the entity is open (1) or closed (0).
  - **location** (array) - Geospatial coordinates [longitude, latitude].
  - **contentVector** (array) - The vector representation of the document content.

#### Response Example
```json
[
  {
    "similarityScore": 0.9745354109084544,
    "document": {
      "_id": "645acb54413be5502badff94",
      "name": "Eugenia Lopez",
      "bio": "CEO of AdventureWorks",
      "is_open": 1,
      "location": [-118.9865, 34.0145],
      "contentVector": [0.52, 0.20, 0.23]
    }
  },
  {
    "similarityScore": 0.9006955671333992,
    "document": {
      "_id": "645acb54413be5502badff97",
      "name": "Rory Nguyen",
      "bio": "President of Our Planet initiative",
      "is_open": 1,
      "location": [-119.7302, 34.4005],
      "contentVector": [0.91, 0.76, 0.83]
    }
  }
]
```
```
Tokens:
Raw