Run a MongoDB Search Query

Overview

In this guide, you can learn how to query a MongoDB Search index and use advanced full-text search functionality in your C++ driver applications. You can query a search index by using a $search aggregation pipeline stage.

To learn more about the $search pipeline stage, see the $search guide in the MongoDB Server manual.

Note

Atlas and Community Edition Version Requirements

The $search aggregation-pipeline operator is available only for collections hosted on MongoDB Atlas clusters running MongoDB v4.2 or later, or on MongoDB Community Edition clusters running MongoDB v8.2 or later. Collections must be covered by a MongoDB Search index. To learn more about the required setup and the functionality of this operator, see the MongoDB Search documentation.

Sample Data

The examples in this guide use the sample_mflix.movies collection from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see the MongoDB Get Started guide.

Create a MongoDB Search Index

Before you can perform a search on an Atlas collection, you must first create a MongoDB Search index on the collection. A MongoDB Search index is a data structure that categorizes data in a searchable format. To learn how to create a MongoDB Search index, see the MongoDB Search Indexes guide.

Search Your Data

To use the $search aggregation pipeline stage, you must specify a MongoDB Search query operator that indicates the type of query you want to run. You can optionally use a collector to specify the values and ranges of the query output. To view a table of all the operators and collectors available with MongoDB Search, see the Operators and Collectors page in the Atlas documentation.

The following example uses the compound operator to combine several operators into a single query. To learn more, see the Compound Operator guide in the Atlas documentation.

The query has the following search criteria:

The genres field must not contain Comedy.
The title field must contain the string New York.

The query also includes the following stages:

$limit, to limit the output to 10 results.
$project, to exclude all fields except title and add a field named score.

#include <iostream>
#include <bsoncxx/json.hpp>
#include <mongocxx/client.hpp>
#include <mongocxx/exception/exception.hpp>
#include <mongocxx/instance.hpp>
#include <mongocxx/pipeline.hpp>
int main() {
    const mongocxx::instance instance{};
    
    try {
        const mongocxx::client client{mongocxx::uri{"<connection-string>"}};
        auto collection = client["sample_mflix"]["movies"];
        mongocxx::pipeline pipeline{};
        
        auto search_stage = bsoncxx::from_json(R"(
        {
            "$search": {
                "index": "test_index",
                "compound": {
                    "mustNot": [
                        {
                            "text": {
                                "query": [ "Comedy" ],
                                "path": "genres"
                            }
                        }
                    ],
                    "must": [
                        {
                            "text": {
                                "query": [ "New York" ],
                                "path": "title"
                            }
                        }
                    ]
                }
            }
        }
        )");
        
        pipeline.append_stage(search_stage.view());
        pipeline.limit(10);
        
        pipeline.project(bsoncxx::from_json(R"(
        { "_id" : 0, "title" : 1, "score" : { "$meta" : "searchScore" } }
        )"));
        auto cursor = collection.aggregate(pipeline);
        for (const auto& doc : cursor) {
            std::cout << bsoncxx::to_json(doc) << std::endl;
        }
    } catch (const mongocxx::exception& e) {
        std::cerr << "MongoDB error: " << e.what() << std::endl;
        return EXIT_FAILURE;
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << std::endl;
        return EXIT_FAILURE;
    }
    return EXIT_SUCCESS;
}

{ "title" : "New York, New York", "score" : 6.7870168685913085938 }
{ "title" : "New York", "score" : 6.2591872215270996094 }
{ "title" : "New York Doll", "score" : 5.3819599151611328125 }
{ "title" : "Escape from New York", "score" : 4.7203946113586425781 }
{ "title" : "Autumn in New York", "score" : 4.7203946113586425781 }
{ "title" : "Gangs of New York", "score" : 4.7203946113586425781 }
{ "title" : "Sleepless in New York", "score" : 4.7203946113586425781 }
{ "title" : "Sherlock Holmes in New York", "score" : 4.2036685943603515625 }
{ "title" : "New York: A Documentary Film", "score" : 4.2036685943603515625 }
{ "title" : "An Englishman in New York", "score" : 4.2036685943603515625 }

Additional Information

To learn more about the available MongoDB Search operators, see the Operators and Collectors guide in the MongoDB Atlas documentation.

For more information about MongoDB Search, and to view more query examples, see the MongoDB Search documentation.

If you'd like to perform vector searches on your data stored in Atlas, you must use MongoDB Vector Search. To learn more about MongoDB Vector Search, see the MongoDB Vector Search documentation.

Back

Run a Database Command

MongoDB Vector Search