Find Documents

On this page

Overview
Sample Data for Examples
Find Operation
Example
Find Example: Full File
Aggregate Operation
Example
Additional Information
API Documentation
Server Manual Entries

Overview

In this guide, you can learn how to retrieve documents from your MongoDB database. You can find your documents by using the following:

Retrieve a subset of documents from your collection using a find operation
Perform transformations on retrieved documents from your collection using an aggregate operation
Monitor real-time changes to your database using change streams

Sample Data for Examples

The following sections feature examples of how the owner of a paint store manages their customers' orders. For each order, the owner keeps track of the color and quantity, which corresponds to the color and qty fields in their paint_order collection:

{ "_id": 1, "color": "purple", "qty": 10 }
{ "_id": 2, "color": "green", "qty": 8 }
{ "_id": 3, "color": "purple", "qty": 4 }
{ "_id": 4, "color": "green", "qty": 11 }

Find Operation

Use the find operation to retrieve your documents from MongoDB. You can specify which documents to retrieve, in what order to retrieve them, and how many to retrieve.

Call the find() method on an instance of a MongoCollection to filter for documents that match the provided query. For more information about how to specify a query, see our Specify a Query guide.

You can then use methods such as forEach() or cursor() to retrieve matching documents. For more information, see the FindIterable API documentation.

To retrieve a single document, you can add the first() method to your find() call. To choose a specific document, you can use the sort() operation before selecting the first document. You may also want to use the limit() method to optimize memory usage. For more information, see the server manual for more information about memory optimization when using the sort operation.

Example

The owner would like to know which orders contain greater than three, but less than nine cans of paint from their paint_order collection.

To address this scenario, the owner finds orders to match the criteria:

Bson filter = Filters.and(Filters.gt("qty", 3), Filters.lt("qty", 9));
// Retrieves documents that match the filter and prints them as JSON
collection.find(filter).forEach(doc -> System.out.println(doc.toJson()));

For more information about how to build filters, see our Filters Builders guide.

The following shows the output of the preceding query:

{ "_id": 2, "color": "green", "qty": 8 }
{ "_id": 3, "color": "purple", "qty": 4 }

After the owner runs this query, they find two orders that matched the criteria.

Find Example: Full File

Note

Example Setup

This example connects to an instance of MongoDB by using a connection URI. To learn more about connecting to your MongoDB instance, see the Create a MongoClient guide. This example also uses the movies collection in the sample_mflix database included in the Atlas sample datasets. You can load them into your database on the free tier of MongoDB Atlas by following the Get Started with Atlas Guide.

This example is a complete, standalone file that performs the following actions:

Calls the find() method to retrieve 10 documents that has a runtime value less than 15 minutes, applying a projection and sort to the results
Calls the find() and first() methods to retrieve the document with the highest imdb.rating that is has a runtime value less than 15 minutes, applying a projection to the result

// Retrieves documents that match a query filter by using the Java driver
package org.example;
import static com.mongodb.client.model.Filters.lt;
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.MongoCursor;
import com.mongodb.client.MongoDatabase;
import com.mongodb.client.model.Projections;
import com.mongodb.client.model.Sorts;
import static com.mongodb.client.model.Filters.eq;
public class Find {
    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");
            // Projects "title" and "imdb" fields, excludes "_id"
            Bson projectionFields = Projections.fields(
                    Projections.include("title", "imdb"),
                    Projections.excludeId());
            // Retrieves documents with a runtime of less than 15 minutes, applying the
            // projection and a sorting in alphabetical order
            FindIterable<Document> docs = collection.find(lt("runtime", 15))
                    .projection(projectionFields)
                    .sort(Sorts.ascending("title"))
                    .limit(10);
            // Prints the titles of the queried documents
            System.out.println("10 movies under 15 minutes: ");
            docs.forEach(doc -> System.out.println("- " + doc.get("title")));
            System.out.println();
            // Retrieves the document with the best imdb rating that is less
            // than 15 minutes long, applying the projection
            Document doc = collection.find(lt("runtime", 15))
                    .projection(projectionFields)
                    .sort(Sorts.ascending("imdb.rating"))
                    .first();
            // Prints title of the queried document
            if (doc == null) {
                System.out.println("No results found.");
            } else {
                System.out.println("The highest rated movie under 15 minutes: " + doc.toJson().get("title"));
            }
        }
    }
}

10 movies under 15 minutes: 10 Minutes, 3x3, 7:35 in the Morning, 8, 9, A Chairy Tale, A Corner in Wheat, A Gentle Spirit, A Is for Autism, A Movie,
The highest rated movie under 15 minutes: {"title": "Andrè and Wally B.", "imdb": {"rating": 5.4, "votes": 3294, "id": 86855}}

Aggregate Operation

Use the aggregate operation to perform the stages in an aggregation pipeline. An aggregation pipeline is a multi-staged transformation that produces an aggregated result.

To perform an aggregate operation, call the aggregate() method on an instance of a MongoCollection. This method accepts aggregation expressions to run in sequence. To perform aggregations, you can define aggregation stages that specify how to match documents, rename fields, and group values. For more information, see our Aggregation guide and the Aggregation Expression Operations page.

Example

The owner would like to know which paint color is the most purchased (highest quantity sold) from their paint_order collection.

To address the scenario, the owner creates an aggregation pipeline that:

Matches all the documents in the paint_order collection
Groups orders by colors
Sums up the quantity field by color
Orders the results by highest-to-lowest quantity

Bson filter = Filters.empty();
// Prints the collection's "color" values and each value's frequency in descending frequency order
collection.aggregate(Arrays.asList(
    Aggregates.match(filter), 
    Aggregates.group("$color", Accumulators.sum("qty", "$qty")),
    Aggregates.sort(Sorts.descending("qty"))))
    .forEach(doc -> System.out.println(doc.toJson()));

The following shows the output of the preceding aggregation:

{ "_id": "green", "qty": 19 }
{ "_id": "purple", "qty": 14 }

After the owner runs the aggregation, they find that "green" is the most purchased color.

For more information about how to construct an aggregation pipeline, see the MongoDB Server manual page on Aggregation.

Additional Information

API Documentation

For more information about the methods and classes used to retrieve documents on this page, see the following API documentation:

Server Manual Entries

Back

Specify a Query

Count Documents