Model

A Model is a class that's your primary tool for interacting with MongoDB. An instance of a Model is called a Document.

In Mongoose, the term "Model" refers to subclasses of the mongoose.Model class. You should not use the mongoose.Model class directly. The mongoose.model() and connection.model() functions create subclasses of mongoose.Model as shown below.

Example:

// `UserModel` is a "Model", a subclass of `mongoose.Model`.
const UserModel = mongoose.model('User', new Schema({ name: String }));

// You can use a Model to create new documents using `new`:
const userDoc = new UserModel({ name: 'Foo' });
await userDoc.save();

// You also use a model to create queries:
const userFromDb = await UserModel.findOne({ name: 'Foo' });

Creates a Query and specifies a $where condition.

Sometimes you need to query for things in mongodb using a JavaScript expression. You can do so via find({ $where: javascript }), or you can use the mongoose shortcut method $where via a Query chain or from your mongoose Model.

Blog.$where('this.username.indexOf("val") !== -1').exec(function (err, docs) {});

Performs aggregations on the models collection.

The aggregate itself is returned.

This function triggers the following middleware.

• aggregate()

Example:

// Find the max balance of all accounts
const res = await Users.aggregate([
  { $group: { _id: null, maxBalance: { $max: '$balance' }}},
  { $project: { _id: 0, maxBalance: 1 }}
]);

console.log(res); // [ { maxBalance: 98000 } ]

// Or use the aggregation pipeline builder.
const res = await Users.aggregate().
  group({ _id: null, maxBalance: { $max: '$balance' } }).
  project('-id maxBalance').
  exec();
console.log(res); // [ { maxBalance: 98 } ]

Note:

• Mongoose does not cast aggregation pipelines to the model's schema because $project and $group operators allow redefining the "shape" of the documents at any stage of the pipeline, which may leave documents in an incompatible format. You can use the mongoose-cast-aggregation plugin to enable minimal casting for aggregation pipelines.
• The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).

More About Aggregations:

• Mongoose Aggregate
• An Introduction to Mongoose Aggregate
• MongoDB Aggregation docs

Apply defaults to the given document or POJO.

Apply this model's timestamps to a given POJO, including subdocument timestamps

Example:

const userSchema = new Schema({ name: String }, { timestamps: true });
const User = mongoose.model('User', userSchema);

const obj = { name: 'John' };
User.applyTimestamps(obj);
obj.createdAt; // 2024-06-01T18:00:00.000Z
obj.updatedAt; // 2024-06-01T18:00:00.000Z

Apply this model's virtuals to a given POJO. Virtuals execute with the POJO as the context this.

Example:

const userSchema = new Schema({ name: String });
userSchema.virtual('upper').get(function() { return this.name.toUpperCase(); });
const User = mongoose.model('User', userSchema);

const obj = { name: 'John' };
User.applyVirtuals(obj);
obj.name; // 'John'
obj.upper; // 'JOHN', Mongoose applied the return value of the virtual to the given object

Takes an array of documents, gets the changes and inserts/updates documents in the database according to whether or not the document is new, or whether it has changes or not.

bulkSave uses bulkWrite under the hood, so it's mostly useful when dealing with many documents (10K+)

bulkSave() throws errors under the following conditions:

• one of the provided documents fails validation. In this case, bulkSave() does not send a bulkWrite(), and throws the first validation error.
• bulkWrite() fails (for example, due to being unable to connect to MongoDB or due to duplicate key error)
• bulkWrite() did not insert or update any documents. In this case, bulkSave() will throw a DocumentNotFound error.

Note that bulkSave() will not throw an error if only some of the save() calls succeeded.

Sends multiple insertOne, updateOne, updateMany, replaceOne, deleteOne, and/or deleteMany operations to the MongoDB server in one command. This is faster than sending multiple independent operations (e.g. if you use create()) because with bulkWrite() there is only one round trip to MongoDB.

Mongoose will perform casting on all operations you provide. The only exception is setting the update operator for updateOne or updateMany to a pipeline: Mongoose does not cast update pipelines.

This function does not trigger any middleware, neither save(), nor update(). If you need to trigger save() middleware for every document use create() instead.

Example:

Character.bulkWrite([
  {
    insertOne: {
      document: {
        name: 'Eddard Stark',
        title: 'Warden of the North'
      }
    }
  },
  {
    updateOne: {
      filter: { name: 'Eddard Stark' },
      // If you were using the MongoDB driver directly, you'd need to do
      // `update: { $set: { title: ... } }` but mongoose adds $set for
      // you.
      update: { title: 'Hand of the King' }
    }
  },
  {
    deleteOne: {
      filter: { name: 'Eddard Stark' }
    }
  }
]).then(res => {
 // Prints "1 1 1"
 console.log(res.insertedCount, res.modifiedCount, res.deletedCount);
});

// Mongoose does **not** cast update pipelines, so no casting for the `update` option below.
// Mongoose does still cast `filter`
await Character.bulkWrite([{
  updateOne: {
    filter: { name: 'Annika Hansen' },
    update: [{ $set: { name: 7 } }] // Array means update pipeline, so Mongoose skips casting
  }
}]);

The supported operations are:

• insertOne
• updateOne
• updateMany
• deleteOne
• deleteMany
• replaceOne

Cast the given POJO to the model's schema

Example:

const Test = mongoose.model('Test', Schema({ num: Number }));

const obj = Test.castObject({ num: '42' });
obj.num; // 42 as a number

Test.castObject({ num: 'not a number' }); // Throws a ValidationError

Deletes all indexes that aren't defined in this model's schema. Used by syncIndexes().

The returned promise resolves to a list of the dropped indexes' names as an array

If auto encryption is enabled, returns a ClientEncryption instance that is configured with the same settings that Mongoose's underlying MongoClient is using. If the client has not yet been configured, returns null.

Counts number of documents matching filter in a database collection.

Example:

const count = await Adventure.countDocuments({ type: 'jungle' });
console.log('there are %d jungle adventures', count);

If you want to count all documents in a large collection, use the estimatedDocumentCount() function instead. If you call countDocuments({}), MongoDB will always execute a full collection scan and not use any indexes.

The countDocuments() function is similar to count(), but there are a few operators that countDocuments() does not support. Below are the operators that count() supports but countDocuments() does not, and the suggested replacement:

• $where: $expr
• $near: $geoWithin with $center
• $nearSphere: $geoWithin with $centerSphere

Shortcut for saving one or more documents to the database. MyModel.create(docs) does new MyModel(doc).save() for every doc in docs.

This function triggers the following middleware.

• save()

Example:

// Insert one new `Character` document
await Character.create({ name: 'Jean-Luc Picard' });

// Insert multiple new `Character` documents
await Character.create([{ name: 'Will Riker' }, { name: 'Geordi LaForge' }]);

// Create a new character within a transaction. Note that you **must**
// pass an array as the first parameter to `create()` if you want to
// specify options.
await Character.create([{ name: 'Jean-Luc Picard' }], { session });

Create the collection for this model. By default, if no indexes are specified, mongoose will not create the collection for the model until any documents are created. Use this method to create the collection explicitly.

Note 1: You may need to call this before starting a transaction See https://www.mongodb.com/docs/manual/core/transactions/#transactions-and-operations

Note 2: You don't have to call this if your schema contains index or unique field. In that case, just use Model.init()

Example:

const userSchema = new Schema({ name: String })
const User = mongoose.model('User', userSchema);

User.createCollection().then(function(collection) {
  console.log('Collection is created!');
});

Similar to ensureIndexes(), except for it uses the createIndex function.

Create an Atlas search index. This function only works when connected to MongoDB Atlas.

Example:

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.createSearchIndex({ name: 'test', definition: { mappings: { dynamic: true } } });

Creates all Atlas search indexes defined in this model's schema. This function only works when connected to MongoDB Atlas.

Example:

const schema = new Schema({
  name: String,
  description: String
});
schema.searchIndex({ name: 'test', definition: { mappings: { dynamic: true } } });
const Product = mongoose.model('Product', schema);

// Creates the search index defined in the schema
await Product.createSearchIndexes();

Connection instance the model uses.

Deletes all of the documents that match conditions from the collection. It returns an object with the property deletedCount containing the number of documents deleted.

Example:

await Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }); // returns {deletedCount: x} where x is the number of documents deleted.

Note:

This function triggers deleteMany query hooks. Read the middleware docs to learn more.

Deletes the first document that matches conditions from the collection. It returns an object with the property deletedCount indicating how many documents were deleted.

Example:

await Character.deleteOne({ name: 'Eddard Stark' }); // returns {deletedCount: 1}

Note:

This function triggers deleteOne query hooks. Read the middleware docs to learn more.

Does a dry-run of Model.syncIndexes(), returning the indexes that syncIndexes() would drop and create if you were to run syncIndexes().

Example:

const { toDrop, toCreate } = await Model.diffIndexes();
toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
toCreate; // Array of index specs containing the keys of indexes that `syncIndexes()` will create

Adds a discriminator type.

Example:

function BaseSchema() {
  Schema.apply(this, arguments);

  this.add({
    name: String,
    createdAt: Date
  });
}
util.inherits(BaseSchema, Schema);

const PersonSchema = new BaseSchema();
const BossSchema = new BaseSchema({ department: String });

const Person = mongoose.model('Person', PersonSchema);
const Boss = Person.discriminator('Boss', BossSchema);
new Boss().__t; // "Boss". `__t` is the default `discriminatorKey`

const employeeSchema = new Schema({ boss: ObjectId });
const Employee = Person.discriminator('Employee', employeeSchema, 'staff');
new Employee().__t; // "staff" because of 3rd argument above

Creates a Query for a distinct operation.

Example:

const query = Link.distinct('url');
query.exec();

Delete an existing Atlas search index by name. This function only works when connected to MongoDB Atlas.

Example:

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.dropSearchIndex('test');

Sends createIndex commands to mongo for each index declared in the schema. The createIndex commands are sent in series.

Example:

await Event.ensureIndexes();

After completion, an index event is emitted on this Model passing an error if one occurred.

Example:

const eventSchema = new Schema({ thing: { type: 'string', unique: true } })
const Event = mongoose.model('Event', eventSchema);

Event.on('index', function (err) {
  if (err) console.error(err); // error occurred during index creation
});

NOTE: It is not recommended that you run this in production. Index creation may impact database performance depending on your load. Use with caution.

Estimates the number of documents in the MongoDB collection. Faster than using countDocuments() for large collections because estimatedDocumentCount() uses collection metadata rather than scanning the entire collection.

Example:

const numAdventures = await Adventure.estimatedDocumentCount();

Event emitter that reports any errors that occurred. Useful for global error handling.

Example:

MyModel.events.on('error', err => console.log(err.message));

// Prints a 'CastError' because of the above handler
await MyModel.findOne({ _id: 'Not a valid ObjectId' }).catch(noop);

Returns a document with _id only if at least one document exists in the database that matches the given filter, and null otherwise.

Under the hood, MyModel.exists({ answer: 42 }) is equivalent to MyModel.findOne({ answer: 42 }).select({ _id: 1 }).lean()

Example:

await Character.deleteMany({});
await Character.create({ name: 'Jean-Luc Picard' });

await Character.exists({ name: /picard/i }); // { _id: ... }
await Character.exists({ name: /riker/i }); // null

This function triggers the following middleware.

• findOne()

Finds documents.

Mongoose casts the filter to match the model's schema before the command is sent. See our query casting tutorial for more information on how Mongoose casts filter.

Example:

// find all documents
await MyModel.find({});

// find all documents named john and at least 18
await MyModel.find({ name: 'john', age: { $gte: 18 } }).exec();

// executes, name LIKE john and only selecting the "name" and "friends" fields
await MyModel.find({ name: /john/i }, 'name friends').exec();

// passing options
await MyModel.find({ name: /john/i }, null, { skip: 10 }).exec();

Finds a single document by its _id field. findById(id) is equivalent to findOne({ _id: id }).

The id is cast based on the Schema before sending the command.

This function triggers the following middleware.

• findOne()

Example:

// Find the adventure with the given `id`, or `null` if not found
await Adventure.findById(id).exec();

// select only the adventures name and length
await Adventure.findById(id, 'name length').exec();

Issue a MongoDB findOneAndDelete() command by a document's _id field. In other words, findByIdAndDelete(id) is a shorthand for findOneAndDelete({ _id: id }).

This function triggers the following middleware.

• findOneAndDelete()

Issues a mongodb findOneAndUpdate command by a document's _id field. findByIdAndUpdate(id, ...) is equivalent to findOneAndUpdate({ _id: id }, ...).

Finds a matching document, updates it according to the update arg, passing any options, and returns the found document (if any).

This function triggers the following middleware.

• findOneAndUpdate()

Example:

A.findByIdAndUpdate(id, update, options)  // returns Query
A.findByIdAndUpdate(id, update)           // returns Query
A.findByIdAndUpdate()                     // returns Query

Note:

All top level update keys which are not atomic operation names are treated as set operations:

Example:

Model.findByIdAndUpdate(id, { name: 'jason bourne' }, options)

// is sent as
Model.findByIdAndUpdate(id, { $set: { name: 'jason bourne' }}, options)

Note:

findOneAndX and findByIdAndX functions support limited validation. You can enable validation by setting the runValidators option.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

const doc = await Model.findById(id)
doc.name = 'jason bourne';
await doc.save();

Finds one document.

The conditions are cast to their respective SchemaTypes before the command is sent.

Note: conditions is optional, and if conditions is null or undefined, mongoose will send an empty findOne command to MongoDB, which will return an arbitrary document. If you're querying by _id, use findById() instead.

Example:

// Find one adventure whose `country` is 'Croatia', otherwise `null`
await Adventure.findOne({ country: 'Croatia' }).exec();

// Model.findOne() no longer accepts a callback

// Select only the adventures name and length
await Adventure.findOne({ country: 'Croatia' }, 'name length').exec();

Issue a MongoDB findOneAndDelete() command.

Finds a matching document, removes it, and returns the found document (if any).

This function triggers the following middleware.

• findOneAndDelete()

Example:

A.findOneAndDelete(conditions, options)  // return Query
A.findOneAndDelete(conditions) // returns Query
A.findOneAndDelete()           // returns Query

findOneAndX and findByIdAndX functions support limited validation. You can enable validation by setting the runValidators option.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

const doc = await Model.findById(id)
doc.name = 'jason bourne';
await doc.save();

Issue a MongoDB findOneAndReplace() command.

Finds a matching document, replaces it with the provided doc, and returns the document.

This function triggers the following query middleware.

• findOneAndReplace()

Example:

A.findOneAndReplace(filter, replacement, options)  // return Query
A.findOneAndReplace(filter, replacement) // returns Query
A.findOneAndReplace()                    // returns Query

Issues a mongodb findOneAndUpdate command.

Finds a matching document, updates it according to the update arg, passing any options. A Query object is returned.

Example:

A.findOneAndUpdate(filter, update, options);  // returns Query
A.findOneAndUpdate(filter, update);           // returns Query
A.findOneAndUpdate(filter);                   // returns Query
A.findOneAndUpdate();                         // returns Query

// Other supported syntaxes
// Note that calling `Query#findOneAndUpdate()` with 1 arg will treat the arg as `update`, NOT `filter`
A.find(filter).findOneAndUpdate(update);

Note:

All top level update keys which are not atomic operation names are treated as set operations:

Example:

const query = { name: 'borne' };
Model.findOneAndUpdate(query, { name: 'jason bourne' }, options);

// is sent as
Model.findOneAndUpdate(query, { $set: { name: 'jason bourne' }}, options);

Note:

findOneAndX and findByIdAndX functions support limited validation that you can enable by setting the runValidators option.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

const doc = await Model.findById(id);
doc.name = 'jason bourne';
await doc.save();

Shortcut for creating a new Document from existing raw data, pre-saved in the DB. The document returned has no paths marked as modified initially.

Example:

// hydrate previous data into a Mongoose document
const mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });

This function is responsible for initializing the underlying connection in MongoDB based on schema options. This function performs the following operations:

• createCollection() unless autoCreate option is turned off
• ensureIndexes() unless autoIndex option is turned off
• createSearchIndex() on all schema search indexes if autoSearchIndex is enabled.

Mongoose calls this function automatically when a model is a created using mongoose.model() or connection.model(), so you don't need to call init() to trigger index builds.

However, you may need to call init() to get back a promise that will resolve when your indexes are finished. Calling await Model.init() is helpful if you need to wait for indexes to build before continuing. For example, if you want to wait for unique indexes to build before continuing with a test case.

Example:

const eventSchema = new Schema({ thing: { type: 'string', unique: true } })
// This calls `Event.init()` implicitly, so you don't need to call
// `Event.init()` on your own.
const Event = mongoose.model('Event', eventSchema);

await Event.init();
console.log('Indexes are done building!');

Shortcut for validating an array of documents and inserting them into MongoDB if they're all valid. This function is faster than .create() because it only sends one operation to the server, rather than one for each document.

Mongoose always validates each document before sending insertMany to MongoDB. So if one document has a validation error, no documents will be saved, unless you set the ordered option to false.

This function does not trigger save middleware.

This function triggers the following middleware.

• insertMany()

Example:

const docs = await Movies.insertMany([
  { name: 'Star Wars' },
  { name: 'The Empire Strikes Back' }
]);
docs[0].name; // 'Star Wars'

// Return raw result from MongoDB
const result = await Movies.insertMany([
  { name: 'Star Wars' },
  { name: 'The Empire Strikes Back' }
], { rawResult: true });

Shortcut for saving one document to the database. MyModel.insertOne(obj, options) is almost equivalent to new MyModel(obj).save(options). The difference is that insertOne() checks if obj is already a document, and checks for discriminators.

This function triggers the following middleware.

• save()

Example:

// Insert one new `Character` document
const character = await Character.insertOne({ name: 'Jean-Luc Picard' });
character.name; // 'Jean-Luc Picard'

// Create a new character within a transaction.
await Character.insertOne({ name: 'Jean-Luc Picard' }, { session });

Helper for console.log. Given a model named 'MyModel', returns the string 'Model { MyModel }'.

Example:

const MyModel = mongoose.model('Test', Schema({ name: String }));
MyModel.inspect(); // 'Model { Test }'
console.log(MyModel); // Prints 'Model { Test }'

Lists the indexes currently defined in MongoDB. This may or may not be the same as the indexes defined in your schema depending on whether you use the autoIndex option and if you build indexes manually.

List all Atlas search indexes on this model's collection. This function only works when connected to MongoDB Atlas.

Example:

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);

await Customer.createSearchIndex({ name: 'test', definition: { mappings: { dynamic: true } } });
const res = await Customer.listSearchIndexes(); // Includes `[{ name: 'test' }]`

Return the MongoDB namespace for this model as a string. The namespace is the database name, followed by '.', followed by the collection name.

Example:

const conn = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
const TestModel = conn.model('Test', mongoose.Schema({ name: String }));

TestModel.namespace(); // 'mydb.tests'

Populates document references.

Changed in Mongoose 6: the model you call populate() on should be the "local field" model, not the "foreign field" model.

Available top-level options:

• path: space delimited path(s) to populate
• select: optional fields to select
• match: optional query conditions to match
• model: optional name of the model to use for population
• options: optional query options like sort, limit, etc
• justOne: optional boolean, if true Mongoose will always set path to a document, or null if no document was found. If false, Mongoose will always set path to an array, which will be empty if no documents are found. Inferred from schema by default.
• strictPopulate: optional boolean, set to false to allow populating paths that aren't in the schema.
• forceRepopulate: optional boolean, defaults to true. Set to false to prevent Mongoose from repopulating paths that are already populated

Example:

const Dog = mongoose.model('Dog', new Schema({ name: String, breed: String }));
const Person = mongoose.model('Person', new Schema({
  name: String,
  pet: { type: mongoose.ObjectId, ref: 'Dog' }
}));

const pets = await Pet.create([
  { name: 'Daisy', breed: 'Beagle' },
  { name: 'Einstein', breed: 'Catalan Sheepdog' }
]);

// populate many plain objects
const users = [
  { name: 'John Wick', dog: pets[0]._id },
  { name: 'Doc Brown', dog: pets[1]._id }
];
await User.populate(users, { path: 'dog', select: 'name' });
users[0].dog.name; // 'Daisy'
users[0].dog.breed; // undefined because of `select`

Returns the model instance used to create this document if no name specified. If name specified, returns the model with the given name.

Example:

const doc = new Tank({});
doc.$model() === Tank; // true
await doc.$model('User').findById(id);

Additional properties to attach to the query when calling save() and isNew is false.

Base Mongoose instance the model uses.

If this is a discriminator model, baseModelName is the name of the base model.

The collection instance this model uses. A Mongoose collection is a thin wrapper around a [MongoDB Node.js driver collection](MongoDB Node.js driver collection). Using Model.collection means you bypass Mongoose middleware, validation, and casting.

This property is read-only. Modifying this property is a no-op.

Collection the model uses.

Connection the model uses.

Delete this document from the db. Returns a Query instance containing a deleteOne operation by this document's _id.

Example:

await product.deleteOne();
await Product.findById(product._id); // null

Since deleteOne() returns a Query, the deleteOne() will not execute unless you use either await, .then(), .catch(), or .exec()

Example:

product.deleteOne(); // Doesn't do anything
product.deleteOne().exec(); // Deletes the document, returns a promise

Registered discriminators for this model.

Signal that we desire an increment of this documents version.

Example:

const doc = await Model.findById(id);
doc.increment();
await doc.save();

Returns the model instance used to create this document if no name specified. If name specified, returns the model with the given name.

Example:

const doc = new Tank({});
doc.$model() === Tank; // true
await doc.$model('User').findById(id);

The name of the model

Saves this document by inserting a new document into the database if document.isNew is true, or sends an updateOne operation with just the modified paths if isNew is false.

Example:

product.sold = Date.now();
product = await product.save();

If save is successful, the returned promise will fulfill with the document saved.

Example:

const newProduct = await product.save();
newProduct === product; // true

Apply changes made to this model's schema after this model was compiled. By default, adding virtuals and other properties to a schema after the model is compiled does nothing. Call this function to apply virtuals and properties that were added later.

Example:

const schema = new mongoose.Schema({ field: String });
const TestModel = mongoose.model('Test', schema);
TestModel.schema.virtual('myVirtual').get(function() {
  return this.field + ' from myVirtual';
});
const doc = new TestModel({ field: 'Hello' });
doc.myVirtual; // undefined

TestModel.recompileSchema();
doc.myVirtual; // 'Hello from myVirtual'

Replace the existing document with the given document (no atomic operators like $set).

Example:

const res = await Person.replaceOne({ _id: 24601 }, { name: 'Jean Valjean' });
res.matchedCount; // Number of documents matched
res.modifiedCount; // Number of documents modified
res.acknowledged; // Boolean indicating the MongoDB server received the operation.
res.upsertedId; // null or an id containing a document that had to be upserted.
res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.

This function triggers the following middleware.

• replaceOne()

Schema the model uses.

Requires MongoDB >= 3.6.0. Starts a MongoDB session for benefits like causal consistency, retryable writes, and transactions.

Calling MyModel.startSession() is equivalent to calling MyModel.db.startSession().

This function does not trigger any middleware.

Example:

const session = await Person.startSession();
let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
await doc.deleteOne();
// `doc` will always be null, even if reading from a replica set
// secondary. Without causal consistency, it is possible to
// get a doc back from the below query if the query reads from a
// secondary that is experiencing replication lag.
doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });

Makes the indexes in MongoDB match the indexes defined in this model's schema. This function will drop any indexes that are not defined in the model's schema except the _id index, and build any indexes that are in your schema but not in MongoDB.

See the introductory blog post for more information.

Example:

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.collection.createIndex({ age: 1 }); // Index is not in schema
// Will drop the 'age' index and create an index on `name`
await Customer.syncIndexes();

You should be careful about running syncIndexes() on production applications under heavy load, because index builds are expensive operations, and unexpected index drops can lead to degraded performance. Before running syncIndexes(), you can use the diffIndexes() function to check what indexes syncIndexes() will drop and create.

Example:

const { toDrop, toCreate } = await Model.diffIndexes();
toDrop; // Array of strings containing names of indexes that `syncIndexes()` will drop
toCreate; // Array of strings containing names of indexes that `syncIndexes()` will create

Translate any aliases fields/conditions so the final query or document object is pure

Example:

await Character.find(Character.translateAliases({
   '名': 'Eddard Stark' // Alias for 'name'
});

By default, translateAliases() overwrites raw fields with aliased fields. So if n is an alias for name, { n: 'alias', name: 'raw' } will resolve to { name: 'alias' }. However, you can set the errorOnDuplicates option to throw an error if there are potentially conflicting paths. The translateAliases option for queries uses errorOnDuplicates.

Note:

Only translate arguments of object type anything else is returned raw

Same as updateOne(), except MongoDB will update all documents that match filter (as opposed to just the first one) regardless of the value of the multi option.

Note updateMany will not fire update middleware. Use pre('updateMany') and post('updateMany') instead.

Example:

const res = await Person.updateMany({ name: /Stark$/ }, { isDeleted: true });
res.matchedCount; // Number of documents matched
res.modifiedCount; // Number of documents modified
res.acknowledged; // Boolean indicating the MongoDB server received the operation. This may be false if Mongoose did not send an update to the server because the update was empty.
res.upsertedId; // null or an id containing a document that had to be upserted.
res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.

// Other supported syntaxes
await Person.find({ name: /Stark$/ }).updateMany({ isDeleted: true }); // Using chaining syntax
await Person.find().updateMany({ isDeleted: true }); // Set `isDeleted` on _all_ Person documents

This function triggers the following middleware.

• updateMany()

Update only the first document that matches filter.

• Use replaceOne() if you want to overwrite an entire document rather than using atomic operators like $set.

Example:

const res = await Person.updateOne({ name: 'Jean-Luc Picard' }, { ship: 'USS Enterprise' });
res.matchedCount; // Number of documents matched
res.modifiedCount; // Number of documents modified
res.acknowledged; // Boolean indicating the MongoDB server received the operation. This may be false if Mongoose did not send an update to the server because the update was empty.
res.upsertedId; // null or an id containing a document that had to be upserted.
res.upsertedCount; // Number indicating how many documents had to be upserted. Will either be 0 or 1.

// Other supported syntaxes
await Person.findOne({ name: 'Jean-Luc Picard' }).updateOne({ ship: 'USS Enterprise' }); // Using chaining syntax
await Person.updateOne({ ship: 'USS Enterprise' }); // Updates first doc's `ship` property

This function triggers the following middleware.

• updateOne()

Update an existing Atlas search index. This function only works when connected to MongoDB Atlas.

Example:

const schema = new Schema({ name: { type: String, unique: true } });
const Customer = mongoose.model('Customer', schema);
await Customer.updateSearchIndex('test', { mappings: { dynamic: true } });

Changes the Connection instance this model uses to make requests to MongoDB. This function is most useful for changing the Connection that a Model defined using mongoose.model() uses after initialization.

Example:

await mongoose.connect('mongodb://127.0.0.1:27017/db1');
const UserModel = mongoose.model('User', mongoose.Schema({ name: String }));
UserModel.connection === mongoose.connection; // true

const conn2 = await mongoose.createConnection('mongodb://127.0.0.1:27017/db2').asPromise();
UserModel.useConnection(conn2); // `UserModel` now stores documents in `db2`, not `db1`

UserModel.connection === mongoose.connection; // false
UserModel.connection === conn2; // true

conn2.model('User') === UserModel; // true
mongoose.model('User'); // Throws 'MissingSchemaError'

Note: useConnection() does not apply any connection-level plugins from the new connection. If you use useConnection() to switch a model's connection, the model will still have the old connection's plugins.

Casts and validates the given object against this model's schema, passing the given context to custom validators.

Example:

const Model = mongoose.model('Test', Schema({
  name: { type: String, required: true },
  age: { type: Number, required: true }
});

try {
  await Model.validate({ name: null }, ['name'])
} catch (err) {
  err instanceof mongoose.Error.ValidationError; // true
  Object.keys(err.errors); // ['name']
}

Requires a replica set running MongoDB >= 3.6.0. Watches the underlying collection for changes using MongoDB change streams.

This function does not trigger any middleware. In particular, it does not trigger aggregate middleware.

The ChangeStream object is an event emitter that emits the following events:

• 'change': A change occurred, see below example
• 'error': An unrecoverable error occurred. In particular, change streams currently error out if they lose connection to the replica set primary. Follow this GitHub issue for updates.
• 'end': Emitted if the underlying stream is closed
• 'close': Emitted if the underlying stream is closed

Example:

const doc = await Person.create({ name: 'Ned Stark' });
const changeStream = Person.watch().on('change', change => console.log(change));
// Will print from the above `console.log()`:
// { _id: { _data: ... },
//   operationType: 'delete',
//   ns: { db: 'mydb', coll: 'Person' },
//   documentKey: { _id: 5a51b125c5500f5aa094c7bd } }
await doc.deleteOne();

Creates a Query, applies the passed conditions, and returns the Query.

For example, instead of writing:

User.find({ age: { $gte: 21, $lte: 65 } });

we can instead write:

User.where('age').gte(21).lte(65).exec();

Since the Query class also supports where you can continue chaining

User
.where('age').gte(21).lte(65)
.where('name', /^b/i)
... etc