Skip to content
Tutorials Center
My learning

Topics

Lesson 27 of 37 ยท Indexes and Performance

Indexes in Mongoose

Understand why indexes make queries fast, how to declare them in Mongoose with index, unique and schema.index(), when autoIndex should be off, and a runnable scan-versus-index comparison.

A collection with ten documents is fast no matter what you do. A collection with ten million documents is fast only if MongoDB does not have to look at all of them. Without an index, every query that filters on email performs a collection scan: it reads each document and checks the field. An index is a separate, sorted structure (a B-tree) that maps field values to documents, so the database can jump straight to the matches.

This lesson explains what indexes do, how Mongoose declares them, and the production rules around building them. Types of index (compound, text, TTL) follow in Compound, text and TTL indexes.

Scan versus index, in numbers

The stand-in below counts how many documents are examined when finding one user by email, with and without an index (a Map plays the role of the B-tree; real indexes are sorted trees with log n lookups, but the comparison holds).

Node.js Collection scan versus index lookup (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Indexes are not free: each one uses RAM and disk and must be updated on every insert and every update that touches an indexed field. The skill is indexing what you query, not everything.

Declaring indexes in a schema

There are three ways, all producing the same MongoDB index.

JavaScript
import mongoose from 'mongoose';
const { Schema, model } = mongoose;

const userSchema = new Schema({
  email: { type: String, required: true, unique: true }, // unique index
  username: { type: String, index: true },                 // ordinary index
  createdAt: { type: Date, default: Date.now },
  lastName: String,
  firstName: String,
});

// compound index, declared on the schema
userSchema.index({ lastName: 1, firstName: 1 });

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

The numbers are the sort direction: 1 ascending, -1 descending. For a single-field index the direction rarely matters because MongoDB can walk an index backward; for compound indexes it matters when you sort on several fields in opposite directions.

unique: true is not a validator. It creates a unique index, and the database rejects duplicates with an error whose code is 11000. Mongoose cannot check uniqueness before saving, so two simultaneous requests are both allowed to proceed and exactly one will fail. Handle it:

JavaScript
try {
  await User.create({ email });
} catch (err) {
  if (err.code === 11000) {
    throw new Error('That email is already registered');
  }
  throw err;
}
Node.js Unique is enforced by the database (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Index options worth knowing

  • unique: no two documents share the value. Missing values count as null, so a second document without the field also collides unless the index is sparse or partial.
  • sparse: true: index only documents that have the field.
  • partialFilterExpression: index only documents matching a filter, such as { deletedAt: null } (a unique email among non-deleted users).
  • collation: case-insensitive or locale-aware comparison: { locale: 'en', strength: 2 }. Queries must use the same collation to use that index.
  • background is obsolete; modern MongoDB builds indexes with minimal locking.
JavaScript
userSchema.index(
  { email: 1 },
  { unique: true, partialFilterExpression: { deletedAt: null } },
);

When are indexes created? autoIndex

By default Mongoose calls createIndexes() for every model when the app connects (autoIndex: true). That is perfect for development and tests. In production it is risky: on a large collection, a build can take minutes and put load on the database at startup, and it happens on every instance that boots.

Production practice is to turn it off and build indexes deliberately:

JavaScript
mongoose.set('autoIndex', false);          // global
// or per schema
const s = new Schema({ /* ... */ }, { autoIndex: false });

// in a migration or deploy script
await User.syncIndexes();   // creates missing, drops indexes not in the schema
await User.createIndexes(); // only creates; never drops

syncIndexes() makes MongoDB match your schema, which also drops indexes that are not declared. Run it on purpose and review the plan first (User.diffIndexes() shows what would change). For a very large collection, create the index with mongosh during a quiet period.

Do I need an index? A checklist

  1. Which queries run often? Index the fields in their filters and sorts.
  2. Which fields are in unique business rules (email, slug, order number)? Index them as unique.
  3. Do you populate through a reference or use virtual populate? Index the foreign field on the child.
  4. Is the field low-cardinality (a boolean, a status with three values)? A single-field index there helps little; combine it with other fields in a compound index.
  5. Are there indexes nobody uses? Remove them; they slow writes. db.collection.aggregate([{ $indexStats: {} }]) shows usage.
flowchart LR
  Q["query: email = ?"] --> I["index (sorted keys)"] --> D["document pointers"] --> R["documents"]

An index turns a full scan into a lookup.

Seeing what MongoDB does: explain

Add .explain('executionStats') to a query and compare totalDocsExamined with nReturned. If MongoDB examined 100000 documents to return 1, there is no usable index. A stage named IXSCAN means an index was used; COLLSCAN means it was not. The next lessons use this to tune compound indexes.

JavaScript
const plan = await User.find({ email: '[email protected]' }).explain('executionStats');
console.log(plan.executionStats.totalDocsExamined);

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does unique: true do in a Mongoose schema?

    It is an index option, not a validator. Duplicates are rejected by the database with error code 11000.
  2. 2. Why is autoIndex often turned off in production?

    Build indexes deliberately in a migration or deploy step instead of on every boot.
  3. 3. A query examines 100000 documents and returns 1. What does that suggest?

    Large totalDocsExamined compared to nReturned means MongoDB read many documents to find a few.
  4. 4. Which method also DROPS indexes that are not in your schema?

    syncIndexes() makes the database match the schema, creating and dropping. diffIndexes() only reports.

Summary

  • An index is a sorted lookup structure that avoids scanning the whole collection.
  • Declare indexes with the index/unique path options or schema.index().
  • unique is enforced by the database; handle error code 11000.
  • Turn autoIndex off in production and run syncIndexes() deliberately.
  • Index what you query, including foreign fields used by populate; verify with explain().

Next: Compound, text and TTL indexes