Guide to Find in MongoDB

1. Overview

In this tutorial, we’ll look at performing search operations to retrieve documents in MongoDB. MongoDB provides a find operator to query documents from a collection. The main purpose of the find operator is to select documents from a collection based on the query condition and return a cursor to the selected documents.

In this tutorial, we’ll first look at the find operator in the MongoDB Shell query and then use the Java driver code.

2. Database Initialization

Before we move forward to perform the find operations, we first need to set up a database baeldung and a sample collection employee:

db.employee.insertMany([
{
    "employeeId":"EMP1",
    "name":"Sam", 
    "age":23,
    "type":"Full Time",
    "department":"Engineering"
},
{ 
    "employeeId":"EMP2",
    "name":"Tony",
    "age":31,
    "type":"Full Time",
    "department":"Admin"
},
{
    "employeeId":"EMP3",
    "name":"Lisa",
    "age":42,
    "type":"Part Time",
    "department":"Engineering"
}]);

Upon successful insertion, the above query would return a JSON result similar to the one shown below:

{
    "acknowledged" : true,
    "insertedIds" : [
        ObjectId("62a88223ff0a77909323a7fa"),
        ObjectId("62a88223ff0a77909323a7fb"),
        ObjectId("62a88223ff0a77909323a7fc")
    ]
}

At this point, we’ve inserted a few documents into our collection to perform various types of find operations.

3. Using the MongoDB Shell

To query documents from a MongoDB collection, we make use of the db.collection.find(query, projection) method. The method accepts two optional parameters – query and projection – as MongoDB BSON documents.

The query parameter accepts a selection filter with query operators. To retrieve all the documents from the MongoDB collection, we can omit this parameter or pass a blank document.

Next, the projection parameter is used to specify the fields to return from the matching documents. To return all the fields in the matching document, we can omit this parameter.

Further, let’s start with a basic find query that would return all the collection documents:

db.employee.find({});

The above query will return all the documents from the employee collection:

{ "_id" : ObjectId("62a88223ff0a77909323a7fa"), "employeeId" : "1", "name" : "Sam", "age" : 23, "type" : "Full Time", "department" : "Engineering" }
{ "_id" : ObjectId("62a88223ff0a77909323a7fb"), "employeeId" : "2", "name" : "Tony", "age" : 31, "type" : "Full Time", "department" : "Admin" }
{ "_id" : ObjectId("62a88223ff0a77909323a7fc"), "employeeId" : "3", "name" : "Ray", "age" : 42, "type" : "Part Time", "department" : "Engineering" }

Next, let’s write a query to return all employees who belong to the “Engineering” department:

db.employee.find(
{
    "department":"Engineering"
});

The above query returns all employee collection documents with department equal to “Engineering”:

{ "_id" : ObjectId("62a88223ff0a77909323a7fa"), "employeeId" : "1", "name" : "Sam", "age" : 23, "type" : "Full Time", "department" : "Engineering" }
{ "_id" : ObjectId("62a88223ff0a77909323a7fc"), "employeeId" : "3", "name" : "Ray", "age" : 42, "type" : "Part Time", "department" : "Engineering" }

Finally, let’s write a query to fetch the name and age of all the employees that belong to the “Engineering” department:

db.employee.find(
{
    "department":"Engineering"
},
{
    "name":1,
    "age":1
});

The above query returns only the name and age fields of the documents matching the query condition:

{ "_id" : ObjectId("62a88223ff0a77909323a7fa"), "name" : "Sam", "age" : 23 }
{ "_id" : ObjectId("62a88223ff0a77909323a7fc"), "name" : "Ray", "age" : 42 }

Notice that the _id field is returned by default in all the documents unless explicitly excluded.

Also, it’s important to note that the find operator returns a cursor to the documents that match the query filter. The MongoDB Shell automatically iterates the cursor to display up to 20 documents.

In addition, the MongoDB Shell provides a findOne() method that returns just one document that satisfies the mentioned query criteria. If multiple documents match, the first document will be returned according to the natural order of documents on the disk:

db.employee.findOne();

Unlike find(), the above query would return only a single document instead of a cursor:

{
    "_id" : ObjectId("62a99e22a849e1472c440bbf"),
    "employeeId" : "EMP1",
    "name" : "Sam",
    "age" : 23,
    "type" : "Full Time",
    "department" : "Engineering"
}

4. Using the Java Driver

So far, we’ve seen how to use the MongoDB Shell to perform the find operation. Next, let’s implement the same using the MongoDB Java driver. Before we start, let’s first create a MongoClient connection to the employee collection:

MongoClient mongoClient = new MongoClient("localhost", 27017);
MongoDatabase database = mongoClient.getDatabase("baeldung");
MongoCollection<Document> collection = database.getCollection("employee");

Here, we created a connection to the MongoDB Server running on default port 27017. Next, we obtained an instance of MongoCollection from the MongoDatabase instance created from the connection.

Firstly, to perform a find operation, we call the find() method on an instance of MongoCollection. Let’s check the code to retrieve all documents from the collection:

FindIterable<Document> documents = collection.find();
MongoCursor<Document> cursor = documents.iterator();
while (cursor.hasNext()) {
    System.out.println(cursor.next());
}

Notice that the find() method returns an instance of FindIterable<Document>. We then obtain an instance of MongoCursor by calling the iterator() method of FindIterable. Finally, we iterate over the cursor to retrieve each document.

Next, let’s add query operators to filter the documents returned from the find operation:

Bson filter = Filters.eq("department", "Engineering");
FindIterable<Document> documents = collection.find(filter);

MongoCursor<Document> cursor = documents.iterator();
while (cursor.hasNext()) {
    System.out.println(cursor.next());
}

Here, we pass a Bson filter as a parameter to the find() method. We can use any combination of the query operators as a filter for the find() method. The above snippet would return all documents where the department equals “Engineering”.

Further, let’s write a snippet that returns only the name and age fields from the documents matching the selection criteria:

Bson filter = Filters.eq("department", "Engineering");
Bson projection = Projections.fields(Projections.include("name", "age"));
FindIterable<Document> documents = collection.find(filter)
  .projection(projection);

MongoCursor<Document> cursor = documents.iterator();
while (cursor.hasNext()) {
    System.out.println(cursor.next());
}

Here, we call the projection() method on the FindIterable instance. We pass a Bson filter as a parameter to the projection() method. We can include or exclude any fields from the final results using the projection operation. As an alternative to using the MongoDB Driver and Bson directly, please take a look at our guide to Projection in Spring Data MongoDB.

Lastly, we can retrieve the first document of the result using the first() method on the FindIterable instance. This returns a single document instead of a MongoCursor instance:

FindIterable<Document> documents = collection.find();
Document document = documents.first();

5. Conclusion

In this article, we’ve learned to perform the find operation in MongoDB using various methods. We performed find to retrieve specific documents that match selection criteria using the query operators. In addition, we also learned to perform a projection to determine which fields are returned in the matching documents.

At first, we looked into the use cases of find operations in the MongoDB Shell query, and then we discussed the corresponding Java driver code.