For the most recent version of the reference documentation, see our MongoDB Java Driver documentation site.
- MongoDB Driver
- Tutorials
- Read Operations
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 thetest
database. To create and populate the collection, follow the directions in github.Include the following import statements:
import com.mongodb.*; 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.Projections; import com.mongodb.client.model.Filters; import static com.mongodb.client.model.Filters.*; import static com.mongodb.client.model.Projections.*; import com.mongodb.client.model.Sorts; import java.util.Arrays; import org.bson.Document;
Include the following code which the examples in the tutorials 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()); } };
Connect to a MongoDB Deployment
Connect to a MongoDB deployment and declare and define a MongoDatabase
instance and a MongoCollection
instance
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 collection’s find()
method.
You can call the method without any arguments to query all documents in a collection:
collection.find().forEach(printBlock);
Or pass a filter to query for documents that match the filter criteria:
collection.find(eq("name", "456 Cookies Shop"))
.forEach(printBlock);
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);
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);
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, ANDthe
categories
field equals"Bakery"
(or ifcategories
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);
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);
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 iterator()
and 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);
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);
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);
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);
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()
- Via
MongoClientSettings
:
MongoClient mongoClient = MongoClients.create(MongoClientSettings.builder() .applyConnectionString(new ConnectionString("mongodb://host1,host2")) .readPreference(ReadPreference.secondary()) .build());
- Via
ConnectionString
, as in the following example:
MongoClient mongoClient = MongoClients.create("mongodb://host1:27017,host2:27017/?readPreference=secondary");
- Via
In a
MongoDatabase
via itswithReadPreference
method.MongoDatabase database = mongoClient.getDatabase("test") .withReadPreference(ReadPreference.secondary());
In a
MongoCollection
via itswithReadPreference
method: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()
- Via
MongoClientURI
, as in the following example:
MongoClient mongoClient = new MongoClient( new MongoClientURI("mongodb://host1:27017,host2:27017/?readConcernLevel=majority"));
- Via
MongoClientOptions
, as in the following example:
MongoClientOptions options = MongoClientOptions.builder().readConcern(ReadConcern.DEFAULT).build(); MongoClient mongoClient = new MongoClient(Arrays.asList( new ServerAddress("host1", 27017), new ServerAddress("host1", 27017)), options);
- Via
In a
MongoDatabase
via itswithReadConcern
method, as in the following example:MongoDatabase database = mongoClient.getDatabase("test") .withReadConcern(ReadConcern.DEFAULT);
In a
MongoCollection
via itswithReadConcern
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);