/ /

Query Text

Overview

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

You can use a text query 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 queries:

Query Text by a Term
Query Text by a Phrase
Query Text with Terms Excluded

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

Sample Documents

The following sections feature examples of text queries 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 query. A text index specifies the string or string array field on which to run a text query.

In the following examples, you run text queries on the title field in the fast_and_furious_movies collection. To enable text queries 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 Query

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

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

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

Specify Options

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

To specify a case sensitive query, 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:

Query Text by a Term

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

Example

The following example runs a text query 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 query, separate each term with spaces in the Filters.text() builder method. The builder method returns the text 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 query 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])

Query Text by a Phrase

Pass a phrase with escaped quotes to the Filters.text() method to specify the phrase in your text query. 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 query 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])

Query Text with Terms Excluded

For each term you want to exclude from your text query, 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 query contain the excluded term in your text index field.

Important

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

Example

The following example runs a text query 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])

Back

Search Geospatially

Update Documents