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( 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])