Search Text

On this page

Overview

Sample Documents
Text Index
Text Search
Specify Options
Search Text by a Term
Search Text by a Phrase
Search Text with Terms Excluded

Overview

In this guide, you can learn how to run a text search in the MongoDB Kotlin 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.

Sample Documents

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"] }

This data is modeled with the following Kotlin data class:

data class Movies(
    @BsonId val id: Int,
    val title: String,
    val tags: List<String>
)

Text Index

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:

Text Indexes section of our Indexes guide
Text Indexes Server Manual Entry

Text Search

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.

Specify Options

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:

val options: TextSearchOptions = TextSearchOptions().caseSensitive(true)
val filter = Filters.text("SomeText", options)

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

Search Text by a Term

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

Example

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

val filter = Filters.text("fast")
val findFlow = collection.find(filter)
findFlow.collect { println(it) }

Movies(id=1, title=2 Fast 2 Furious, tags=[undercover, drug dealer])
Movies(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.

Example

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":

val filter = Filters.text("fate 7")
val findFlow = collection.find(filter)
findFlow.collect { println(it) }

Movies(id=3, title=Furious 7, tags=[emotional])
Movies(id=4, title=The Fate of the Furious, tags=[betrayal])

Search Text by a Phrase

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.

Example

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":

val filter = Filters.text("\"fate of the furious\"")
val findFlow = collection.find(filter)
findFlow.collect { println(it) }

Movies(id=4, title=The Fate of the Furious, tags=[betrayal])

Search Text with Terms Excluded

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.

Example

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":

val filter = Filters.text("furious -fast")
val findFlow = collection.find(filter)
findFlow.collect { println(it) }

Movies(id=3, title=Furious 7, tags=[emotional])
Movies(id=4, title=The Fate of the Furious, tags=[betrayal])

MongoDB Kotlin Driver