Find a Document

You can retrieve a single document in a collection by chaining together the find() and first() methods on a MongoCollection object. You can pass a query filter to the find() method to query for and return documents that match the filter in the collection. If you do not include a filter, MongoDB returns all the documents in the collection. The first() method returns the first matching document.

For more information about querying MongoDB with the Java driver, see our guide on Querying Documents.

You can also chain other methods to the find() method such as sort() which organizes the matched documents in a specified order, and projection() which configures the fields included in the returned documents.

For more information about the sort() method, see our guide on Sorting. For more information about the projection() method, see our guide on Projections

The find() method returns an instance of FindIterable, a class that offers several methods to access, organize, and traverse the results. FindIterable also inherits methods from its parent class, MongoIterable such as first().

The first() method returns the first document from the retrieved results or null if there are no results.

Example

The following snippet finds a single document from the movies collection. It uses the following objects and methods:

A query filter that is passed to the find() method. The eq filter matches only movies with the title exactly matching the text 'The Room'.
A sort that organizes matched documents in descending order by rating, so if our query matches multiple documents the returned document is the one with the highest rating.
A projection that includes the objects in the title and imdb fields and excludes the _id field using the helper method excludeId().

Note

This example connects to an instance of MongoDB using a connection URI. To learn more about connecting to your MongoDB instance, see the connection guide.

// Retrieves a document that matches a query filter by using the Java driver
package usage.examples;
import static com.mongodb.client.model.Filters.eq;
import org.bson.Document;
import org.bson.conversions.Bson;
import com.mongodb.client.MongoClient;
import com.mongodb.client.MongoClients;
import com.mongodb.client.MongoCollection;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Projections;
import com.mongodb.client.model.Sorts;
public class FindOne {
    public static void main( String[] args ) {
        // Replace the uri string with your MongoDB deployment's connection string
        String uri = "<connection string uri>";
        try (MongoClient mongoClient = MongoClients.create(uri)) {
            MongoDatabase database = mongoClient.getDatabase("sample_mflix");
            MongoCollection<Document> collection = database.getCollection("movies");
            // Creates instructions to project two document fields
            Bson projectionFields = Projections.fields(
                    Projections.include("title", "imdb"),
                    Projections.excludeId());
            // Retrieves the first matching document, applying a projection and a descending sort to the results
            Document doc = collection.find(eq("title", "The Room"))
                    .projection(projectionFields)
                    .sort(Sorts.descending("imdb.rating"))
                    .first();
            // Prints a message if there are no result documents, or prints the result document as JSON
            if (doc == null) {
                System.out.println("No results found.");
            } else {
                System.out.println(doc.toJson());
            }
        }
    }
}

Tip

Legacy API

If you are using the legacy API, see our FAQ page to learn what changes you need to make to this code example.

For additional information on the classes and methods mentioned on this page, see the following API Documentation:

Back

Find

Find Many