Schema

Connection

Model

QueryCursor

AggregationCursor

Virtualtype

Array

DocumentArrayPath

Parameters

  • [options] «Object»

Inherits:

Schema constructor.

Example:

Options:

  • : bool - defaults to null (which means use the connection’s autoIndex option)
  • autoCreate: bool - defaults to null (which means use the connection’s autoCreate option)
  • : bool - defaults to true
  • bufferTimeoutMS: number - defaults to 10000 (10 seconds). If is enabled, the amount of time Mongoose will wait for connectivity to be restablished before erroring out.
  • : bool - defaults to false
  • collection: string - no default
  • : string - defaults to __t
  • id: bool - defaults to true
  • : bool - defaults to true
  • minimize: bool - controls behavior when called manually - defaults to true
  • read: string
  • : object - defaults to null, use to override the MongoDB server’s default write concern settings
  • : object - defaults to null
  • strict: bool - defaults to true
  • : bool - defaults to false
  • toJSON - object - no default
  • - object - no default
  • typeKey - string - defaults to ‘type’
  • - boolean - defaults to true. Determines whether a type set to a POJO becomes a Mixed path or a Subdocument
  • useNestedStrict - boolean - defaults to false
  • - bool - defaults to true
  • versionKey: string or object - defaults to “__v”
  • : bool - defaults to false. Set to true to enable optimistic concurrency.
  • : object - defaults to null (which means use no collation)
  • selectPopulatedPaths: boolean - defaults to true
  • : object - paths to exclude from versioning
  • timestamps: object or boolean - defaults to false. If true, Mongoose adds createdAt and updatedAt properties to your schema and manages those properties for you.
  • : 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.

Type:
  • «property»

The various built-in Mongoose Schema Types.

Example:

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

Types:

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

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

Schema.indexTypes

Type:
  • «property»

The allowed index types

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:

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

Schema.prototype.childSchemas

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.

Returns:
  • «Schema» the cloned schema

Returns a deep copy of the schema

Example:

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

Parameters
  • fn «Function» callback function
Returns:
  • «Schema» this

Iterates the schemas paths similar to Array#forEach.

Example:

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

Schema.prototype.get()

Parameters
  • key «String» option name
Returns:
  • «Any» the option’s value

Gets a schema option.

Example:

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

Parameters
  • fields «Object»

  • [options] «Object» Options to pass to

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

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

Example

  1. schema.index({ first: 1, last: -1 })
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:

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

Plugins 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.

Schema.prototype.loadClass()

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 setters + , static methods, and to schema virtuals, , and methods.

Example:

  1. const md5 = require('md5');
  2. const userSchema = new Schema({ email: String });
  3. class UserClass {
  4.   // `gravatarImage` becomes a virtual
  5.   get gravatarImage() {
  6.     const hash = md5(this.email.toLowerCase());
  7.     return `https://www.gravatar.com/avatar/${hash}`;
  8.   }
  10.   // `getProfileUrl()` becomes a document method
  11.   getProfileUrl() {
  12.     return `https://mysite.com/${this.email}`;
  13.   }
  15.   // `findByEmail()` becomes a static
  16.   static findByEmail(email) {
  17.     return this.findOne({ email });
  18.   }
  19. }
  21. // `schema` will now have a `gravatarImage` virtual, a `getProfileUrl()` method,
  22. // and a `findByEmail()` static
  23. userSchema.loadClass(UserClass);

Parameters

  • method «String|Object» name

  • [fn] «Function»

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

Example

  1. const schema = kittySchema = new Schema(..);
  3. schema.method('meow', function () {
  4.   console.log('meeeeeoooooooooooow');
  5. })
  7. const Kitty = mongoose.model('Kitty', schema);
  9. const fizz = new Kitty;
  10. 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.

  1. schema.method({
  2.     purr: function () {}
  3.   , scratch: function () {}
  4. });
  6. // later
  7. fizz.purr();
  8. 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 guide

Schema.prototype.obj

Type:
  • «property»

The original object passed to the schema constructor

Example:

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

Schema.prototype.path()

Parameters
  • path «String»
  • constructor «Object»

Gets/sets schema paths.

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

Example

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

Schema.prototype.pathType()

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:

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

Type:

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:

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

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 Lodash’s pick() function for Mongoose schemas.

Example:

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

Parameters

  • plugin «Function» callback

  • [opts] «Object»

Registers a plugin for this schema.

Example:

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.

Defines a post hook for the document

  1. const schema = new Schema(..);
  2. schema.post('save', function (doc) {
  3.   console.log('this fired after a document was saved');
  4. });
  6. schema.post('find', function(docs) {
  7.   console.log('this fired after you ran a find query');
  8. });
  10. schema.post(/Many$/, function(res) {
  11.   console.log('this fired after you ran `updateMany()` or `deleteMany()`);
  12. });
  14. const Model = mongoose.model('Model', schema);
  16. const m = new Model(..);
  17. m.save(function(err) {
  18.   console.log('this fires after the `post` hook');
  19. });
  21. m.find(function(err, docs) {
  22.   console.log('this fires after the post find hook');
  23. });

Schema.prototype.pre()

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

  1. const toySchema = new Schema({ name: String, created: Date });
  3. toySchema.pre('save', function(next) {
  4.   if (!this.created) this.created = new Date;
  5.   next();
  6. });
  8. toySchema.pre('validate', function(next) {
  9.   if (this.name !== 'Woody') this.name = 'Woody';
  10.   next();
  11. });
  13. // Equivalent to calling `pre()` on `find`, `findOne`, `findOneAndUpdate`.
  14. toySchema.pre(/^find/, function(next) {
  15.   console.log(this.getFilter());
  16. });
  18. // Equivalent to calling `pre()` on `updateOne`, `findOneAndUpdate`.
  19. toySchema.pre(['updateOne', 'findOneAndUpdate'], function(next) {
  20.   console.log(this.getFilter());
  21. });
  23. toySchema.pre('deleteOne', function() {
  24.   // Runs when you call `Toy.deleteOne()`
  25. });
  27. toySchema.pre('deleteOne', { document: true }, function() {
  28.   // Runs when you call `doc.deleteOne()`
  29. });

Schema.prototype.queue()

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:

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

Schema.prototype.remove()

Parameters
  • path «String|Array»
Returns:
  • «Schema» the Schema instance

Removes the given path (or [paths]).

Example:

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

Parameters
  • invalidate «Boolean» refresh the cache
Returns:
  • «Array»

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

Example:

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

Schema.prototype.set()

Parameters

  • key «String» option name

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

Sets a schema option.

Example

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

Schema.prototype.static()

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

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

Example

  1. const schema = new Schema(..);
  2. // Equivalent to `schema.statics.findByName = function(name) {}`;
  3. schema.static('findByName', function(name) {
  4.   return this.find({ name: name });
  5. });
  7. const Drink = mongoose.model('Drink', schema);
  8. 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.

Schema.prototype.virtual()

Parameters
  • name «String»

  • [options] «Object»

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

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

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

  • [options.justOne=false] «Boolean|Function» Only works with populate virtuals. If , 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 truthy, this populate virtual will contain the number of documents rather than the documents themselves when you populate().

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

Returns:
  • «VirtualType»

Creates a virtual type with the given name.

Schema.prototype.virtualpath()

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.