Querying with Mongoose — find, findOne, findById and Query Chains

Querying is the most frequent operation in any MERN application — every API endpoint that returns data to React involves a Mongoose query. Mongoose’s query API is built around a chainable builder pattern: you start with a method like find() or findOne(), chain on modifiers like sort(), limit(), select(), and populate(), and then await the chain to execute it. Understanding the difference between a Mongoose Query object and a resolved Promise, when to use lean(), and how to build efficient queries are the skills covered in this lesson.

Core Query Methods #

find() — Get Many Documents #

// ── Basic find ─────────────────────────────────────────────────────────────────
const posts = await Post.find({ published: true });
// Returns: Array of Mongoose document instances

// ── Chaining query methods ─────────────────────────────────────────────────────
const posts = await Post
  .find({ published: true, tags: 'mern' })  // filter
  .sort({ createdAt: -1 })                   // newest first
  .skip(0)                                   // pagination offset
  .limit(10)                                 // max 10 results
  .select('title slug excerpt createdAt')    // only these fields
  .populate('author', 'name avatar')         // resolve author reference
  .lean();                                   // return plain JS objects

// ── Empty result — find returns an empty array, not null ─────────────────────
const posts = await Post.find({ tags: 'nonexistent-tag' });
console.log(posts);        // []  ← empty array, not null
console.log(posts.length); // 0

// ── Dynamic filter building ────────────────────────────────────────────────────
const filter = { published: true };
if (req.query.tag)    filter.tags   = req.query.tag;
if (req.query.author) filter.author = req.query.author;
if (req.query.search) filter.$text  = { $search: req.query.search };

const posts = await Post.find(filter).sort({ createdAt: -1 }).limit(10).lean();

findOne() and findById() #

// ── findOne — first match or null ────────────────────────────────────────────
const post = await Post.findOne({ slug: req.params.slug });
if (!post) throw new AppError('Post not found', 404);

// ── findById — by _id or null ─────────────────────────────────────────────────
const post = await Post.findById(req.params.id);
if (!post) throw new AppError('Post not found', 404);

// ── findById with populate and select ─────────────────────────────────────────
const post = await Post.findById(req.params.id)
  .populate('author', 'name avatar bio')
  .select('-__v');

// ── findOne with select('+password') — opt in to excluded fields ───────────────
const user = await User.findOne({ email: req.body.email }).select('+password');
// select: false fields are excluded by default
// prefix with '+' to explicitly include them when needed (auth login route)

Query Chain Methods #

Efficient Pagination with countDocuments #

const getAllPosts = asyncHandler(async (req, res) => {
  const page  = Math.max(1, parseInt(req.query.page,  10) || 1);
  const limit = Math.min(100, parseInt(req.query.limit, 10) || 10);
  const skip  = (page - 1) * limit;

  const filter = { published: true };
  if (req.query.tag) filter.tags = req.query.tag;

  // Run count and data fetch in parallel for maximum efficiency
  const [posts, total] = await Promise.all([
    Post.find(filter)
      .sort({ createdAt: -1 })
      .skip(skip)
      .limit(limit)
      .populate('author', 'name avatar')
      .lean(),
    Post.countDocuments(filter), // separate efficient count query
  ]);

  res.json({
    success: true,
    data:    posts,
    total,
    page,
    pages:   Math.ceil(total / limit),
    count:   posts.length,
  });
});

Mongoose Query vs Promise #

// A Mongoose Query is NOT a native Promise
const q = Post.find({ published: true }); // q is a Query object — not awaited yet
q.sort({ createdAt: -1 });                // chaining still works
q.limit(10);                              // still not executed

// Three ways to execute a Mongoose Query:
const posts = await q;                    // 1. await (most common)
const posts = await q.exec();            // 2. .exec() — returns a true Promise
q.then(posts => console.log(posts));     // 3. .then() — thenable

// All three are equivalent — the query runs when consumed

// Why does this matter? Conditional query building:
let query = Post.find({ published: true });

if (req.query.tag) {
  query = query.where('tags').equals(req.query.tag); // add condition without executing
}

if (req.query.sort === 'views') {
  query = query.sort({ viewCount: -1 });
} else {
  query = query.sort({ createdAt: -1 });
}

const posts = await query.limit(10).lean(); // executed here with all conditions applied

Common Mistakes #

Mistake 1 — Not checking for null after findById #

❌ Wrong — trying to access properties on null:

const post = await Post.findById(req.params.id);
res.json({ data: post }); // post could be null — React gets { data: null }

✅ Correct — always null-check:

const post = await Post.findById(req.params.id);
if (!post) throw new AppError('Post not found', 404);
res.json({ success: true, data: post }); // ✓

Mistake 2 — Calling find without any filter and not limiting #

❌ Wrong — fetching the entire collection:

const posts = await Post.find(); // entire collection — could be 1,000,000 docs

✅ Correct — always filter and limit:

const posts = await Post.find({ published: true }).limit(10).lean(); // ✓

Mistake 3 — Awaiting individual methods in a chain instead of the whole chain #

❌ Wrong — awaiting each method separately:

const query = await Post.find({ published: true }); // executes immediately
const sorted = await query.sort({ createdAt: -1 }); // TypeError — result is not a Query

✅ Correct — chain all modifiers before awaiting:

const posts = await Post.find({ published: true }).sort({ createdAt: -1 }).limit(10); // ✓

Quick Reference #