Find Operations

Find operations retrieve documents from a collection. You can specify a filter to select only those documents that match the filter condition.

Prerequisites

  • The example below requires a restaurants collection in the test database. To create and populate the collection, follow the directions in github.

  • Include the following import statements:

import com.mongodb.*;
import com.mongodb.async.SingleResultCallback;
import com.mongodb.async.client.*;
import com.mongodb.client.model.Sorts;
import com.mongodb.connection.ClusterSettings;
import org.bson.Document;

import static com.mongodb.client.model.Filters.*;
import static com.mongodb.client.model.Projections.excludeId;
import static com.mongodb.client.model.Projections.fields;
import static com.mongodb.client.model.Projections.include;
import static java.util.Arrays.asList;
  • Include the following callback code which the examples in the tutorials will use:
SingleResultCallback<Void> callbackWhenFinished = new SingleResultCallback<Void>() {
    @Override
    public void onResult(final Void result, final Throwable t) {
        System.out.println("Operation Finished!");
    }
};
  • Include the following code which the examples will use to print the results of the find operations:
Block<Document> printBlock = new Block<Document>() {
    @Override
    public void apply(final Document document) {
        System.out.println(document.toJson());
    }
};

Considerations

important

Always check for errors in any SingleResultCallback<T> implementation and handle them appropriately.

For sake of brevity, this tutorial omits the error check logic in the code examples.

Connect to a MongoDB Deployment

Connect to a MongoDB deployment and declare and define a MongoDatabase and a MongoCollection instances.

For example, include the following code to connect to a standalone MongoDB deployment running on localhost on port 27017 and define database to refer to the test database and collection to refer to the restaurants collection:

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

For additional information on connecting to MongoDB, see Connect to MongoDB.

Query a Collection

To query the collection, you can use the find() method.

You can call the method without any arguments to query all documents in a collection:

collection.find().forEach(printBlock, callbackWhenFinished);

Or pass a filter to query for documents that match the filter criteria:

collection.find(eq("name", "456 Cookies Shop"))
            .forEach(printBlock, callbackWhenFinished);

Query Filters

To query for documents that match certain conditions, pass a filter document to the find() method.

Empty Filter

To specify an empty filter (i.e. match all documents in a collection), use an empty Document object.

collection.find(new Document()).forEach(printBlock, callbackWhenFinished);
tip

For the find() method, you can also call the method without passing a filter object to match all documents in a collection.

collection.find().forEach(printBlock, callbackWhenFinished);

Filters Helper

To facilitate the creation of filter documents, the Java driver provides the Filters class that provides filter condition helper methods.

Consider the following find operation which includes a filter Document which specifies that:

  • the stars field is greater than or equal to 2 and less than 5, AND

  • the categories field equals "Bakery" (or if categories is an array, contains the string "Bakery" as an element):

collection.find(
    new Document("stars", new Document("$gte", 2)
          .append("$lt", 5))
          .append("categories", "Bakery")).forEach(printBlock, callbackWhenFinished);

The following example specifies the same filter condition using the Filters helper methods:

collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
            .forEach(printBlock, callbackWhenFinished);

For a list of MongoDB query filter operators, refer to the MongoDB Manual. For the associated Filters helpers, see Filters. See also the Query Documents Tutorial for an overview of querying in MongoDB, including specifying filter conditions on arrays and embedded documents.

FindIterable

The find() method returns an instance of the FindIterable interface. The interface provides various methods that you can chain to the find() method to modify the output or behavior of the query, such as sort() or projection(), as well as for iterating the results, such as forEach().

Projections

By default, queries in MongoDB return all fields in matching documents. To specify the fields to return in the matching documents, you can specify a projection document.

Consider the following find operation which includes a projection Document which specifies that the matching documents return only the name field, stars field, and the categories field.

collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
                .projection(new Document("name", 1)
                     .append("stars", 1)
                     .append("categories",1)
                     .append("_id", 0))
                .forEach(printBlock, callbackWhenFinished);

To facilitate the creation of projection documents, the Java driver provides the Projections class.

collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
                .projection(fields(include("name", "stars", "categories"), excludeId()))
                .forEach(printBlock, callbackWhenFinished);

In the projection document, you can also specify a projection expression using a projection operator

For an example on using the Projections.metaTextScore, see the Text Search tutorial.

Sorts

To sort documents, pass a sort specification document to the FindIterable.sort() method. The Java driver provides Sorts helpers to facilitate the sort specification document.

collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
                .sort(Sorts.ascending("name"))
                .forEach(printBlock, callbackWhenFinished);

Sort with Projections

The FindIterable methods themselves return FindIterable objects, and as such, you can append multiple FindIterable methods to the find() method.

collection.find(and(gte("stars", 2), lt("stars", 5), eq("categories", "Bakery")))
                .sort(Sorts.ascending("name"))
                .projection(fields(include("name", "stars", "categories"), excludeId()))
                .forEach(printBlock, callbackWhenFinished);

MongoIterable

The MongoIterable interface provides helper methods to access the results of an operation:

Read Preference

For read operations on replica sets or sharded clusters, applications can configure the read preference at three levels:

  • In a MongoClient()

      ClusterSettings clusterSettings = ClusterSettings.builder()
                            .hosts(asList(
                            new ServerAddress("host1", 27017),
                            new ServerAddress("host2", 27017))).build();
  MongoClientSettings settings = MongoClientSettings.builder()
                                    .clusterSettings(clusterSettings)
                                    .readPreference(ReadPreference.secondary())
                                    .build();
  MongoClient mongoClient = MongoClients.create(settings);

      MongoClient mongoClient = MongoClients.create(new ConnectionString(
        "mongodb://host1:27017,host2:27017/?readPreference=secondary"));
    • Via string that specifies the connection URI:
      MongoClient mongoClient = MongoClients.create(
        "mongodb://host1:27017,host2:27017/?readPreference=secondary");

  • In a MongoDatabase via its withReadPreference method, as in the following example:

     MongoDatabase database = mongoClient.getDatabase("test")     
        .withReadPreference(ReadPreference.secondary());

  • In a MongoCollection via its withReadPreference method, as in the following example:

    MongoCollection<Document> collection = database.getCollection("restaurants")
          .withReadPreference(ReadPreference.secondary());

MongoDatabase and MongoCollection instances are immutable. Calling .withReadPreference() on an existing MongoDatabase or MongoCollection instance returns a new instance and does not affect the instance on which the method is called.

For example, in the following, the collectionWithReadPref instance has the read preference of primaryPreferred whereas the read preference of the collection is unaffected.

  MongoCollection<Document> collectionWithReadPref =
                collection.withReadPreference(ReadPreference.primaryPreferred());

Read Concern

For read operations on replica sets or sharded clusters, applications can configure the read concern at three levels:

  • In a MongoClient()

      ClusterSettings clusterSettings = ClusterSettings.builder()
                            .hosts(asList(
                            new ServerAddress("host1", 27017),
                            new ServerAddress("host2", 27017))).build();
  MongoClientSettings settings = MongoClientSettings.builder()
                                    .clusterSettings(clusterSettings)
                                    .readConcern(ReadConcern.DEFAULT)
                                    .build();
  MongoClient mongoClient = MongoClients.create(settings);

      MongoClient mongoClient = MongoClients.create(new ConnectionString(
          "mongodb://host1:27017,host2:27017/?readConcernLevel=majority"));
    • Via string that specifies the connection URI:
      MongoClient mongoClient = MongoClients.create(
          "mongodb://host1:27017,host2:27017/?readConcernLevel=majority");

  • In a MongoDatabase via its withReadConcern method, as in the following example:

     MongoDatabase database = mongoClient.getDatabase("test")
                            .withReadConcern(ReadConcern.DEFAULT);

  • In a MongoCollection via its withReadConcern method, as in the following example:

    MongoCollection<Document> collection = database.getCollection("restaurants")
                            .withReadConcern(ReadConcern.DEFAULT);

MongoDatabase and MongoCollection instances are immutable. Calling .withReadConcern() on an existing MongoDatabase or MongoCollection instance returns a new instance and does not affect the instance on which the method is called.

For example, in the following, the collWithReadConcern instance has majority read concern whereas the read concern of the collection is unaffected.

MongoCollection<Document> collWithReadConcern = collection
                                                  .withReadConcern(ReadConcern.MAJORITY);

You can build MongoClientOptions, MongoDatabase, or MongoCollection to include a combination of read concern, read preference, and write concern.

For example, the following sets all three at the collection level:

collection = database.getCollection("restaurants")
                .withReadPreference(ReadPreference.primary())
                .withReadConcern(ReadConcern.MAJORITY)
                .withWriteConcern(WriteConcern.MAJORITY);
On this page