An Introduction to Queries in Mongoose

Jun 25, 2019

Many Mongoose model functions, like find(), return a Mongoose query. The Mongoose Query class provides a chaining interface for finding, updating, and deleting documents.

const Character = mongoose.model('Character', Schema({
  name: String,
  age: Number

const query = Character.find();
query instanceof mongoose.Query; // true

// Execute the query
const docs = await query;


The first parameter to Model.find() is called the query filter. When you call find(), MongoDB will return all documents that match the query filter. You can use Mongoose's numerous query helpers to build up query filters. Just make sure you specify the property name to add to the filter using where().

let docs = await Character.find().
  // `where()` specifies the name of the property
  // and then the query helper `in()` specifies that `name`
  // must be one of the 2 values in the array
  in(['Jean-Luc Picard', 'Will Riker']);

// Equivalent query, but with the filter expressed as an object rather
// than using chaining
docs = await Character.find({
  name: { $in: ['Jean-Luc Picard', 'Will Riker'] }

Chainable operations let you add to the current query filter. You can get the query's current filter using the Query#getFilter() function.

const query = Character.find().
  where('name').in(['Jean-Luc Picard', 'Will Riker']);
// `{ name: { $in: ['Jean-Luc Picard', 'Will Riker'] } }`

Here's a list of several useful query helpers:

You can chain arbitrarily many where() calls and query helpers to build up your query. For example:

const docs = await Character.find().
  // `name` must match the regular expression
  // `age` must be between 29 and 59


Mongoose queries are not promises. The key difference is that Mongoose doesn't actually send your query to the server until you explicitly execute the query. There's 2 ways to execute a query:

const promise = Character.find().exec();
promise instanceof Promise; // true
promise instanceof mongoose.Query; // false

const docs = await promise;
return Character.find().then(docs => {
  docs; // List of docs

Want to become your team's MongoDB expert? "Mastering Mongoose" distills 8 years of hard-earned lessons building Mongoose apps at scale into 153 pages. That means you can learn what you need to know to build production-ready full-stack apps with Node.js and MongoDB in a few days. Get your copy!

Did you find this tutorial useful? Say thanks by starring our repo on GitHub!

More Mongoose Tutorials