What is MongoDB findOne and how to use it

The MongoDB findOne method is great for searching a collection. However, it only returns a single result, making it unsuitable for many types of searches.

What is MongoDB findOne?

MongoDB is a database management system that can easily store and manage large amounts of data thanks to its NoSQL approach and remarkable scalability. While these aspects offer users significant advantages, it also means that the system needs strong methods to ensure users can effectively navigate the database.

The system saves data of all types in the form of a BSON document (binary JSON) and bundles these documents into collections. If you want to search for and output one of these documents, there are several options available to you. In addition to the more general search method MongoDB find, MongoDB findOne is a highly effective method for filtering through large databases with precision.

MongoDB findOne searches all documents and collections according to certain criteria specified by the user. The special feature of this method is that it always returns exactly one document. If there is only one document in the search query, this document will be returned. If several documents match the parameters defined by the user, MongoDB findOne will return the document that appears first in the natural order of the database. If no documents can be found in the search, the output is “null”.

What is the syntax for MongoDB findOne?

The basic syntax of MongoDB findOne is straightforward. The method is used like this:

db.collection.findOne ( <query>, <projection>, <options> )

Under <query>, you can specify how the method should filter the documents.

Under <projection>, you can specify which fields should be shown for the document that is returned. Use the Boolean values 1 (true/include) and 0 (false/exclude) to indicate if a field should be included. If this parameter remains empty, all fields will be displayed.

The third search parameter <options> allows you to further modify the search and also change the display. All three search parameters are optional.

How to create a collection for testing purposes

If you’ve installed MongoDB on Linux, Windows or Mac and want to use MongoDB findOne, it’s worth setting up a test environment to experiment with the method.

If you haven’t set up a database yet, read our comprehensive MongoDB tutorial to learn how to set one up. In our example below, we’re going to use an employee database containing five entries. Each entry contains information about the name, gender and age of employees as well as how long the person has been with the company. The collection looks like this:

db.employee.insertMany ( [
    {
    name : "Smith",
    gender : "Female",
    age : 56,
    year : 2002
    },
    {
    name : "Jones",
    gender : "Female",
    age : 40,
    year : 2017,
    },
    {
    name : "Brown",
    gender : "Male",
    age : 40,
    year : 2019
    },
    {
    name : "Michaels",
    gender : "Female",
    age : 44,
    year : 2015
    },
    name : "Cartwright",
    gender : "Male",
    age : 22,
    year : 2022
    }
]
)

What are different ways to search with Mongo DB findOne?

There’s more than one way to search for information using MongoDB findOne. You can search without parameters, with an ID, with one field or with several fields.

Searching without parameters

If you are using the MongoDB findOne method without any parameters, the system will search your database and take all entries into consideration. In our example, this means the method will identify five entries. Since none of the documents are excluded and the method only returns one result, MongoDB findOne will select the first person that was entered into the database.

db.employee.findOne ( )

The output is:

db.employee.findOne ( )
{
    _id : ObjectID ( "529ete7300of4002bme148om" ),
    name : "Smith",
    gender : "Female",
    age : 56,
    year : 2002
}

Searching by ID

Normally, you want to provide some sort of criteria for your search so that you end up with the document you actually need. One way you can search for documents with MongoDB findOne is by searching for an ID.

The _id field is unique in every document. In our example, each ID represents exactly one employee. If you run MongoDB findOne using the object ID, you’ll get the exact result you are looking for.

db.employee.findOne ( { _id : ObjectID ( "582pfh773813tw982qj411l0" ) } )

The output looks like this:

db.employee.findOne ( { _id : ObjectID ( "582pfh773813tw982qj411l0" ) } )
{
    _id : ObjectID ( "582pfh773813tw982qj411l0"
    name : "Cartwright",
    gender : "Male",
    age : 22,
    year : 2022
}

Searching using specific fields

If you don’t know the ID or want to search your collection for other parameters, you can also use MongoDB findOne to search for specific fields. If there is only one document that matches the parameter, that’s the document that will be displayed. However, if several documents match your search criteria, the system will only display the first entry.

In the example below, we’re going to search for all entries with “Male” as the gender. Here’s the command:

db.employee.findOne ( { gender : "Male" } )

There are two entries that match this criteria, however only one will be displayed. The output displays the employee Mr. Brown:

db.employee.findOne ( { gender : "Male" } )
{
    _id : ObjectID ( "498p0t173mv489fh63th00kh"
    name : "Brown",
    gender : "Male",
    age : 40,
    year : 2019
}

Searching using several fields

You also have the option of narrowing down your search further to prevent any overlaps. This may not be necessary for our small sample collection, but if you are working with several hundred or even thousands of entries, this option comes in handy. MongoDB findOne allows you to use several fields for the search. If you want to identify an employee by gender (male) and age, you can write the following:

db.employee.findOne ( { gender : "Male", age: 40 } )

The output once again shows Mr. Brown, who is the only person in the collection who is male and 40 years old. Ms. Jones is the same age, but her gender doesn’t match the criteria, so the result looks like this:

db.employee.findOne ( { gender : "Male", age: 40 } )
{
    _id : ObjectID ( "498p0t173mv489fh63th00kh"
    name : "Brown",
    gender : "Male",
    age : 40,
    year : 2019
}

How to set conditions for a field using MongoDB findOne

It’s also possible to define conditions for a specific field and use these as search criteria. In the following example, we are only searching for employees who are over 30.

This entry looks like this:

db.employee.findOne ( { age : { $gt : 30 } } )

This excludes Mr. Cartwright. Since Ms. Smith is over 30 and is the first person in the list, she appears as the result:

db.employee.findOne ( { age : { $gt : 30 } } )
{
    _id : ObjectID ( "529ete7300of4002bme148om" ),
    name : "Smith",
    gender : "Female",
    age : 56,
    year : 2002
}

How to exclude fields with MongoDB findOne

If you have extensive collections that contain a lot of information, the output can include too much information. Fortunately, MongoDB findOne also offers the option to exclude fields from the output. In the following example, we don’t want to display ID, gender and age in the output.

db.employee.findOne ( { name : "Smith" }, { _id : 0, gender : 0, age : 0 } )

You’ll receive the following output:

db.employee.findOne ( { name : "Smith" }, { _id : 0, gender : 0, age : 0 } )
{
    name : "Smith",
    year : 2002
}

What happens if MongoDB findOne can’t find any results for my search?

If there are no results for your search with MongoDB findOne, an output will still be displayed. To illustrate what happens, we’ll search for Ms. Larkham, who is not in the collection.

db.employee.findOne ( { name : "Larkham" }  )

The output for this is:

db.employee.findOne ( { name : "Larkham" }  )
null