Find Multiple Documents

You can query for multiple documents in a collection by calling the find() method on a MongoCollection object. 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.

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

You can also chain methods to the find() method such as sort() which organizes the matched documents in a specified order and projection() which configures the included fields 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 which implements the core Java interface Iterable.

You can call the iterator() method on the MongoIterable which returns a MongoCursor instance that you can use to traverse the results. You can call methods on the MongoCursor such as hasNext() to check whether additional results exist, or next() to return the next document in the collection. If no documents match the query, calling hasNext() returns false and therefore calling next() throws an exception.

If you call next() on the iterator either after it has returned the final result or when no results exist, it throws an exception of type java.util.NoSuchElementException. Always use hasNext() to check that additional results exist before you call next().

Example

The following snippet finds and prints all documents that match a query on the movies collection. It uses the following objects and methods:

A query filter that is passed to the find() method. The lt() filter matches only movies with a runtime of less than 15 minutes.
A sort that organizes returned documents in descending order by title ("Z" before "A").
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 documents that match a query filter by using the Java driver
package usage.examples;
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;
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");
            // Creates instructions to project two document fields
            Bson projectionFields = Projections.fields(
                    Projections.include("title", "imdb"),
                    Projections.excludeId());
            // Retrieves documents that match the filter, applying a projection and a descending sort to the results
            MongoCursor<Document> cursor = collection.find(lt("runtime", 15))
                    .projection(projectionFields)
                    .sort(Sorts.descending("title")).iterator();
            // Prints the results of the find operation as JSON
            try {
                while(cursor.hasNext()) {
                    System.out.println(cursor.next().toJson());
                }
            } finally {
                cursor.close();
            }
        }
    }
}

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 One

Insert