Run an Atlas Vector Search Query

Overview

In this guide, you can learn how to use the Kotlin Sync driver to perform Atlas Vector Search queries. The Aggregates builders class provides the vectorSearch() helper method, which you can use to create a $vectorSearch pipeline stage.

Important

Feature Compatibility

To learn which versions of MongoDB Atlas support this feature, see Limitations in the MongoDB Atlas documentation.

Perform a Vector Search

Before you can perform Atlas Vector Search queries, you must create an Atlas Vector Search index on your collection. To learn how to programmatically create a vector search index, see the Atlas Search and Vector Search Indexes guide.

Then, you can run an Atlas Vector Search query by using the vectorSearch() method in an aggregation pipeline. This method accepts the following parameters:

path: The field to search
queryVector: The vector embedding that represents your search query
indexName: The name of the Atlas Vector Search index to use
limit: The maximum number of results to return
options: (Optional) A set of options that you can use to configure the vector search query

Basic Vector Search Example

This example runs an Atlas Vector Search query that performs the following actions:

Queries the plot_embedding vector field.
Limits the results to 5 documents.
Specifies an Approximate Nearest Neighbor (ANN) vector search that considers 150 candidates. To learn more about ANN searches, see ANN Search in the MongoDB Atlas documentation.

val vectorValues = FloatArray(1536) { i -> (i % 10).toFloat() * 0.1f }
val queryVector = BinaryVector.floatVector(vectorValues)
val indexName = "<vector search index>"
// Specifies the path of the field to search
val fieldSearchPath: FieldSearchPath = fieldPath("plot_embedding")
// Creates the vector search pipeline stage with a limit and numCandidates
val pipeline: List<Bson> = listOf(
    vectorSearch(
        fieldSearchPath,
        queryVector,
        indexName,
        5L, 
        approximateVectorSearchOptions(150)
    ),
    project(
        Projections.fields(
            Projections.excludeId(),
            Projections.include("title")
        )
    )
)
val results = collection.aggregate(pipeline)
results.forEach { doc ->
    println(doc.toJson())
}

{"title": "Berserk: The Golden Age Arc I - The Egg of the King"}
{"title": "Rollerball"}
{"title": "After Life"}
{"title": "What Women Want"}
{"title": "Truth About Demons"}

Tip

Query Vector Type

The preceding example creates an instance of BinaryVector to serve as the query vector, but you can also create a List of Double instances. However, we recommend that you use the BinaryVector type to improve storage efficiency.

Vector Search Score Example

The following example shows how to run same vector search query as the preceding example and print the documents' vector search meta-score. This score represents the relevance of each document to the query vector:

val pipeline: List<Bson> = listOf(
    vectorSearch(
        fieldSearchPath,
        queryVector,
        indexName,
        5L,
        approximateVectorSearchOptions(150)
    ),
    project(
        Projections.fields(
            Projections.excludeId(),
            Projections.include("title"),
            Projections.metaVectorSearchScore("score")
        )
    )
)
val results = collection.aggregate(pipeline)
results.forEach { doc ->
    println("Title: ${doc.getString("title")}, Score: ${doc.getDouble("score")}")
}

Title: Berserk: The Golden Age Arc I - The Egg of the King, Score: 0.49899211525917053
Title: Rollerball, Score: 0.4976102113723755
Title: After Life, Score: 0.4965665936470032
Title: What Women Want, Score: 0.49622756242752075
Title: Truth About Demons, Score: 0.49614521861076355

Tip

Vector Search Tutorials

To view more tutorials that show how to run Atlas Vector Search queries, see the Atlas Vector Search Tutorials in the MongoDB Atlas documentation.

API Documentation

To learn more about the methods and types mentioned in this guide, see the following API documentation:

Back

Atlas Search

Logging and Monitoring