Atlas Vector Search

On this page

Overview

Create an Atlas Vector Search Index
Perform Queries

Overview

In this guide, you can learn how to perform searches on your documents by using the Atlas Vector Search feature. Laravel MongoDB provides an API to perform Atlas Vector Search queries directly with your models. This guide describes how to create Atlas Vector Search indexes and provides examples of how to use the Laravel Integration to perform searches.

Note

Deployment Compatibility

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

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

Note

You might not be able to use the methods described in this guide for every type of Atlas Vector Search query. For more complex use cases, create an aggregation pipeline by using the Aggregation Builder.

To perform advanced full-text searches on your documents, you can use the Laravel MongoDB Atlas Search API. To learn about this feature, see the Atlas Search guide.

Create an Atlas Vector Search Index

You can create an Atlas Search index in either of the following ways:

Call the create() method on the Schema facade and pass the vectorSearchIndex() helper method with index creation details. To learn more about this strategy, see the Manage Atlas Search and Vector Search Indexes section of the Schema Builder guide.

Access a collection, then call the createSearchIndex() method from the MongoDB PHP Library. You must specify the type option as 'vectorSearch', as shown in the following code:

$collection = DB::connection('mongodb')->getCollection('movies');
$collection->createSearchIndex([
    'fields' => [
        [
            'type' => 'vector',
            'numDimensions' => 4,
            'path' => 'embeddings',
            'similarity' => 'cosine'
        ],
    ],
], ['name' => 'vector_index', 'type' => 'vectorSearch']);

Perform Queries

In this section, you can learn how to use the Atlas Vector Search API in the Laravel Integration. The Laravel Integration provides the vectorSearch() method as a query builder method and as an Eloquent model method. You can use the vectorSearch() method to run Atlas Vector Search queries on documents in your collections.

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

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

The following code uses the vector index created in the preceding Create an Atlas Vector Search Index section to perform an Atlas Vector Search query on the movies collection:

$movies = Book::vectorSearch(
    index: 'vector',
    path: 'vector_embeddings',
    // Vector representation of the query `coming of age`
    queryVector: [-0.0016261312, -0.028070757, ...],
    limit: 3,
);

[
   { "title": "Sunrising",
     "plot": "A shy teenager discovers confidence and new friendships during a transformative summer camp experience."
   },
   { "title": "Last Semester",
     "plot": "High school friends navigate love, identity, and unexpected challenges before graduating together."
   }
]

You can use the vectorSearch() method to perform many types of Atlas 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`

Note

To construct a QueryInterface instance, you must import the MongoDB\Builder\Query class into your application.

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

Back

Atlas Search

Eloquent Models