Docs Menu

Search Text

In this guide, you can learn how to run a text search in the MongoDB Java driver.

You can use a text search to retrieve documents that contain a term or a phrase in a specified field. A term is a sequence of characters that excludes whitespace characters. A phrase is a sequence of terms with any number of whitespace characters.

The following sections show you how to perform the following types of text searches:

  • Search Text by a Term

  • Search Text by a Phrase

  • Search Text with Terms Excluded

If you want to sort your text search results, see the Text Search section of our Sort Results guide.

The following sections feature examples of text searches on the fast_and_furious_movies collection. Each section uses a variable named collection to refer to the MongoCollection instance of the fast_and_furious_movies collection.

The fast_and_furious_movies collection contains documents that describe one of the several movies that are part of the Fast and Furious movie franchise. Each document contains a title field and a tags field.

{ "_id": 1, "title": "2 Fast 2 Furious ", "tags": ["undercover", "drug dealer"] }
{ "_id": 2, "title": "Fast 5", "tags": ["bank robbery", "full team"] }
{ "_id": 3, "title": "Furious 7", "tags": ["emotional"] }
{ "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }

You must create a text index before running a text search. A text index specifies the string or string array field on which to run a text search.

In the following examples, you run text searches on the title field in the fast_and_furious_movies collection. To enable text searches on the title field, create a text index using the Indexes builder with the following snippet:

collection.createIndex(Indexes.text("title"));

For more information, see the following resources:

Use the Filters.text() method to specify a text search.

The Filters.text() method uses the Filters builder to define a query filter specifying what to search for during the text search. The query filter is represented by a BSON instance. Pass the query filter to the find() method to run a text search.

When you execute the find() method, MongoDB runs a text search on all the fields indexed with the text index on the collection. MongoDB returns documents that contain one or more of the search terms and a relevance score for each result. For more information on relevance scores, see the Text Search section in our Sort Results guide.

You can include TextSearchOptions as the second parameter of the Filters.text() method to specify text search options such as case sensitivity. By default, text searches run without case sensitivity which means the search matches lowercase and uppercase values.

To specify a case sensitive search, use the following snippet:

TextSearchOptions options = new TextSearchOptions().caseSensitive(true);
Bson filter = Filters.text("SomeText", options);

For more information about the methods and classes mentioned in this section, see the following API Documentation:

Pass a term as a string to the Filters.text() method to specify the term in your text search.

The following example runs a text search on the documents in the fast_and_furious_movies collection for titles that contain the term "fast":

Bson filter = Filters.text("fast");
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding code:

{ "_id": 1, "title": "2 Fast 2 Furious ", "tags": ["undercover", "drug dealer"] }
{ "_id": 2, "title": "Fast 5", "tags": ["bank robbery", "full team"] }

To match multiple terms in your text search, separate each term with spaces in the Filters.text() builder method. The builder method returns the text search query as a Bson instance. When you pass this to the find() method, it returns documents that match any of the terms.

The following example runs a text search on the documents in the fast_and_furious_movies collection for titles that contain the terms "fate" or "7":

Bson filter = Filters.text("fate 7");
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding code:

{ "_id": 3, "title": "Furious 7", "tags": ["emotional"] }
{ "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }

Pass a phrase with escaped quotes to the Filters.text() method to specify the phrase in your text search. Escaped quotes are double quote characters preceded by a backslash character. If you don't add escaped quotes around the phrase, the find() method runs a term search.

The following example runs a text search on the documents in the fast_and_furious_movies collection for titles that contain the phrase "fate of the furious":

Bson filter = Filters.text("\"fate of the furious\"");
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding code:

{ "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }

For each term you want to exclude from your text search, prefix the term with a minus sign in the string that you pass to the Filters.text() builder method.

None of the documents returned from the search contain the excluded term in your text index field.

Important

You must have at least one text search term if you want to exclude terms from your search.

The following example runs a text search on the documents in the fast_and_furious_movies collection for titles that contain the term "furious", but do not contain the term "fast":

Bson filter = Filters.text("furious -fast");
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding code:

{ "_id": 3, "title": "Furious 7", "tags": ["emotional"] }
{ "_id": 4, "title": "The Fate of the Furious", "tags": ["betrayal"] }