Search Text
On this page
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( 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])