MongodbHow-ToBeginner · 3 min read

How to Use findOne in Mongoose: Syntax and Examples

In Mongoose, use findOne to find the first document that matches a query in a collection. It takes a filter object and returns a single document or null if none matches. You can use it with callbacks or async/await for easy database queries.

📐

Syntax

The findOne method searches for the first document matching the filter criteria.

filter: An object specifying the search conditions.
projection (optional): Fields to include or exclude.
options (optional): Additional query options.
callback (optional): Function to handle the result.

If no callback is provided, findOne returns a Promise.

javascript

Model.findOne(filter, [projection], [options], [callback])

💻

Example

This example shows how to use findOne with async/await to find a user by their email.

javascript

const mongoose = require('mongoose');

// Define a simple User schema
const userSchema = new mongoose.Schema({
  name: String,
  email: String,
  age: Number
});

const User = mongoose.model('User', userSchema);

async function findUserByEmail(email) {
  try {
    await mongoose.connect('mongodb://localhost:27017/testdb');

    const user = await User.findOne({ email: email });

    if (user) {
      console.log('User found:', user);
    } else {
      console.log('No user found with email:', email);
    }

    await mongoose.disconnect();
  } catch (error) {
    console.error('Error:', error);
  }
}

findUserByEmail('alice@example.com');

Output

User found: { _id: ObjectId("..."), name: 'Alice', email: 'alice@example.com', age: 30, __v: 0 }

⚠️

Common Pitfalls

Common mistakes when using findOne include:

Not awaiting the Promise or missing a callback, causing unexpected behavior.
Using incorrect filter keys or values that do not match any document.
Expecting multiple results; findOne returns only the first match.
Not handling null result when no document matches.

Always check if the result is null before accessing document fields.

javascript

/* Wrong: Missing await, result is a Promise */
const user = await User.findOne({ email: 'bob@example.com' });
console.log(user); // Prints user document

/* Right: Using await to get the document */
const userCorrect = await User.findOne({ email: 'bob@example.com' });
console.log(userCorrect);

📊

Quick Reference

Parameter	Description	Example
filter	Object to specify search criteria	{ email: 'test@example.com' }
projection	Fields to include or exclude	{ name: 1, email: 1 }
options	Additional query options	{ sort: { age: -1 } }
callback	Function to handle result	(err, doc) => { ... }

✅

Key Takeaways

Use findOne to get the first document matching your filter in Mongoose.

Always await findOne or provide a callback to handle the result properly.

Check if the result is null before accessing document properties.

findOne returns only one document, not multiple matches.

You can specify fields to return using the projection parameter.