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 |
---|---|---|
|
| Name of the vector search index |
|
| Field that stores vector embeddings |
|
| Vector representation of your query |
|
| 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 |
---|---|---|---|
|
| Specifies whether to run an Exact Nearest Neighbor ( |
|
|
| Specifies a pre-filter for documents to search on | no filtering |
|
| Specifies the number of nearest neighbors to use during the search |
|
To learn more about these parameters, see the Fields section of the
$vectorSearch
operator reference in the Atlas documentation.