Perform Text Queries

Overview

In this guide, you can learn how to use the Scala driver to run text queries on your documents.

You can use a text query to retrieve documents that contain a term or a phrase in a specified field. A term contains only non-whitespace characters. A phrase contains terms separated by any number of whitespace characters.

val database: MongoDatabase = mongoClient.getDatabase("sample_mflix")
val collection: MongoCollection[Document] =
  database.getCollection("movies")

Create a Text Index

Before you run a text query, you must create a text index on the collection. A text index specifies one or more string fields to index for text search. The following example creates a text index on the title field of the movies collection:

val observable = collection.createIndex(Indexes.text("title"))
Await.result(observable.toFuture(), Duration(10, TimeUnit.SECONDS))

Query Text by Term

To find documents that contain a specific term, pass the term as a string to the text() method of the Filters class.

The following example counts documents that have the term "time" in the title field:

val filterTerm = text("time")
collection.countDocuments(filterTerm)
          .subscribe((count: Long) => println(count))

146

To find documents that contain multiple terms, separate the terms with spaces in the search string. The following example counts documents that have the term "time" or the term "machine" in the title field:

val filterMultiple = text("time machine")
collection.countDocuments(filterMultiple)
          .subscribe((count: Long) => println(count))

158

Query Text by Phrase

To find documents that contain a phrase, surround it with escaped quotation marks (\") in the search string.

The following example counts documents that have the phrase "time machine" in the title field:

val filterPhrase = text("\"time machine\"")
collection.countDocuments(filterPhrase)
          .subscribe((count: Long) => println(count))

4

Query Text with Excluded Terms

To exclude documents that contain a specific term, prefix the term with a hyphen (-) in the search string. You must include at least one positive term in the query.

The following example counts documents that contain the term "time" but not the term "machine":

val filterExclude = text("time -machine")
collection.countDocuments(filterExclude)
          .subscribe((count: Long) => println(count))

142

Specify Query Text Options

You can customize text query behavior by passing a TextSearchOptions object as the second parameter to Filters.text(). The following table describes the methods you can chain to a TextSearchOptions instance:

The following example counts documents that match a case-sensitive search for the term "Time" in the title field:

val options = TextSearchOptions().caseSensitive(true)
val filterOptions = text("Time", options)
collection.countDocuments(filterOptions)
          .subscribe((count: Long) => println(count))

146

Additional Information

To learn more about text search, see the following resources in the MongoDB Server manual:

• $text

• Text Indexes

To learn more about creating indexes by using the Scala driver, see the Optimize Queries by Using Indexes guide.