/ /

Run a MongoDB Vector Search Query

Overview

In this guide, you can learn how to perform searches on your documents by using the MongoDB Vector Search feature. The PHP library allows you to perform MongoDB Vector Search queries by using the Aggregation Builder.

Note

Deployment Compatibility

You can use the MongoDB Vector Search feature only when you connect to MongoDB Atlas clusters. This feature is not available for self-managed deployments.

To learn more about MongoDB Vector Search, see the MongoDB Vector Search Overview. The MongoDB Vector Search implementation for the PHP library internally uses the $vectorSearch aggregation operator to perform queries. To learn more about this operator, see the $vectorSearch reference in the Atlas documentation.

Note

MongoDB Search

To perform advanced full-text search on your documents, you can use the MongoDB Search API. To learn about this feature, see the Run a MongoDB Search Query guide.

MongoDB Vector Search Index

Before you can perform MongoDB Vector Search queries, you must create a MongoDB Vector Search index on your collection. To learn more about creating this index type, see the MongoDB Search Indexes guide.

Vector Search Aggregation Stage

Import the following classes into your application to perform MongoDB Vector Search queries by using the Aggregation Builder:

use MongoDB\Builder\Pipeline;
use MongoDB\Builder\Stage;

To create a $vectorSearch stage in your aggregation pipeline, perform the following actions:

Create a Pipeline instance to store the pipeline stages.
Call the Stage::vectorSearch() method to create the MongoDB Vector Search stage.
Within the body of the vectorSearch() method, specify the criteria for your vector query.

The following code demonstrates the template for constructing basic MongoDB Vector Search queries:

$pipeline = new Pipeline(
    Stage::vectorSearch(
        /* MongoDB Vector Search query specifications
        index: '<index name>',
        path: '<path to embeddings>', ...*/
    ),
);

You must pass the following parameters to the vectorSearch() method:

Parameter	Type	Description
`index`	`string`	Name of the vector search index
`path`	`array` or `string`	Field that stores vector embeddings
`queryVector`	`array`	Vector representation of your query
`limit`	`int`	Number of results to return

Vector Search Query Examples

In this section, you can learn how to perform MongoDB Vector Search queries by using the Aggregation Builder. The examples in this section use sample data from the sample_mflix.embedded_movies collection.

Note

Query Vector Length

For demonstrative purposes, the examples in this section use sample query vectors that contain very few elements, compared to the query vector you might use in a runnable application. To view an example that contains the full-length query vector, see the MongoDB Vector Search Quick Start and select PHP from the Select your language dropdown in the upper-right corner of the page.

Basic Vector Search Query

The following code performs a MongoDB Vector Search query on the plot_embedding vector field:

$pipeline = new Pipeline(
    Stage::vectorSearch(
        index: 'vector',
        path: 'plot_embedding',
        queryVector: [-0.0016261312, -0.028070757, -0.011342932],
        numCandidates: 150,
        limit: 5,
    ),
    Stage::project(
        _id: 0,
        title: 1,
    ),
);
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"title":"Thrill Seekers"}
{"title":"About Time"}
{"title":"Timecop"}
// Results truncated

Vector Search Score

The following code performs the same query as in the preceding example, but outputs only the title field and vectorSearchScore meta field, which describes how well the document matches the query vector:

$pipeline = new Pipeline(
    Stage::vectorSearch(
        index: 'vector',
        path: 'plot_embedding',
        queryVector: [-0.0016261312, -0.028070757, -0.011342932],
        numCandidates: 150,
        limit: 5,
    ),
    Stage::project(
        _id: 0,
        title: 1,
        score: ['$meta' => 'vectorSearchScore'],
    ),
);
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"title":"Thrill Seekers","score":0.927734375}
{"title":"About Time","score":0.925750732421875}
{"title":"Timecop","score":0.9241180419921875}
// Results truncated

Vector Search Options

You can use the vectorSearch() method to perform many types of MongoDB Vector Search queries. Depending on your desired query, you can pass the following optional parameters to vectorSearch():

Optional Parameter	Type	Description	Default Value
`exact`	`bool`	Specifies whether to run an Exact Nearest Neighbor (`true`) or Approximate Nearest Neighbor (`false`) search	`false`
`filter`	`QueryInterface` or `array`	Specifies a pre-filter for documents to search on	no filtering
`numCandidates`	`int` or `null`	Specifies the number of nearest neighbors to use during the search	`null`

To learn more about these parameters, see the Fields section of the $vectorSearch operator reference in the Atlas documentation.

Back

MongoDB Search

Monitoring