Atlas Search

On this page

Overview

Create an Atlas Search Index
Perform Queries
General Queries
Autocomplete Queries

Overview

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

Note

Deployment Compatibility

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

To learn more about Atlas Search, see the Overview in the Atlas documentation. The Atlas 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 Atlas 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 Atlas Vector Search API. To learn about this feature, see the Atlas Vector Search guide.

Create an Atlas 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 searchIndex() 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, 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 Atlas 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 Atlas 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 an Atlas 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 Atlas 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 Atlas 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 backend database or return only stored source fields directly from Atlas 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 Atlas Search query, see the autocomplete reference in the Atlas documentation.

Note

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

The following code performs an Atlas 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

Atlas Vector Search