/ /

MongoDB Search

Overview

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

Note

Deployment Compatibility

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

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

Note

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

To perform searches on vector embeddings in MongoDB, you can use the Laravel MongoDB MongoDB Vector Search API. To learn about this feature, see the MongoDB Vector Search guide.

Create a MongoDB Search Index

You can create a MongoDB Search index in either of the following ways:

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

Access a collection, then call the createSearchIndex() method from the MongoDB PHP Library, as shown in the following code:

$collection = DB::connection('mongodb')->getCollection('movies');
$collection->createSearchIndex(
    ['mappings' => ['dynamic' => true]],
    ['name' => 'search_index']
);

Perform Queries

In this section, you can learn how to use the MongoDB Search API in the Laravel Integration.

General Queries

The Laravel Integration provides the search() method as a query builder method and as an Eloquent model method. You can use the search() method to run MongoDB Search queries on documents in your collections.

You must pass an operator parameter to the search() method that is an instance of SearchOperatorInterface or an array that contains the operator type, field name, and query value. You can create an instance of SearchOperatorInterface by calling the Search::text() method and passing the field you are querying and your search term or phrase.

You must include the following import statement in your application to create a SearchOperatorInterface instance:

use MongoDB\Builder\Search;

The following code performs a MongoDB Search query on the Movie model's title field for the term 'dream':

$movies = Movie::search(
    sort: ['title' => 1],
    operator: Search::text('title', 'dream'),
)->all();

[
   { "title": "Dreaming of Jakarta",
     "year": 1990
   },
   { "title": "See You in My Dreams",
     "year": 1996
   }
]

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

Optional Parameter	Type	Description
`index`	`string`	Provides the name of the MongoDB Search index to use
`highlight`	`array`	Specifies highlighting options for displaying search terms in their original context
`concurrent`	`bool`	Parallelizes search query across segments on dedicated search nodes
`count`	`string`	Specifies the count options for retrieving a count of the results
`searchAfter`	`string`	Specifies a reference point for returning documents starting immediately following that point
`searchBefore`	`string`	Specifies a reference point for returning documents starting immediately preceding that point
`scoreDetails`	`bool`	Specifies whether to retrieve a detailed breakdown of the score for results
`sort`	`array`	Specifies the fields on which to sort the results
`returnStoredSource`	`bool`	Specifies whether to perform a full document lookup on the back end database or return only stored source fields directly from MongoDB Search
`tracking`	`array`	Specifies the tracking option to retrieve analytics information on the search terms

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

Autocomplete Queries

The Laravel Integration provides the autocomplete() method as a query builder method and as an Eloquent model method. You can use the autocomplete() method to run autocomplete searches on documents in your collections. This method returns only the values of the field you specify as the query path.

To learn more about this type of MongoDB Search query, see the autocomplete reference in the Atlas documentation.

Note

You must create a MongoDB Search index with an autocomplete configuration on your collection before you can perform autocomplete searches. See the Create a MongoDB Search Index section of this guide to learn more about creating Search indexes.

The following code performs a MongoDB Search autocomplete query for the string "jak" on the title field:

$movies = Movie::autocomplete('title', 'jak')->all();

[
   "Dreaming of Jakarta",
   "Jakob the Liar",
   "Emily Calling Jake"
]

You can also pass the following optional parameters to the autocomplete() method to customize the query:

Optional Parameter	Type	Description	Default Value
`fuzzy`	`bool` or `array`	Enables fuzzy search and fuzzy search options	`false`
`tokenOrder`	`string`	Specifies order in which to search for tokens	`'any'`

To learn more about these parameters, see the Options section of the autocomplete operator reference in the Atlas documentation.

Back

Aggregation Builder

MongoDB Vector Search