API Docs

• Mongoose()
• Mongoose.prototype.CastError()
• Mongoose.prototype.Connection()
• Mongoose.prototype.Decimal128
• Mongoose.prototype.DocumentProvider()
• Mongoose.prototype.Mixed
• Mongoose.prototype.Mongoose()
• Mongoose.prototype.ObjectId
• Mongoose.prototype.PromiseProvider()
• Mongoose.prototype.STATES
• Mongoose.prototype.SchemaType()
• Mongoose.prototype.SchemaTypes
• Mongoose.prototype.VirtualType()
• Mongoose.prototype.connection
• Mongoose.prototype.createConnection()
• Mongoose.prototype.disconnect()
• Mongoose.prototype.get()
• Mongoose.prototype.model()
• Mongoose.prototype.mongo
• Mongoose.prototype.now()
• Mongoose.prototype.pluralize()
• Mongoose.prototype.startSession()

Schema

• Schema.Types
• Schema.prototype.add()
• Schema.prototype.clone()
• Schema.prototype.get()
• Schema.prototype.indexes()
• Schema.prototype.method()
• Schema.prototype.path()
• Schema.prototype.paths
• Schema.prototype.plugin()
• Schema.prototype.pre()
• Schema.prototype.remove()
• Schema.prototype.set()
• Schema.prototype.virtual()
• Schema.reserved

• Connection()
• Connection.prototype.close()
• Connection.prototype.collections
• Connection.prototype.createCollection()
• Connection.prototype.deleteModel()
• Connection.prototype.dropDatabase()
• Connection.prototype.getClient()
• Connection.prototype.id
• Connection.prototype.modelNames()
• Connection.prototype.name
• Connection.prototype.pass
• Connection.prototype.plugins
• Connection.prototype.readyState
• Connection.prototype.setClient()
• Connection.prototype.transaction()
• Connection.prototype.user

Document

• Document.prototype.$ignore()
• Document.prototype.$isDeleted()
• Document.prototype.$locals
• Document.prototype.$op
• Document.prototype.$session()
• Document.prototype.$where
• Document.prototype.directModifiedPaths()
• Document.prototype.errors
• Document.prototype.get()
• Document.prototype.id
• Document.prototype.inspect()
• Document.prototype.isDirectModified()
• Document.prototype.isInit()
• Document.prototype.isNew
• Document.prototype.markModified()
• Document.prototype.overwrite()
• Document.prototype.populate()
• Document.prototype.replaceOne()
• Document.prototype.schema
• Document.prototype.toJSON()
• Document.prototype.toString()
• Document.prototype.unmarkModified()
• Document.prototype.updateOne()
• Document.prototype.validateSync()

• Model()
• Model.buildBulkWriteOperations()
• Model.bulkWrite()
• Model.count()
• Model.create()
• Model.createIndexes()
• Model.deleteOne()
• Model.discriminator()
• Model.ensureIndexes()
• Model.events
• Model.find()
• Model.findByIdAndDelete()
• Model.findByIdAndUpdate()
• Model.findOneAndDelete()
• Model.findOneAndReplace()
• Model.geoSearch()
• Model.init()
• Model.inspect()
• Model.mapReduce()
• Model.prototype.$where
• Model.prototype.base
• Model.prototype.collection
• Model.prototype.delete
• Model.prototype.discriminators
• Model.prototype.modelName
• Model.prototype.save()
• Model.remove()
• Model.startSession()
• Model.translateAliases()
• Model.updateMany()
• Model.validate()
• Model.where()

Query

• Query.prototype.$where()
• Query.prototype.all()
• Query.prototype.and()
• Query.prototype.box()
• Query.prototype.catch()
• Query.prototype.centerSphere()
• Query.prototype.collation()
• Query.prototype.count()
• Query.prototype.cursor()
• Query.prototype.deleteOne()
• Query.prototype.elemMatch()
• Query.prototype.error()
• Query.prototype.exec()
• Query.prototype.explain()
• Query.prototype.findOne()
• Query.prototype.findOneAndRemove()
• Query.prototype.findOneAndUpdate()
• Query.prototype.get()
• Query.prototype.getOptions()
• Query.prototype.getQuery()
• Query.prototype.gt()
• Query.prototype.hint()
• Query.prototype.intersects()
• Query.prototype.lean()
• Query.prototype.lt()
• Query.prototype.map()
• Query.prototype.maxScan()
• Query.prototype.maxscan()
• Query.prototype.mod()
• Query.prototype.mongooseOptions()
• Query.prototype.near()
• Query.prototype.nin()
• Query.prototype.or()
• Query.prototype.polygon()
• Query.prototype.post()
• Query.prototype.projection()
• Query.prototype.readConcern()
• Query.prototype.remove()
• Query.prototype.select()
• Query.prototype.selectedExclusively()
• Query.prototype.session()
• Query.prototype.setOptions()
• Query.prototype.setUpdate()
• Query.prototype.skip()
• Query.prototype.slice()
• Query.prototype.sort()
• Query.prototype.then()
• Query.prototype.update()
• Query.prototype.updateOne()
• Query.prototype.w()
• Query.prototype.within()
• Query.prototype.wtimeout()

• Query.prototype.Symbol.asyncIterator()
• QueryCursor.prototype.addCursorFlag()
• QueryCursor.prototype.eachAsync()
• QueryCursor.prototype.next()

Aggregate

• Aggregate.prototype.Symbol.asyncIterator()
• Aggregate.prototype.addFields()
• Aggregate.prototype.append()
• Aggregate.prototype.collation()
• Aggregate.prototype.cursor()
• Aggregate.prototype.explain()
• Aggregate.prototype.graphLookup()
• Aggregate.prototype.hint()
• Aggregate.prototype.lookup()
• Aggregate.prototype.model()
• Aggregate.prototype.option()
• Aggregate.prototype.pipeline()
• Aggregate.prototype.read()
• Aggregate.prototype.redact()
• Aggregate.prototype.sample()
• Aggregate.prototype.session()
• Aggregate.prototype.sort()
• Aggregate.prototype.then()

AggregationCursor

• AggregationCursor.prototype.Symbol.asyncIterator()
• AggregationCursor.prototype.close()
• AggregationCursor.prototype.map()

Schematype

• SchemaType.prototype.cast()
• SchemaType.prototype.get()
• SchemaType.prototype.index()
• SchemaType.prototype.required()
• SchemaType.prototype.set()
• SchemaType.prototype.text()
• SchemaType.prototype.unique()
• Schematype.cast()
• Schematype.checkRequired()
• Schematype.set()

• VirtualType()
• VirtualType.prototype.applySetters()
• VirtualType.prototype.set()

• Error()
• Error.DivergentArrayError
• Error.MissingSchemaError
• Error.ParallelSaveError
• Error.ValidationError
• Error.VersionError
• Error.prototype.name

• MongooseArray.prototype.$pop()
• MongooseArray.prototype.addToSet()
• MongooseArray.prototype.indexOf()
• MongooseArray.prototype.nonAtomicPush()
• MongooseArray.prototype.pull()
• MongooseArray.prototype.remove()
• MongooseArray.prototype.shift()
• MongooseArray.prototype.splice()
• MongooseArray.prototype.unshift()

• SchemaArray()
• SchemaArray.options
• SchemaArray.prototype.enum()
• SchemaArray.set()

• DocumentArrayPath()
• DocumentArrayPath.options
• DocumentArrayPath.schemaName

• SingleNestedPath()
• SingleNestedPath.prototype.discriminator()

• Mongoose.prototype.Aggregate()
• Mongoose.prototype.Collection()
• Mongoose.prototype.Date
• Mongoose.prototype.Document()
• Mongoose.prototype.Error()
• Mongoose.prototype.Model()
• Mongoose.prototype.Number
• Mongoose.prototype.Promise
• Mongoose.prototype.Query()
• Mongoose.prototype.Schema()
• Mongoose.prototype.SchemaTypeOptions()
• Mongoose.prototype.Types
• Mongoose.prototype.connect()
• Mongoose.prototype.connections
• Mongoose.prototype.deleteModel()
• Mongoose.prototype.driver
• Mongoose.prototype.isValidObjectId()
• Mongoose.prototype.modelNames()
• Mongoose.prototype.mquery
• Mongoose.prototype.plugin()
• Mongoose.prototype.set()
• Mongoose.prototype.version

Parameters

• options «Object» see docs

Mongoose constructor.

The exports object of the mongoose module is an instance of this class. Most apps will only use this one instance.

Example:

The Mongoose Aggregate constructor

Parameters

• type «String» The name of the type

• value «Any» The value that failed to cast

• path «String» The path a.b.c in the doc where this cast error occurred

• [reason] «Error» The original error that was thrown

The Mongoose CastError constructor

Mongoose.prototype.Collection()

The Mongoose Collection constructor

Mongoose.prototype.Connection()

The Mongoose constructor

Type:

• «property»

The Mongoose Date .

Example:

const schema = new Schema({ test: Date });
schema.path('test') instanceof mongoose.Date; // true

Mongoose.prototype.Decimal128

Type:

• «property»

The Mongoose Decimal128 SchemaType. Used for declaring paths in your schema that should be . Do not use this to create a new Decimal128 instance, use mongoose.Types.Decimal128 instead.

Example:

const vehicleSchema = new Schema({ fuelLevel: mongoose.Decimal128 });

Mongoose.prototype.Document()

The Mongoose constructor.

The Mongoose DocumentProvider constructor. Mongoose users should not have to use this directly

The MongooseError constructor.

Mongoose.prototype.Mixed

Type:

• «property»

The Mongoose Mixed SchemaType. Used for declaring paths in your schema that Mongoose’s change tracking, casting, and validation should ignore.

Example:

const schema = new Schema({ arbitrary: mongoose.Mixed });

The Mongoose Model constructor.

Mongoose.prototype.Mongoose()

The Mongoose constructor

The exports of the mongoose module is an instance of this class.

Example:

const mongoose = require('mongoose');
const mongoose2 = new mongoose.Mongoose();

Type:

• «property»

The Mongoose Number . Used for declaring paths in your schema that Mongoose should cast to numbers.

Example:

const schema = new Schema({ num: mongoose.Number });
// Equivalent to:
const schema = new Schema({ num: 'number' });

Mongoose.prototype.ObjectId

Type:

• «property»

The Mongoose ObjectId SchemaType. Used for declaring paths in your schema that should be . Do not use this to create a new ObjectId instance, use mongoose.Types.ObjectId instead.

Example:

const childSchema = new Schema({ parentId: mongoose.ObjectId });

Mongoose.prototype.Promise

Type:

• «property»

The Mongoose Promise constructor.

Mongoose.prototype.PromiseProvider()

Storage layer for mongoose promises

Mongoose.prototype.Query()

The Mongoose constructor.

Type:

• «property»

Expose connection states for user-land

Mongoose.prototype.Schema()

The Mongoose constructor

Example:

const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const CatSchema = new Schema(..);

Mongoose.prototype.SchemaType()

The Mongoose constructor

The constructor used for schematype options

Type:

• «property»

The various Mongoose SchemaTypes.

Note:

Alias of mongoose.Schema.Types for backwards compatibility.

Type:

• «property»

The various Mongoose Types.

Example:

const mongoose = require('mongoose');
const array = mongoose.Types.Array;

Types:

• Buffer
• DocumentArray
• ObjectId
• Subdocument

Using this exposed access to the ObjectId type, we can construct ids on demand.

const ObjectId = mongoose.Types.ObjectId;
const id1 = new ObjectId;

Mongoose.prototype.VirtualType()

The Mongoose constructor

Parameters

• uri(s) «String»

• [options] «Object» passed down to the , except for 4 mongoose-specific options explained below.

• [options.bufferCommands=true] «Boolean» Mongoose specific option. Set to false to disable buffering on all models associated with this connection.

• [options.bufferTimeoutMS=10000] «Number» Mongoose specific option. If bufferCommands is true, Mongoose will throw an error after bufferTimeoutMS if the operation is still buffered.

• [options.dbName] «String» The name of the database we want to use. If not provided, use database name from connection string.

• [options.user] «String» username for authentication, equivalent to options.auth.user. Maintained for backwards compatibility.

• [options.pass] «String» password for authentication, equivalent to options.auth.password. Maintained for backwards compatibility.

• [options.poolSize=5] «Number» The maximum number of sockets the MongoDB driver will keep open for this connection. By default, poolSize is 5. Keep in mind that, as of MongoDB 3.4, MongoDB only allows one operation per socket at a time, so you may want to increase this if you find you have a few slow queries that are blocking faster queries from proceeding. See .

• [options.useUnifiedTopology=false] «Boolean» False by default. Set to true to opt in to the MongoDB driver’s replica set and sharded cluster monitoring engine.

• [options.serverSelectionTimeoutMS] «Number» If useUnifiedTopology = true, the MongoDB driver will try to find a server to send any given operation to, and keep retrying for serverSelectionTimeoutMS milliseconds before erroring out. If not set, the MongoDB driver defaults to using 30000 (30 seconds).

• [options.heartbeatFrequencyMS] «Number» If useUnifiedTopology = true, the MongoDB driver sends a heartbeat every heartbeatFrequencyMS to check on the status of the connection. A heartbeat is subject to serverSelectionTimeoutMS, so the MongoDB driver will retry failed heartbeats for up to 30 seconds by default. Mongoose only emits a 'disconnected' event after a heartbeat has failed, so you may want to decrease this setting to reduce the time between when your server goes down and when Mongoose emits 'disconnected'. We recommend you do not set this setting below 1000, too many heartbeats can lead to performance degradation.

• [options.autoIndex=true] «Boolean» Mongoose-specific option. Set to false to disable automatic index creation for all models associated with this connection.

• [options.useNewUrlParser=false] «Boolean» False by default. Set to true to opt in to the MongoDB driver’s new URL parser logic.

• [options.useCreateIndex=true] «Boolean» Mongoose-specific option. If true, this connection will use createIndex() instead of ensureIndex() for automatic index builds via .

• [options.useFindAndModify=true] «Boolean» True by default. Set to false to make findOneAndUpdate() and findOneAndRemove() use native findOneAndUpdate() rather than findAndModify().

• [options.reconnectTries=30] «Number» If you’re connected to a single server or mongos proxy (as opposed to a replica set), the MongoDB driver will try to reconnect every reconnectInterval milliseconds for reconnectTries times, and give up afterward. When the driver gives up, the mongoose connection emits a reconnectFailed event. This option does nothing for replica set connections.

• [options.reconnectInterval=1000] «Number» See reconnectTries option above.

• [options.promiseLibrary] «Class» Sets the underlying driver’s promise library.

• [options.bufferMaxEntries] «Number» This option does nothing if useUnifiedTopology is set. The MongoDB driver also has its own buffering mechanism that kicks in when the driver is disconnected. Set this option to 0 and set bufferCommands to false on your schemas if you want your database operations to fail immediately when the driver is not connected, as opposed to waiting for reconnection.

• [options.connectTimeoutMS=30000] «Number» How long the MongoDB driver will wait before killing a socket due to inactivity during initial connection. Defaults to 30000. This option is passed transparently to .

• [options.socketTimeoutMS=30000] «Number» How long the MongoDB driver will wait before killing a socket due to inactivity after initial connection. A socket may be inactive because of either no activity or a long-running operation. This is set to 30000 by default, you should set this to 2-3x your longest running operation if you expect some of your database operations to run longer than 20 seconds. This option is passed to Node.js socket#setTimeout() function after the MongoDB driver successfully completes.

• [options.family=0] «Number» Passed transparently to function. May be either 0, 4, or 6. 4 means use IPv4 only, 6 means use IPv6 only, 0 means try both.

• [options.autoCreate=false] «Boolean» Set to true to make Mongoose automatically call createCollection() on every model created on this connection.

• [callback] «Function»

Returns:

• «Promise» resolves to this if connection succeeded

Opens the default mongoose connection.

Example:

mongoose.connect('mongodb://user:pass@localhost:port/database');
// replica sets
const uri = 'mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/mydatabase';
mongoose.connect(uri);
// with options
mongoose.connect(uri, options);
// optional callback that gets fired when initial connection completed
const uri = 'mongodb://nonexistent.domain:27000';
mongoose.connect(uri, function(error) {
  // if error is truthy, the initial connection failed.
})

Type:

• «Connection»

The Mongoose module’s default connection. Equivalent to mongoose.connections[0], see .

Example:

const mongoose = require('mongoose');
mongoose.connect(...);
mongoose.connection.on('error', cb);

This is the connection used by default for every model created using .

To create a new connection, use createConnection().

Mongoose.prototype.connections

Type:

• «Array»

An array containing all connections associated with this Mongoose instance. By default, there is 1 connection. Calling adds a connection to this array.

Example:

const mongoose = require('mongoose');
mongoose.connections.length; // 1, just the default connection
mongoose.connections[0] === mongoose.connection; // true
mongoose.createConnection('mongodb://localhost:27017/test');
mongoose.connections.length; // 2

Mongoose.prototype.createConnection()

Parameters

• [uri] «String» a mongodb:// URI

• [options] «Object» passed down to the MongoDB driver’s connect() function, except for 4 mongoose-specific options explained below.

• [options.bufferCommands=true] «Boolean» Mongoose specific option. Set to false to on all models associated with this connection.

• [options.dbName] «String» The name of the database you want to use. If not provided, Mongoose uses the database name from connection string.

• [options.user] «String» username for authentication, equivalent to options.auth.user. Maintained for backwards compatibility.

• [options.pass] «String» password for authentication, equivalent to options.auth.password. Maintained for backwards compatibility.

• [options.autoIndex=true] «Boolean» Mongoose-specific option. Set to false to disable automatic index creation for all models associated with this connection.

• [options.useNewUrlParser=false] «Boolean» False by default. Set to true to make all connections set the useNewUrlParser option by default.

• [options.useUnifiedTopology=false] «Boolean» False by default. Set to true to make all connections set the useUnifiedTopology option by default.

• [options.useCreateIndex=true] «Boolean» Mongoose-specific option. If true, this connection will use createIndex() instead of ensureIndex() for automatic index builds via .

• [options.reconnectTries=30] «Number» If you’re connected to a single server or mongos proxy (as opposed to a replica set), the MongoDB driver will try to reconnect every reconnectInterval milliseconds for reconnectTries times, and give up afterward. When the driver gives up, the mongoose connection emits a reconnectFailed event. This option does nothing for replica set connections.

• [options.reconnectInterval=1000] «Number» See reconnectTries option above.

• [options.promiseLibrary] «Class» Sets the underlying driver’s promise library.

• [options.poolSize=5] «Number» The maximum number of sockets the MongoDB driver will keep open for this connection. By default, poolSize is 5. Keep in mind that, as of MongoDB 3.4, MongoDB only allows one operation per socket at a time, so you may want to increase this if you find you have a few slow queries that are blocking faster queries from proceeding. See .

• [options.bufferMaxEntries] «Number» This option does nothing if useUnifiedTopology is set. The MongoDB driver also has its own buffering mechanism that kicks in when the driver is disconnected. Set this option to 0 and set bufferCommands to false on your schemas if you want your database operations to fail immediately when the driver is not connected, as opposed to waiting for reconnection.

• [options.connectTimeoutMS=30000] «Number» How long the MongoDB driver will wait before killing a socket due to inactivity during initial connection. Defaults to 30000. This option is passed transparently to Node.js’ socket#setTimeout() function.

• [options.socketTimeoutMS=30000] «Number» How long the MongoDB driver will wait before killing a socket due to inactivity after initial connection. A socket may be inactive because of either no activity or a long-running operation. This is set to 30000 by default, you should set this to 2-3x your longest running operation if you expect some of your database operations to run longer than 20 seconds. This option is passed to after the MongoDB driver successfully completes.

• [options.family=0] «Number» Passed transparently to Node.js’ dns.lookup() function. May be either 0, 4, or 6. 4 means use IPv4 only, 6 means use IPv6 only, 0 means try both.

Returns:

• «Connection» the created Connection object. Connections are thenable, so you can do await mongoose.createConnection()

Creates a Connection instance.

Each connection instance maps to a single database. This method is helpful when managing multiple db connections.

Options passed take precedence over options included in connection strings.

Example:

// with mongodb:// URI
db = mongoose.createConnection('mongodb://user:pass@localhost:port/database');
// and options
const opts = { db: { native_parser: true }}
db = mongoose.createConnection('mongodb://user:pass@localhost:port/database', opts);
// replica sets
db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database');
// and options
const opts = { replset: { strategy: 'ping', rs_name: 'testSet' }}
db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database', opts);
// and options
const opts = { server: { auto_reconnect: false }, user: 'username', pass: 'mypassword' }
db = mongoose.createConnection('localhost', 'database', port, opts)
// initialize now, connect later
db = mongoose.createConnection();
db.openUri('localhost', 'database', port, [opts]);

Mongoose.prototype.deleteModel()

Parameters

• name «String|RegExp» if string, the name of the model to remove. If regexp, removes all models whose name matches the regexp.

Returns:

• «Mongoose» this

Removes the model named name from the default connection, if it exists. You can use this function to clean up any models you created in your tests to prevent OverwriteModelErrors.

Equivalent to mongoose.connection.deleteModel(name).

Example:

mongoose.model('User', new Schema({ name: String }));
console.log(mongoose.model('User')); // Model object
mongoose.deleteModel('User');
console.log(mongoose.model('User')); // undefined
// Usually useful in a Mocha `afterEach()` hook
afterEach(function() {
  mongoose.deleteModel(/.+/); // Delete every model
});

Parameters

• [callback] «Function» called after all connection close, or when first error occurred.

Returns:

• «Promise» resolves when all connections are closed, or rejects with the first error that occurred.

Runs .close() on all connections in parallel.

Type:

• «property»

Object with get() and set() containing the underlying driver this Mongoose instance uses to communicate with the database. A driver is a Mongoose-specific interface that defines functions like find().

Mongoose.prototype.get()

Parameters

• key «String»

Gets mongoose options

Example:

mongoose.get('test') // returns the 'test' value

Mongoose.prototype.isValidObjectId()

Returns true if Mongoose can cast the given value to an ObjectId, or false otherwise.

Example:

mongoose.isValidObjectId(new mongoose.Types.ObjectId()); // true
mongoose.isValidObjectId('0123456789ab'); // true
mongoose.isValidObjectId(6); // false

Parameters

• name «String|Function» model name or class extending Model

• [schema] «Schema» the schema to use.

• [collection] «String» name (optional, inferred from model name)

• [skipInit] «Boolean|Object» whether to skip initialization (defaults to false). If an object, treated as options.

Returns:

• «Model» The model associated with name. Mongoose will create the model if it doesn’t already exist.

Defines a model or retrieves it.

Models defined on the mongoose instance are available to all connection created by the same mongoose instance.

If you call mongoose.model() with twice the same name but a different schema, you will get an OverwriteModelError. If you call mongoose.model() with the same name and same schema, you’ll get the same schema back.

Example:

const mongoose = require('mongoose');
// define an Actor model with this mongoose instance
const schema = new Schema({ name: String });
mongoose.model('Actor', schema);
// create a new connection
const conn = mongoose.createConnection(..);
// create Actor model
const Actor = conn.model('Actor', schema);
conn.model('Actor') === Actor; // true
conn.model('Actor', schema) === Actor; // true, same schema
conn.model('Actor', schema, 'actors') === Actor; // true, same schema and collection name
// This throws an `OverwriteModelError` because the schema is different.
conn.model('Actor', new Schema({ name: String }));

When no collection argument is passed, Mongoose uses the model name. If you don’t like this behavior, either pass a collection name, use mongoose.pluralize(), or set your schemas collection name option.

Example:

const schema = new Schema({ name: String }, { collection: 'actor' });
// or
schema.set('collection', 'actor');
// or
const collectionName = 'actor'
const M = mongoose.model('Actor', schema, collectionName)

Returns:

• «Array»

Returns an array of model names created on this instance of Mongoose.

Note:

Does not include names of models created using connection.model().

Type:

• «property»

The driver Mongoose uses.

Type:

• «property»

The query builder Mongoose uses.

Mongoose uses this function to get the current time when setting timestamps. You may stub out this function using a tool like for testing.

Parameters

• fn «Function» plugin callback

• [opts] «Object» optional options

Returns:

• «Mongoose» this

Declares a global plugin executed on all Schemas.

Equivalent to calling .plugin(fn) on each Schema you create.

Parameters

• [fn] «Function|null» overwrites the function used to pluralize collection names

Returns:

• «Function,null» the current function used to pluralize collection names, defaults to the legacy function from mongoose-legacy-pluralize.

Getter/setter around function for pluralizing collection names.

Parameters

• key «String»
• value «String|Function|Boolean»

Sets mongoose options

Example:

mongoose.set('test', value) // sets the 'test' option to `value`
mongoose.set('debug', true) // enable logging collection methods + arguments to the console/file
mongoose.set('debug', function(collectionName, methodName, ...methodArgs) {}); // use custom function to log collection methods + arguments

Currently supported options are

• ‘debug’: If true, prints the operations mongoose sends to MongoDB to the console. If a writable stream is passed, it will log to that stream, without colorization. If a callback function is passed, it will receive the collection name, the method name, then all arugments passed to the method. For example, if you wanted to replicate the default logging, you could output from the callback Mongoose: ${collectionName}.${methodName}(${methodArgs.join(', ')}).
• ‘returnOriginal’: If false, changes the default returnOriginal option to findOneAndUpdate(), findByIdAndUpdate, and findOneAndReplace() to false. This is equivalent to setting the new option to true for findOneAndX() calls by default. Read our for more information.
• ‘bufferCommands’: enable/disable mongoose’s buffering mechanism for all connections and models
• ‘useCreateIndex’: false by default. Set to true to make Mongoose’s default index build use createIndex() instead of ensureIndex() to avoid deprecation warnings from the MongoDB driver.
• ‘useFindAndModify’: true by default. Set to false to make findOneAndUpdate() and findOneAndRemove() use native findOneAndUpdate() rather than findAndModify().
• ‘useNewUrlParser’: false by default. Set to true to make all connections set the useNewUrlParser option by default
• ‘useUnifiedTopology’: false by default. Set to true to make all connections set the useUnifiedTopology option by default
• ‘cloneSchemas’: false by default. Set to true to clone() all schemas before compiling into a model.
• ‘applyPluginsToDiscriminators’: false by default. Set to true to apply global plugins to discriminator schemas. This typically isn’t necessary because plugins are applied to the base schema and discriminators copy all middleware, methods, statics, and properties from the base schema.
• ‘applyPluginsToChildSchemas’: true by default. Set to false to skip applying global plugins to child schemas
• ‘objectIdGetter’: true by default. Mongoose adds a getter to MongoDB ObjectId’s called _id that returns this for convenience with populate. Set this to false to remove the getter.
• ‘runValidators’: false by default. Set to true to enable update validators for all validators by default.
• ‘toObject’: { transform: true, flattenDecimals: true } by default. Overwrites default objects to
• ‘toJSON’: { transform: true, flattenDecimals: true } by default. Overwrites default objects to toJSON(), for determining how Mongoose documents get serialized by JSON.stringify()
• ‘strict’: true by default, may be false, true, or 'throw'. Sets the default strict mode for schemas.
• ‘strictQuery’: false by default, may be false, true, or 'throw'. Sets the default mode for schemas.
• ‘selectPopulatedPaths’: true by default. Set to false to opt out of Mongoose adding all fields that you populate() to your select(). The schema-level option selectPopulatedPaths overwrites this one.
• ‘typePojoToMixed’: true by default, may be false or true. Sets the default typePojoToMixed for schemas.
• ‘maxTimeMS’: If set, attaches maxTimeMS to every query
• ‘autoIndex’: true by default. Set to false to disable automatic index creation for all models associated with this Mongoose instance.
• ‘autoCreate’: Set to true to make Mongoose call automatically when you create a model with mongoose.model() or conn.model(). This is useful for testing transactions, change streams, and other features that require the collection to exist.
• ‘overwriteModels’: Set to true to default to overwriting models with the same name when calling mongoose.model(), as opposed to throwing an OverwriteModelError.

Parameters

• [options] «Object» see the

• [options.causalConsistency=true] «Boolean» set to false to disable causal consistency

• [callback] «Function»

Returns:

• «Promise<ClientSession>» promise that resolves to a MongoDB driver ClientSession

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

Calling mongoose.startSession() is equivalent to calling mongoose.connection.startSession(). Sessions are scoped to a connection, so calling mongoose.startSession() starts a session on the default mongoose connection.

Mongoose.prototype.version

Type:

• «property»

The Mongoose version

Example

console.log(mongoose.version); // '5.x.x'

Schema

• Schema.Types
• Schema.prototype.add()
• Schema.prototype.clone()
• Schema.prototype.get()
• Schema.prototype.indexes()
• Schema.prototype.method()
• Schema.prototype.path()
• Schema.prototype.paths
• Schema.prototype.plugin()
• Schema.prototype.pre()
• Schema.prototype.remove()
• Schema.prototype.set()
• Schema.prototype.virtual()
• Schema.reserved

Schema()

Parameters

• [definition] «Object|Schema|Array» Can be one of: object describing schema paths, or schema to copy, or array of objects and schemas

• [options] «Object»

Schema constructor.

Example:

const child = new Schema({ name: String });
const schema = new Schema({ name: String, age: Number, children: [child] });
const Tree = mongoose.model('Tree', schema);
// setting schema options
new Schema({ name: String }, { _id: false, autoIndex: false })

Options:

• autoIndex: bool - defaults to null (which means use the connection’s autoIndex option)
• : bool - defaults to null (which means use the connection’s autoCreate option)
• bufferCommands: bool - defaults to true
• : number - defaults to 10000 (10 seconds). If bufferCommands is enabled, the amount of time Mongoose will wait for connectivity to be restablished before erroring out.
• capped: bool - defaults to false
• : string - no default
• discriminatorKey: string - defaults to __t
• : bool - defaults to true
• _id: bool - defaults to true
• : bool - controls document#toObject behavior when called manually - defaults to true
• : string
• writeConcern: object - defaults to null, use to override
• shardKey: object - defaults to null
• : bool - defaults to true
• strictQuery: bool - defaults to false
• - object - no default
• toObject - object - no default
• - string - defaults to ‘type’
• typePojoToMixed - boolean - defaults to true. Determines whether a type set to a POJO becomes a Mixed path or a Subdocument
• - boolean - defaults to false
• validateBeforeSave - bool - defaults to true
• : string or object - defaults to “__v”
• optimisticConcurrency: bool - defaults to false. Set to true to enable .
• collation: object - defaults to null (which means use no collation)
• : boolean - defaults to true
• skipVersioning: object - paths to exclude from versioning
• : object or boolean - defaults to false. If true, Mongoose adds createdAt and updatedAt properties to your schema and manages those properties for you.
• storeSubdocValidationError: boolean - Defaults to true. If false, Mongoose will wrap validation errors in single nested document subpaths into a single validation error on the single nested subdoc’s path.

Options for Nested Schemas:

• excludeIndexes: bool - defaults to false. If true, skip building indexes on this schema’s paths.

Note:

When nesting schemas, (children in the example above), always declare the child schema first before passing it into its parent.

Schema.Types

Type:

• «property»

The various built-in Mongoose Schema Types.

Example:

const mongoose = require('mongoose');
const ObjectId = mongoose.Schema.Types.ObjectId;

Types:

• String
• Boolean | Bool
• Buffer
• ObjectId | Oid

Using this exposed access to the Mixed SchemaType, we can use them in our schema.

const Mixed = mongoose.Schema.Types.Mixed;
new mongoose.Schema({ _user: Mixed })

Type:

• «property»

The allowed index types

Schema.prototype.add()

Parameters

• obj «Object|Schema» plain object with paths to add, or another schema

• [prefix] «String» path to prefix the newly added paths with

Returns:

• «Schema» the Schema instance

Adds key path / schema type pairs to this schema.

Example:

const ToySchema = new Schema();
ToySchema.add({ name: 'string', color: 'string', price: 'number' });
const TurboManSchema = new Schema();
// You can also `add()` another schema and copy over all paths, virtuals,
// getters, setters, indexes, methods, and statics.
TurboManSchema.add(ToySchema).add({ year: Number });

Type:

• «property»

Array of child schemas (from document arrays and single nested subdocs) and their corresponding compiled models. Each element of the array is an object with 2 properties: schema and model.

This property is typically only useful for plugin authors and advanced users. You do not need to interact with this property at all to use mongoose.

Schema.prototype.clone()

Returns:

• «Schema» the cloned schema

Returns a deep copy of the schema

Example:

const schema = new Schema({ name: String });
const clone = schema.clone();
clone === schema; // false
clone.path('name'); // SchemaString { ... }

Schema.prototype.eachPath()

Parameters

• fn «Function» callback function

Returns:

• «Schema» this

Iterates the schemas paths similar to Array#forEach.

The callback is passed the pathname and the schemaType instance.

Example:

const userSchema = new Schema({ name: String, registeredAt: Date });
userSchema.eachPath((pathname, schematype) => {
  // Prints twice:
  // name SchemaString { ... }
  // registeredAt SchemaDate { ... }
  console.log(pathname, schematype);
});

Parameters

• key «String» option name

Returns:

• «Any» the option’s value

Gets a schema option.

Example:

schema.get('strict'); // true
schema.set('strict', false);
schema.get('strict'); // false

Schema.prototype.index()

Parameters

• fields «Object»

• [options] «Object» Options to pass to MongoDB driver’s createIndex() function

• | «String» number} [options.expires=null] Mongoose-specific syntactic sugar, uses to convert expires option into seconds for the expireAfterSeconds in the above link.

Defines an index (most likely compound) for this schema.

Example

schema.index({ first: 1, last: -1 })

Schema.prototype.indexes()

Returns:

• «Array» list of indexes defined in the schema

Returns a list of indexes that this schema declares, via schema.index() or by index: true in a path’s options. Indexes are expressed as an array [spec, options].

Example:

const userSchema = new Schema({
  email: { type: String, required: true, unique: true },
  registeredAt: { type: Date, index: true }
});
// [ [ { email: 1 }, { unique: true, background: true } ],
//   [ { registeredAt: 1 }, { background: true } ] ]
userSchema.indexes();

can use the return value of this function to modify a schema’s indexes. For example, the below plugin makes every index unique by default.

function myPlugin(schema) {
  for (const index of schema.indexes()) {
    if (index[1].unique === undefined) {
      index[1].unique = true;
    }
  }
}

Parameters

• model «Function»
• [virtualsOnly] «Boolean» if truthy, only pulls virtuals from the class, not methods or statics

Loads an ES6 class into a schema. Maps + getters, , and instance methods to schema , statics, and .

Example:

const md5 = require('md5');
const userSchema = new Schema({ email: String });
class UserClass {
  // `gravatarImage` becomes a virtual
  get gravatarImage() {
    const hash = md5(this.email.toLowerCase());
    return `https://www.gravatar.com/avatar/${hash}`;
  }
  // `getProfileUrl()` becomes a document method
  getProfileUrl() {
    return `https://mysite.com/${this.email}`;
  }
  // `findByEmail()` becomes a static
  static findByEmail(email) {
    return this.findOne({ email });
  }
}
// `schema` will now have a `gravatarImage` virtual, a `getProfileUrl()` method,
// and a `findByEmail()` static
userSchema.loadClass(UserClass);

Schema.prototype.method()

Parameters

• method «String|Object» name

• [fn] «Function»

Adds an instance method to documents constructed from Models compiled from this schema.

Example

const schema = kittySchema = new Schema(..);
schema.method('meow', function () {
  console.log('meeeeeoooooooooooow');
})
const Kitty = mongoose.model('Kitty', schema);
const fizz = new Kitty;
fizz.meow(); // meeeeeooooooooooooow

If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as methods.

schema.method({
    purr: function () {}
  , scratch: function () {}
});
// later
fizz.purr();
fizz.scratch();

NOTE: Schema.method() adds instance methods to the Schema.methods object. You can also add instance methods directly to the Schema.methods object as seen in the

Type:

• «property»

The original object passed to the schema constructor

Example:

const schema = new Schema({ a: String }).add({ b: String });
schema.obj; // { a: String }

Parameters

• path «String»
• constructor «Object»

Gets/sets schema paths.

Sets a path (if arity 2) Gets a path (if arity 1)

Example

schema.path('name') // returns a SchemaType
schema.path('name', Number) // changes the schemaType of `name` to Number

Parameters

• path «String»

Returns:

• «String»

Returns the pathType of path for this schema.

Given a path, returns whether it is a real, virtual, nested, or ad-hoc/undefined path.

Example:

const s = new Schema({ name: String, nested: { foo: String } });
s.virtual('foo').get(() => 42);
s.pathType('name'); // "real"
s.pathType('nested'); // "nested"
s.pathType('foo'); // "virtual"
s.pathType('fail'); // "adhocOrUndefined"

Schema.prototype.paths

Type:

• «property»

The paths defined on this schema. The keys are the top-level paths in this schema, and the values are instances of the SchemaType class.

Example:

const schema = new Schema({ name: String }, { _id: false });
schema.paths; // { name: SchemaString { ... } }
schema.add({ age: Number });
schema.paths; // { name: SchemaString { ... }, age: SchemaNumber { ... } }

Schema.prototype.pick()

Parameters

• paths «Array» list of paths to pick

• [options] «Object» options to pass to the schema constructor. Defaults to this.options if not set.

Returns:

• «Schema»

Returns a new schema that has the picked paths from this schema.

This method is analagous to for Mongoose schemas.

Example:

const schema = Schema({ name: String, age: Number });
// Creates a new schema with the same `name` path as `schema`,
// but no `age` path.
const newSchema = schema.pick(['name']);
newSchema.path('name'); // SchemaString { ... }
newSchema.path('age'); // undefined

Schema.prototype.plugin()

Parameters

• plugin «Function» callback

• [opts] «Object»

Registers a plugin for this schema.

Example:

const s = new Schema({ name: String });
s.plugin(schema => console.log(schema.path('name').path));
mongoose.model('Test', s); // Prints 'name'

Schema.prototype.post()

Parameters

• The «String|RegExp» method name or regular expression to match method name

• [options] «Object»

• [options.document] «Boolean» If name is a hook for both document and query middleware, set to true to run on document middleware.

• [options.query] «Boolean» If name is a hook for both document and query middleware, set to true to run on query middleware.

• fn «Function» callback

Defines a post hook for the document

const schema = new Schema(..);
schema.post('save', function (doc) {
  console.log('this fired after a document was saved');
});
schema.post('find', function(docs) {
  console.log('this fired after you ran a find query');
});
schema.post(/Many$/, function(res) {
  console.log('this fired after you ran `updateMany()` or `deleteMany()`);
});
const Model = mongoose.model('Model', schema);
const m = new Model(..);
m.save(function(err) {
  console.log('this fires after the `post` hook');
});
m.find(function(err, docs) {
  console.log('this fires after the post find hook');
});

Parameters

• The «String|RegExp» method name or regular expression to match method name

• [options] «Object»

• [options.document] «Boolean» If name is a hook for both document and query middleware, set to true to run on document middleware. For example, set options.document to true to apply this hook to Document#deleteOne() rather than Query#deleteOne().

• [options.query] «Boolean» If name is a hook for both document and query middleware, set to true to run on query middleware.

• callback «Function»

Defines a pre hook for the model.

Example

const toySchema = new Schema({ name: String, created: Date });
toySchema.pre('save', function(next) {
  if (!this.created) this.created = new Date;
  next();
});
toySchema.pre('validate', function(next) {
  if (this.name !== 'Woody') this.name = 'Woody';
  next();
});
// Equivalent to calling `pre()` on `find`, `findOne`, `findOneAndUpdate`.
toySchema.pre(/^find/, function(next) {
  console.log(this.getFilter());
});
// Equivalent to calling `pre()` on `updateOne`, `findOneAndUpdate`.
toySchema.pre(['updateOne', 'findOneAndUpdate'], function(next) {
  console.log(this.getFilter());
});
toySchema.pre('deleteOne', function() {
  // Runs when you call `Toy.deleteOne()`
});
toySchema.pre('deleteOne', { document: true }, function() {
  // Runs when you call `doc.deleteOne()`
});

Parameters

• name «String» name of the document method to call later

• args «Array» arguments to pass to the method

Adds a method call to the queue.

Example:

schema.methods.print = function() { console.log(this); };
schema.queue('print', []); // Print the doc every one is instantiated
const Model = mongoose.model('Test', schema);
new Model({ name: 'test' }); // Prints '{"_id": ..., "name": "test" }'

Parameters

• path «String|Array»

Returns:

• «Schema» the Schema instance

Removes the given path (or [paths]).

Example:

const schema = new Schema({ name: String, age: Number });
schema.remove('name');
schema.path('name'); // Undefined
schema.path('age'); // SchemaNumber { ... }

Schema.prototype.requiredPaths()

Parameters

• invalidate «Boolean» refresh the cache

Returns:

• «Array»

Returns an Array of path strings that are required by this schema.

Example:

const s = new Schema({
  name: { type: String, required: true },
  age: { type: String, required: true },
  notes: String
});
s.requiredPaths(); // [ 'age', 'name' ]

Parameters

• key «String» option name

• [value] «Object» if not passed, the current option value is returned

Sets a schema option.

Example

schema.set('strict'); // 'true' by default
schema.set('strict', false); // Sets 'strict' to false
schema.set('strict'); // 'false'

Parameters

• name «String|Object»
• [fn] «Function»

Adds static “class” methods to Models compiled from this schema.

Example

const schema = new Schema(..);
// Equivalent to `schema.statics.findByName = function(name) {}`;
schema.static('findByName', function(name) {
  return this.find({ name: name });
});
const Drink = mongoose.model('Drink', schema);
await Drink.findByName('LaCroix');

If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.

Parameters

• name «String»

• [options] «Object»

• [options.ref] «String|Model» model name or model instance. Marks this as a .

• [options.localField] «String|Function» Required for populate virtuals. See populate virtual docs for more information.

• [options.foreignField] «String|Function» Required for populate virtuals. See for more information.

• [options.justOne=false] «Boolean|Function» Only works with populate virtuals. If truthy, will be a single doc or null. Otherwise, the populate virtual will be an array.

• [options.count=false] «Boolean» Only works with populate virtuals. If , this populate virtual will contain the number of documents rather than the documents themselves when you populate().

• [options.get=null] «Function|null» Adds a getter to this virtual to transform the populated doc.

Returns:

• «VirtualType»

Creates a virtual type with the given name.

Parameters

• name «String»

Returns:

• «VirtualType»

Returns the virtual type with the given name.

Type:

• «property»

Reserved document keys.

Keys in this object are names that are rejected in schema declarations because they conflict with Mongoose functionality. If you create a schema using new Schema() with one of these property names, Mongoose will throw an error.

• _posts
• _pres
• collection
• emit
• errors
• get
• init
• isModified
• isNew
• listeners
• modelName
• on
• once
• populated
• prototype
• remove
• removeListener
• save
• schema
• toObject
• validate

NOTE: Use of these terms as method names is permitted, but play at your own risk, as they may be existing mongoose document methods you are stomping on.

const schema = new Schema(..);
 schema.methods.init = function () {} // potentially breaking

Connection

• Connection.prototype.client
• Connection.prototype.collection()
• Connection.prototype.config
• Connection.prototype.db
• Connection.prototype.dropCollection()
• Connection.prototype.get()
• Connection.prototype.host
• Connection.prototype.model()
• Connection.prototype.models
• Connection.prototype.openUri()
• Connection.prototype.plugin()
• Connection.prototype.port
• Connection.prototype.set()
• Connection.prototype.startSession()
• Connection.prototype.useDb()
• Connection.prototype.watch()

Connection()

Parameters

• base «Mongoose» a mongoose instance

Connection constructor

For practical reasons, a Connection equals a Db.

Type:

• «property»

The MongoClient instance this connection uses to talk to MongoDB. Mongoose automatically sets this property when the connection is opened.

Connection.prototype.close()

Parameters

• [force] «Boolean» optional

• [callback] «Function» optional

Returns:

• «Promise»

Closes the connection

Connection.prototype.collection()

Parameters

• name «String» of the collection

• [options] «Object» optional collection options

Returns:

• «Collection» collection instance

Retrieves a collection, creating it if not cached.

Not typically needed by applications. Just talk to your collection through your model.

Connection.prototype.collections

Type:

• «property»

A hash of the collections associated with this connection

Type:

• «property»

A hash of the global options that are associated with this connection

Connection.prototype.createCollection()

Parameters

• collection «string» The collection to create

• [options] «Object» see MongoDB driver docs

• [callback] «Function»

Returns:

• «Promise»

Helper for createCollection(). Will explicitly create the given collection with specified options. Used to create capped collections and from mongoose.

Options are passed down without modification to the MongoDB driver’s createCollection() function

Connection.prototype.db

Type:

• «property»

The mongodb.Db instance, set when the connection is opened

Parameters

• name «String|RegExp» if string, the name of the model to remove. If regexp, removes all models whose name matches the regexp.

Returns:

• «Connection» this

Removes the model named name from this connection, if it exists. You can use this function to clean up any models you created in your tests to prevent OverwriteModelErrors.

Example:

conn.model('User', new Schema({ name: String }));
console.log(conn.model('User')); // Model object
conn.deleteModel('User');
console.log(conn.model('User')); // undefined
// Usually useful in a Mocha `afterEach()` hook
afterEach(function() {
  conn.deleteModel(/.+/); // Delete every model
});

Connection.prototype.dropCollection()

Parameters

• collection «string» The collection to delete

• [callback] «Function»

Returns:

• «Promise»

Helper for dropCollection(). Will delete the given collection, including all documents and indexes.

Connection.prototype.dropDatabase()

Parameters

• [callback] «Function»

Returns:

• «Promise»

Helper for dropDatabase(). Deletes the given database, including all collections, documents, and indexes.

Example:

const conn = mongoose.createConnection('mongodb://localhost:27017/mydb');
// Deletes the entire 'mydb' database
await conn.dropDatabase();

Parameters

• key «String»

Gets the value of the option key. Equivalent to conn.options[key]

Example:

conn.get('test'); // returns the 'test' value

Returns:

• «MongoClient»

Returns the instance that this connection uses to talk to MongoDB.

Example:

const conn = await mongoose.createConnection('mongodb://localhost:27017/test');
conn.getClient(); // MongoClient { ... }