Schema

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)
• autoCreate: bool - defaults to null (which means use the connection's autoCreate option)
• bufferCommands: bool - defaults to true
• bufferTimeoutMS: 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
• collection: string - no default
• id: bool - defaults to true
• _id: bool - defaults to true
• minimize: bool - controls document#toObject behavior when called manually - defaults to true
• read: string
• writeConcern: object - defaults to null, use to override the MongoDB server's default write concern settings
• shardKey: object - defaults to null
• strict: bool - defaults to true
• strictQuery: bool - defaults to false
• toJSON - object - no default
• toObject - object - no default
• typeKey - string - defaults to 'type'
• typePojoToMixed - boolean - defaults to true. Determines whether a type set to a POJO becomes a Mixed path or a Subdocument
• useNestedStrict - boolean - defaults to false
• validateBeforeSave - bool - defaults to true
• versionKey: string or object - defaults to "__v"
• optimisticConcurrency: bool - defaults to false. Set to true to enable optimistic concurrency.
• collation: object - defaults to null (which means use no collation)
• selectPopulatedPaths: boolean - defaults to true
• skipVersioning: 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.
• 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.

The various built-in Mongoose Schema Types.

Example:

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

Types:

• String
• Number
• Boolean | Bool
• Array
• Buffer
• Date
• ObjectId | Oid
• Mixed

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 })

The allowed index types

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 });

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 a deep copy of the schema

Example:

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

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);
});

Gets a schema option.

Example:

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

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

Example

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

Returns a list of indexes that this schema declares, via schema.index() or by index: true in a path's 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();

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

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);

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 guide

The original object passed to the schema constructor

Example:

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

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

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"

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 { ... } }

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:

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

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'

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');
});

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()`
});

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" }'

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 { ... }

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' ]

Sets a schema option.

Example

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

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.

Creates a virtual type with the given name.

Returns the virtual type with the given name.

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