/ /

MongoDB Search

Overview

In this guide, you can learn how to use the Java driver to run MongoDB Search queries on a collection. MongoDB Search enables you to perform full-text searches on collections hosted on MongoDB Atlas. MongoDB Search indexes specify the behavior of the search and which fields to index.

Sample Data

The examples in this guide use the movies collection in the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB deployment and load the sample datasets, see the MongoDB Get Started guide. To learn more about aggregation operations and builders, see the Aggregation guide.

Run a MongoDB Search Query

This section shows how to create an aggregation pipeline to run a MongoDB Search query on a collection. You can use the Aggregates.search() builder method to create a $search pipeline stage, which specifies the search criteria. Then, call the aggregate() method and pass your pipeline as a parameter.

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.

Before running a MongoDB Search query, you must create a MongoDB Search index on your collection. To learn how to programmatically create a MongoDB Search index, see the MongoDB Search and Vector Search Indexes section in the Indexes guide.

MongoDB Search Example

This example runs a MongoDB Search query by performing the following actions:

Constructs a $search stage by using the Aggregates.search() builder method, instructing the driver to query for documents in which the title field contains the word "Alabama"
Constructs a $project stage by using the Aggregates.project() builder method, instructing the driver to include the title field in the query results
Passes the pipeline stages to the aggregate() method and prints the results

collection.aggregate(
    Arrays.asList(
    	Aggregates.search(SearchOperator.text(
                      SearchPath.fieldPath("title"), "Alabama")),
        Aggregates.project(Projections.include("title"))
    )
).forEach(doc -> System.out.println(doc.toJson()));

{"_id": {"$oid": "..."}, "title": "Alabama Moon"}
{"_id": {"$oid": "..."}, "title": "Crazy in Alabama"}
{"_id": {"$oid": "..."}, "title": "Sweet Home Alabama"}

Tip

Java Driver MongoDB Search Examples

To view more examples that use the Java driver to perform MongoDB Search queries, see MongoDB Search Tutorials in the Atlas documentation.

MongoDB Search Metadata

Use the searchMeta() method to create a $searchMeta pipeline stage, which returns only the metadata from of the MongoDB Search results.

Note

Atlas and Community Edition Version Requirements

This aggregation pipeline operator is available only on MongoDB Atlas clusters running v4.4.11 and later, or on MongoDB Community Edition clusters running MongoDB v8.2 or later. For a detailed list of version availability, see the MongoDB Atlas documentation on $searchMeta.

The following example shows the near metadata for a MongoDB Search aggregation stage:

Aggregates.searchMeta(
        SearchOperator.near(2010, 1, fieldPath("year")));

To learn more about this helper method, see the searchMeta() API documentation.

Create Pipeline Search Stages

The Java driver provides helper methods for the following operators:

Operator	Description
autocomplete	Performs a search for a word or phrase that contains a sequence of characters from an incomplete input string.
compound	Combines two or more operators into a single query.
equals	Checks whether a field matches a value you specify. Maps to the `equals()` and `equalsNull()` methods.
exists	Tests if a path to a specified indexed field name exists in a document.
in	Performs a search for an array of BSON number, date, boolean, objectId, uuid, or string values at the given path and returns documents where the value of the field equals any value in the specified array.
moreLikeThis	Returns documents similar to input documents.
near	Supports querying and scoring numeric, date, and GeoJSON point values.
phrase	Performs a search for documents containing an ordered sequence of terms using the analyzer specified in the index configuration.
queryString	Supports querying a combination of indexed fields and values.
range	Supports querying and scoring numeric, date, and string values. Maps to the `numberRange()` and `dateRange()` methods.
regex	Interprets the query field as a regular expression.
text	Performs a full-text search using the analyzer that you specify in the index configuration.
wildcard	Enables queries which use special characters in the search string that can match any character.

Example Pipeline Search Stage

Before you can run this example, you must create a MongoDB Search index on the movies collection that has the following definition:

{
  "mappings": {
    "dynamic": true,
    "fields": {
      "title": {
        "analyzer": "lucene.keyword",
        "type": "string"
      },
      "genres": {
        "normalizer": "lowercase",
        "type": "token"
      }
    }
  }
}

To learn more about creating MongoDB Search indexes, see the MongoDB Search and Vector Search Indexes section of the Indexes guide.

The following code creates a $search stage that has the following specifications:

Checks that the genres array includes "Comedy"
Searches the fullplot field for the phrase "new york"
Matches year values between 1950 and 2000, inclusive
Searches for title values that begins with the term "Love"

List<Bson> pipeline = new ArrayList<>();
pipeline.add(Aggregates.search(
        SearchOperator.compound()
                .filter(
                        List.of(
                                SearchOperator.in(fieldPath("genres"), "Comedy"),
                                SearchOperator.phrase(fieldPath("fullplot"), "new york"),
                                SearchOperator.numberRange(fieldPath("year")).gtLt(1950, 2000),
                                SearchOperator.wildcard(fieldPath("title"), "Love *")
                        ))));
pipeline.add(Aggregates.project(
        Projections.include("title", "year", "genres")
));
AggregateIterable<Document> results = collection.aggregate(pipeline);
results.forEach(doc -> System.out.println(doc.toJson()));

{"_id": ..., "genres": ["Comedy", "Romance"], "title": "Love at First Bite", "year": 1979}
{"_id": ..., "genres": ["Comedy", "Drama"], "title": "Love Affair", "year": 1994}

To learn more about the MongoDB Search helper methods, see the SearchOperator interface reference in the Driver Core API documentation.

MongoDB Vector Search Operators

Use the vectorSearch() or vectorSearchExact() static methods on the SearchOperator class to perform a vector search within a $search aggregation pipeline stage. These methods allow you to combine vector similarity search with other MongoDB Search operators, including operators that use analyzed text prefilters.

Note

MongoDB Vector Search Index Required

To use these methods, you must have a MongoDB Vector Search index configured on your collection. To learn how to create a vector search index, see the MongoDB Search and Vector Search Indexes section in the Indexes guide.

Use the vectorSearch() method to perform an approximate nearest neighbor (ANN) search. Use the vectorSearchExact() method to perform an exact nearest neighbor (ENN) search. Both methods accept the following parameters:

Parameter	Type	Description
`path`	`FieldSearchPath`	The path to the indexed vector field to search.
`queryVector`	`Iterable<Double>`	The query vector. The number of dimensions must match the indexed field.
`limit`	`int`	The maximum number of results to return.
`numCandidates`	`int`	The number of nearest neighbors to consider during the search. Required for `vectorSearch()` only. This value must be greater than or equal to `limit`.

Both methods return a VectorSearchOperator instance. You can chain the following methods on the returned instance:

Method	Description
`filter()`	Applies a `SearchOperator` as a prefilter before the vector search. You can pass any MongoDB Search operator, including operators that use analyzed text fields.
`score()`	Applies a score modifier to the vector search results.

vectorSearch() Example

The following example uses the vectorSearch() method to perform an ANN search on the plot_embedding field of the movies collection. The example applies a text operator as a lexical prefilter on the genres field.

List<Double> queryVector = List.of(
    -0.014, -0.055, 0.047, -0.041, 0.027);
Bson searchStage = Aggregates.search(
    SearchOperator.vectorSearch(
        fieldPath("plot_embedding"),
        queryVector,
        10,
        20
    ).filter(SearchOperator.text(
        fieldPath("genres"), "Drama")));
collection.aggregate(List.of(searchStage))
    .forEach(result -> System.out.println(result));

vectorSearchExact() Example

The following example uses the vectorSearchExact() method to perform an ENN search on the plot_embedding field of the movies collection:

List<Double> queryVector = List.of(
    -0.014, -0.055, 0.047, -0.041, 0.027);
Bson searchStage = Aggregates.search(
    SearchOperator.vectorSearchExact(
        fieldPath("plot_embedding"),
        queryVector,
        5));
collection.aggregate(List.of(searchStage))
    .forEach(result -> System.out.println(result));

Additional Information

To learn more about MongoDB Search, see MongoDB Search in the Atlas documentation.

API Documentation

To learn more about the methods mentioned in this guide, see the following API documentation:

Back

Run a Command

MongoDB Vector Search