Atlas Search

Overview

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

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

Search Aggregation Stage

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

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

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

1. Create a Pipeline instance to store the pipeline stages.

2. Call the Stage::search() method to create the Atlas Search stage.

3. Within the body of the search() method, use methods from the Search builder class to construct your Search query criteria.

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

$pipeline = new Pipeline(
    Stage::search(
        /* Atlas Search query specifications
        Search::compound(...) */
    ),
);

Atlas Search Query Examples

In this section, you can learn how to perform different types of Atlas Search queries by using the Aggregation Builder. The examples in this section use sample data from the sample_restaurants.restaurants collection.

$pipeline = new Pipeline(
    Stage::search(
        Search::compound(
            must: [
                Search::text(
                    query: 'kitchen',
                    path: 'name',
                ),
            ],
            should: [
                Search::text(
                    query: 'american',
                    path: 'cuisine',
                ),
            ],
            filter: [
                Search::text(
                    query: 'Queens',
                    path: 'borough',
                ),
            ],
        ),
    ),
    Stage::project(
        borough: 1,
        cuisine: 1,
        name: 1
    ),
    Stage::limit(3)
);
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":...,"borough":"Queens","cuisine":"American","name":"Kitchen Door"}
{"_id":...,"borough":"Queens","cuisine":"American","name":"Cc Kitchen"}
{"_id":...,"borough":"Queens","cuisine":"American","name":"Suite Kitchen"}
// Results truncated

$pipeline = new Pipeline(
    Stage::search(
        Search::autocomplete(
            query: 'Lucy',
            path: 'name',
        ),
    ),
    Stage::limit(3),
    Stage::project(_id: 0, name: 1),
);
$cursor = $collection->aggregate($pipeline);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"name":"Juicy Lucy"}
{"name":"Lucy'S Vietnamese Kitchen"}
{"name":"Lucy'S Cantina Royale"}
// Results Truncated

Search Options

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():

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