Text Query

MongoDB supports query operations that perform a text query on string content in documents. To perform a text query, MongoDB uses a text index and the $text query operator.

To learn more about other text search options, like full-text search and vector search, see the Text Search overview in the MongoDB Server manual.

The driver provides the Filters.text() helper method to facilitate the creation of text query filters.

Prerequisites

You must set up the following components to run the code examples in this guide:

A test.restaurants collection populated with documents from the restaurants.json file in the documentation assets GitHub.
The following import statements:

import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Indexes;
import com.mongodb.client.model.Filters;
import com.mongodb.client.model.Sorts;
import com.mongodb.client.model.TextSearchOptions;
import com.mongodb.client.model.Projections;
import org.bson.Document;

Important

This guide uses custom Subscriber implementations, which are described in the Sample Custom Subscriber Implementations guide.

Connect to a MongoDB Deployment

First, connect to a MongoDB deployment and declare and define MongoDatabase and MongoCollection instances.

The following code connects to a standalone MongoDB deployment running on localhost on port 27017. Then, it defines the database variable to refer to the test database and the collection variable to refer to the restaurants collection:

MongoClient mongoClient = MongoClients.create();
MongoDatabase database = mongoClient.getDatabase("test");
MongoCollection<Document> collection = database.getCollection("restaurants");

To learn more about connecting to MongoDB deployments, see the Connect to MongoDB tutorial.

Create the Text Index

To create a text index, use the Indexes.text() static helper to create a specification for a text index and pass the specification to the MongoCollection.createIndex() method to create the index.

The following example creates a text index on the name field for the restaurants collection:

MongoCollection<Document> collection = database.getCollection("restaurants");
collection.createIndex(Indexes.text("name")).subscribe(new PrintToStringSubscriber<String>());

Perform a Text Query

To perform a text query, use the Filters.text() helper method to specify the text query filter.

For example, the following code performs a text query on the name field to match the strings "bakery" or "coffee":

collection
    .countDocuments(Filters.text("bakery coffee"))
    .subscribe(new PrintSubscriber<Long>("Text query matches: %s"));

Text query matches: [2]

Text Score

For each matching document, a text query assigns a score that represents the relevance of a document to the specified text query filter. To return and sort by score, use the $meta operator in the projection document and the sort expression:

collection.find(Filters.text("bakery cafe"))
    .projection(Projections.metaTextScore("score"))
    .sort(Sorts.metaTextScore("score"))
    .subscribe(new PrintDocumentSubscriber());

Specify a Text Query Option

The Filters.text() helper can accept various text query options. The driver provides the TextSearchOptions class to specify these options.

For example, the following text query specifies the text query language option when performing a text query for the word "cafe":

collection.countDocuments(
    Filters.text("cafe", new TextSearchOptions().language("english"))
).subscribe(new PrintSubscriber<Long>("Text query matches (English): %s"));

Text query matches (English): [1]

To learn more about text queries, see the following sections in the MongoDB Server manual:

Back

Read Preference

Geospatial Search