Schemas
If you haven't yet done so, please take a minute to read the quickstart to get an idea of how Mongoose works. If you are migrating from 4.x to 5.x please take a moment to read the migration guide.
Defining your schema
Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.
var mongoose = require('mongoose');
var Schema = mongoose.Schema;
var blogSchema = new Schema({
title: String,
author: String,
body: String,
comments: [{ body: String, date: Date }],
date: { type: Date, default: Date.now },
hidden: Boolean,
meta: {
votes: Number,
favs: Number
}
});
If you want to add additional keys later, use the Schema#add method.
Each key in our code blogSchema
defines a property in our documents which
will be cast to its associated SchemaType.
For example, we've defined a property title
which will be cast to the
String SchemaType and property date
which will be cast to a Date
SchemaType. Keys may also be assigned
nested objects containing further key/type definitions like
the meta
property above.
The permitted SchemaTypes are:
- String
- Number
- Date
- Buffer
- Boolean
- Mixed
- ObjectId
- Array
- Decimal128
- Map
Read more about SchemaTypes here.
Schemas not only define the structure of your document and casting of properties, they also define document instance methods, static Model methods, compound indexes, and document lifecycle hooks called middleware.
Creating a model
To use our schema definition, we need to convert our blogSchema
into a
Model we can work with.
To do so, we pass it into mongoose.model(modelName, schema)
:
var Blog = mongoose.model('Blog', blogSchema);
// ready to go!
Instance methods
Instances of Models
are documents. Documents have
many of their own built-in instance methods.
We may also define our own custom document instance methods too.
// define a schema
var animalSchema = new Schema({ name: String, type: String });
// assign a function to the "methods" object of our animalSchema
animalSchema.methods.findSimilarTypes = function(cb) {
return this.model('Animal').find({ type: this.type }, cb);
};
Now all of our animal
instances have a findSimilarTypes
method available
to them.
var Animal = mongoose.model('Animal', animalSchema);
var dog = new Animal({ type: 'dog' });
dog.findSimilarTypes(function(err, dogs) {
console.log(dogs); // woof
});
- Overwriting a default mongoose document method may lead to unpredictable results. See this for more details.
- The example above uses the
Schema.methods
object directly to save an instance method. You can also use theSchema.method()
helper as described here. - Do not declare methods using ES6 arrow functions (
=>
). Arrow functions explicitly prevent bindingthis
, so your method will not have access to the document and the above examples will not work.
Statics
Adding static methods to a Model
is simple as well. Continuing with our
animalSchema
:
// assign a function to the "statics" object of our animalSchema
animalSchema.statics.findByName = function(name, cb) {
return this.find({ name: new RegExp(name, 'i') }, cb);
};
var Animal = mongoose.model('Animal', animalSchema);
Animal.findByName('fido', function(err, animals) {
console.log(animals);
});
Do not declare statics using ES6 arrow functions (=>
). Arrow functions explicitly prevent binding this
, so the above examples will not work because of the value of this
.
Query Helpers
You can also add query helper functions, which are like instance methods but for mongoose queries. Query helper methods let you extend mongoose's chainable query builder API.
animalSchema.query.byName = function(name) {
return this.where({ name: new RegExp(name, 'i') });
};
var Animal = mongoose.model('Animal', animalSchema);
Animal.find().byName('fido').exec(function(err, animals) {
console.log(animals);
});
Animal.findOne().byName('fido').exec(function(err, animal) {
console.log(animal);
});
Indexes
MongoDB supports secondary indexes.
With mongoose, we define these indexes within our Schema
at the path level or the schema
level.
Defining indexes at the schema level is necessary when creating
compound indexes.
var animalSchema = new Schema({
name: String,
type: String,
tags: { type: [String], index: true } // field level
});
animalSchema.index({ name: 1, type: -1 }); // schema level
When your application starts up, Mongoose automatically calls createIndex
for each defined index in your schema.
Mongoose will call createIndex
for each index sequentially, and emit an 'index' event on the model when all the createIndex
calls succeeded or when there was an error.
While nice for development, it is recommended this behavior be disabled in production since index creation can cause a significant performance impact. Disable the behavior by setting the autoIndex
option of your schema to false
, or globally on the connection by setting the option autoIndex
to false
.
mongoose.connect('mongodb://user:pass@localhost:port/database', { autoIndex: false });
// or
mongoose.createConnection('mongodb://user:pass@localhost:port/database', { autoIndex: false });
// or
animalSchema.set('autoIndex', false);
// or
new Schema({..}, { autoIndex: false });
Mongoose will emit an index
event on the model when indexes are done
building or an error occurred.
// Will cause an error because mongodb has an _id index by default that
// is not sparse
animalSchema.index({ _id: 1 }, { sparse: true });
var Animal = mongoose.model('Animal', animalSchema);
Animal.on('index', function(error) {
// "_id index cannot be sparse"
console.log(error.message);
});
See also the Model#ensureIndexes method.
Virtuals
Virtuals are document properties that you can get and set but that do not get persisted to MongoDB. The getters are useful for formatting or combining fields, while setters are useful for de-composing a single value into multiple values for storage.
// define a schema
var personSchema = new Schema({
name: {
first: String,
last: String
}
});
// compile our model
var Person = mongoose.model('Person', personSchema);
// create a document
var axl = new Person({
name: { first: 'Axl', last: 'Rose' }
});
Suppose you want to print out the person's full name. You could do it yourself:
console.log(axl.name.first + ' ' + axl.name.last); // Axl Rose
But concatenating the first and last name every time can get cumbersome. And what if you want to do some extra processing on the name, like removing diacritics? A virtual property getter lets you
define a fullName
property that won't get persisted to MongoDB.
personSchema.virtual('fullName').get(function () {
return this.name.first + ' ' + this.name.last;
});
Now, mongoose will call your getter function every time you access the
fullName
property:
console.log(axl.fullName); // Axl Rose
If you use toJSON()
or toObject()
mongoose will not include virtuals
by default. This includes the output of calling JSON.stringify()
on a Mongoose document, because JSON.stringify()
calls toJSON()
.
Pass { virtuals: true }
to either
toObject()
or toJSON()
.
You can also add a custom setter to your virtual that will let you set both
first name and last name via the fullName
virtual.
personSchema.virtual('fullName').
get(function() { return this.name.first + ' ' + this.name.last; }).
set(function(v) {
this.name.first = v.substr(0, v.indexOf(' '));
this.name.last = v.substr(v.indexOf(' ') + 1);
});
axl.fullName = 'William Rose'; // Now `axl.name.first` is "William"
Virtual property setters are applied before other validation. So the example
above would still work even if the first
and last
name fields were
required.
Only non-virtual properties work as part of queries and for field selection. Since virtuals are not stored in MongoDB, you can't query with them.
Aliases
Aliases are a particular type of virtual where the getter and setter seamlessly get and set another property. This is handy for saving network bandwidth, so you can convert a short property name stored in the database into a longer name for code readability.
var personSchema = new Schema({
n: {
type: String,
// Now accessing `name` will get you the value of `n`, and setting `n` will set the value of `name`
alias: 'name'
}
});
// Setting `name` will propagate to `n`
var person = new Person({ name: 'Val' });
console.log(person); // { n: 'Val' }
console.log(person.toObject({ virtuals: true })); // { n: 'Val', name: 'Val' }
console.log(person.name); // "Val"
person.name = 'Not Val';
console.log(person); // { n: 'Not Val' }
You can also declare aliases on nested paths. It is easier to use nested
schemas and subdocuments, but you can also declare
nested path aliases inline as long as you use the full nested path
nested.myProp
as the alias.
const childSchema = new Schema({
n: {
type: String,
alias: 'name'
}
}, { _id: false });
const parentSchema = new Schema({
// If in a child schema, alias doesn't need to include the full nested path
c: childSchema,
name: {
f: {
type: String,
// Alias needs to include the full nested path if declared inline
alias: 'name.first'
}
}
});
Options
Schemas have a few configurable options which can be passed to the
constructor or set
directly:
new Schema({..}, options);
// or
var schema = new Schema({..});
schema.set(option, value);
Valid options:
- autoIndex
- bufferCommands
- capped
- collection
- id
- _id
- minimize
- read
- writeConcern
- safe
- shardKey
- strict
- strictQuery
- toJSON
- toObject
- typeKey
- validateBeforeSave
- versionKey
- collation
- skipVersioning
- timestamps
option: autoIndex
At application startup, Mongoose sends a createIndex
command for each index declared in your Schema
. As of Mongoose v3, indexes are created in the background
by default. If you wish to disable the auto-creation feature and manually handle when indexes are created, set your Schema
s autoIndex
option to false
and use the ensureIndexes method on your model.
var schema = new Schema({..}, { autoIndex: false });
var Clock = mongoose.model('Clock', schema);
Clock.ensureIndexes(callback);
option: bufferCommands
By default, mongoose buffers commands when the connection goes down until
the driver manages to reconnect. To disable buffering, set bufferCommands
to false.
var schema = new Schema({..}, { bufferCommands: false });
The schema bufferCommands
option overrides the global bufferCommands
option.
mongoose.set('bufferCommands', true);
// Schema option below overrides the above, if the schema option is set.
var schema = new Schema({..}, { bufferCommands: false });
option: capped
Mongoose supports MongoDBs capped
collections. To specify the underlying MongoDB collection be capped
, set
the capped
option to the maximum size of the collection in
bytes.
new Schema({..}, { capped: 1024 });
The capped
option may also be set to an object if you want to pass
additional options like max
or autoIndexId.
In this case you must explicitly pass the size
option, which is required.
new Schema({..}, { capped: { size: 1024, max: 1000, autoIndexId: true } });
option: collection
Mongoose by default produces a collection name by passing the model name to the utils.toCollectionName method. This method pluralizes the name. Set this option if you need a different name for your collection.
var dataSchema = new Schema({..}, { collection: 'data' });
option: id
Mongoose assigns each of your schemas an id
virtual getter by default
which returns the documents _id
field cast to a string, or in the case of
ObjectIds, its hexString. If you don't want an id
getter added to your
schema, you may disable it passing this option at schema construction time.
// default behavior
var schema = new Schema({ name: String });
var Page = mongoose.model('Page', schema);
var p = new Page({ name: 'mongodb.org' });
console.log(p.id); // '50341373e894ad16347efe01'
// disabled id
var schema = new Schema({ name: String }, { id: false });
var Page = mongoose.model('Page', schema);
var p = new Page({ name: 'mongodb.org' });
console.log(p.id); // undefined
option: _id
Mongoose assigns each of your schemas an _id
field by default if one
is not passed into the Schema constructor.
The type assigned is an ObjectId
to coincide with MongoDB's default behavior. If you don't want an _id
added to your schema at all, you may disable it using this option.
You can only use this option on subdocuments. Mongoose can't
save a document without knowing its id, so you will get an error if
you try to save a document without an _id
.
// default behavior
var schema = new Schema({ name: String });
var Page = mongoose.model('Page', schema);
var p = new Page({ name: 'mongodb.org' });
console.log(p); // { _id: '50341373e894ad16347efe01', name: 'mongodb.org' }
// disabled _id
var childSchema = new Schema({ name: String }, { _id: false });
var parentSchema = new Schema({ children: [childSchema] });
var Model = mongoose.model('Model', parentSchema);
Model.create({ children: [{ name: 'Luke' }] }, function(error, doc) {
// doc.children[0]._id will be undefined
});
option: minimize
Mongoose will, by default, "minimize" schemas by removing empty objects.
var schema = new Schema({ name: String, inventory: {} });
var Character = mongoose.model('Character', schema);
// will store `inventory` field if it is not empty
var frodo = new Character({ name: 'Frodo', inventory: { ringOfPower: 1 }});
Character.findOne({ name: 'Frodo' }, function(err, character) {
console.log(character); // { name: 'Frodo', inventory: { ringOfPower: 1 }}
});
// will not store `inventory` field if it is empty
var sam = new Character({ name: 'Sam', inventory: {}});
Character.findOne({ name: 'Sam' }, function(err, character) {
console.log(character); // { name: 'Sam' }
});
This behavior can be overridden by setting minimize
option to false
. It
will then store empty objects.
var schema = new Schema({ name: String, inventory: {} }, { minimize: false });
var Character = mongoose.model('Character', schema);
// will store `inventory` if empty
var sam = new Character({ name: 'Sam', inventory: {}});
Character.findOne({ name: 'Sam' }, function(err, character) {
console.log(character); // { name: 'Sam', inventory: {}}
});
option: read
Allows setting query#read options at the schema level, providing us a way to apply default ReadPreferences to all queries derived from a model.
var schema = new Schema({..}, { read: 'primary' }); // also aliased as 'p'
var schema = new Schema({..}, { read: 'primaryPreferred' }); // aliased as 'pp'
var schema = new Schema({..}, { read: 'secondary' }); // aliased as 's'
var schema = new Schema({..}, { read: 'secondaryPreferred' }); // aliased as 'sp'
var schema = new Schema({..}, { read: 'nearest' }); // aliased as 'n'
The alias of each pref is also permitted so instead of having to type out 'secondaryPreferred' and getting the spelling wrong, we can simply pass 'sp'.
The read option also allows us to specify tag sets. These tell the driver from which members of the replica-set it should attempt to read. Read more about tag sets here and here.
NOTE: you may also specify the driver read pref strategy option when connecting:
// pings the replset members periodically to track network latency
var options = { replset: { strategy: 'ping' }};
mongoose.connect(uri, options);
var schema = new Schema({..}, { read: ['nearest', { disk: 'ssd' }] });
mongoose.model('JellyBean', schema);
option: writeConcern
Allows setting write concern at the schema level.
const schema = new Schema({ name: String }, {
writeConcern: {
w: 'majority',
j: true,
wtimeout: 1000
}
});
option: safe
safe
is a legacy option that is similar to writeConcern
. In particular,
safe: false
is a shorthand for unacknowledged writes writeConcern: { w: 0 }
.
Use the writeConcern
option instead.
option: shardKey
The shardKey
option is used when we have a sharded MongoDB architecture.
Each sharded collection is given a shard key which must be present in all
insert/update operations. We just need to set this schema option to the same
shard key and we’ll be all set.
new Schema({ .. }, { shardKey: { tag: 1, name: 1 }})
Note that Mongoose does not send the shardcollection
command for you. You
must configure your shards yourself.
option: strict
The strict option, (enabled by default), ensures that values passed to our model constructor that were not specified in our schema do not get saved to the db.
var thingSchema = new Schema({..})
var Thing = mongoose.model('Thing', thingSchema);
var thing = new Thing({ iAmNotInTheSchema: true });
thing.save(); // iAmNotInTheSchema is not saved to the db
// set to false..
var thingSchema = new Schema({..}, { strict: false });
var thing = new Thing({ iAmNotInTheSchema: true });
thing.save(); // iAmNotInTheSchema is now saved to the db!!
This also affects the use of doc.set()
to set a property value.
var thingSchema = new Schema({..})
var Thing = mongoose.model('Thing', thingSchema);
var thing = new Thing;
thing.set('iAmNotInTheSchema', true);
thing.save(); // iAmNotInTheSchema is not saved to the db
This value can be overridden at the model instance level by passing a second boolean argument:
var Thing = mongoose.model('Thing');
var thing = new Thing(doc, true); // enables strict mode
var thing = new Thing(doc, false); // disables strict mode
The strict
option may also be set to "throw"
which will cause errors
to be produced instead of dropping the bad data.
NOTE: Any key/val set on the instance that does not exist in your schema is always ignored, regardless of schema option.
var thingSchema = new Schema({..})
var Thing = mongoose.model('Thing', thingSchema);
var thing = new Thing;
thing.iAmNotInTheSchema = true;
thing.save(); // iAmNotInTheSchema is never saved to the db
option: strictQuery
For backwards compatibility, the strict
option does not apply to
the filter
parameter for queries.
const mySchema = new Schema({ field: Number }, { strict: true });
const MyModel = mongoose.model('Test', mySchema);
// Mongoose will **not** filter out `notInSchema: 1`, despite `strict: true`
MyModel.find({ notInSchema: 1 });
The strict
option does apply to updates.
// Mongoose will strip out `notInSchema` from the update if `strict` is
// not `false`
MyModel.updateMany({}, { $set: { notInSchema: 1 } });
Mongoose has a separate strictQuery
option to toggle strict mode for
the filter
parameter to queries.
const mySchema = new Schema({ field: Number }, {
strict: true,
strictQuery: true // Turn on strict mode for query filters
});
const MyModel = mongoose.model('Test', mySchema);
// Mongoose will strip out `notInSchema: 1` because `strictQuery` is `true`
MyModel.find({ notInSchema: 1 });
option: toJSON
Exactly the same as the toObject option but only applies when
the documents toJSON
method is called.
var schema = new Schema({ name: String });
schema.path('name').get(function (v) {
return v + ' is my name';
});
schema.set('toJSON', { getters: true, virtuals: false });
var M = mongoose.model('Person', schema);
var m = new M({ name: 'Max Headroom' });
console.log(m.toObject()); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom' }
console.log(m.toJSON()); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom is my name' }
// since we know toJSON is called whenever a js object is stringified:
console.log(JSON.stringify(m)); // { "_id": "504e0cd7dd992d9be2f20b6f", "name": "Max Headroom is my name" }
To see all available toJSON/toObject
options, read this.
option: toObject
Documents have a toObject method which converts the mongoose document into a plain javascript object. This method accepts a few options. Instead of applying these options on a per-document basis we may declare the options here and have it applied to all of this schemas documents by default.
To have all virtuals show up in your console.log
output, set the
toObject
option to { getters: true }
:
var schema = new Schema({ name: String });
schema.path('name').get(function (v) {
return v + ' is my name';
});
schema.set('toObject', { getters: true });
var M = mongoose.model('Person', schema);
var m = new M({ name: 'Max Headroom' });
console.log(m); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom is my name' }
To see all available toObject
options, read this.
option: typeKey
By default, if you have an object with key 'type' in your schema, mongoose will interpret it as a type declaration.
// Mongoose interprets this as 'loc is a String'
var schema = new Schema({ loc: { type: String, coordinates: [Number] } });
However, for applications like geoJSON, the 'type' property is important. If you want to control which key mongoose uses to find type declarations, set the 'typeKey' schema option.
var schema = new Schema({
// Mongoose interpets this as 'loc is an object with 2 keys, type and coordinates'
loc: { type: String, coordinates: [Number] },
// Mongoose interprets this as 'name is a String'
name: { $type: String }
}, { typeKey: '$type' }); // A '$type' key means this object is a type declaration
option: validateBeforeSave
By default, documents are automatically validated before they are saved to
the database. This is to prevent saving an invalid document. If you want to
handle validation manually, and be able to save objects which don't pass
validation, you can set validateBeforeSave
to false.
var schema = new Schema({ name: String });
schema.set('validateBeforeSave', false);
schema.path('name').validate(function (value) {
return v != null;
});
var M = mongoose.model('Person', schema);
var m = new M({ name: null });
m.validate(function(err) {
console.log(err); // Will tell you that null is not allowed.
});
m.save(); // Succeeds despite being invalid
option: versionKey
The versionKey
is a property set on each document when first created by
Mongoose. This keys value contains the internal
revision
of the document. The versionKey
option is a string that represents the
path to use for versioning. The default is __v
. If this conflicts with
your application you can configure as such:
var schema = new Schema({ name: 'string' });
var Thing = mongoose.model('Thing', schema);
var thing = new Thing({ name: 'mongoose v3' });
thing.save(); // { __v: 0, name: 'mongoose v3' }
// customized versionKey
new Schema({..}, { versionKey: '_somethingElse' })
var Thing = mongoose.model('Thing', schema);
var thing = new Thing({ name: 'mongoose v3' });
thing.save(); // { _somethingElse: 0, name: 'mongoose v3' }
Document versioning can also be disabled by setting the versionKey
to
false
.
DO NOT disable versioning unless you know what you are doing.
new Schema({..}, { versionKey: false });
var Thing = mongoose.model('Thing', schema);
var thing = new Thing({ name: 'no versioning please' });
thing.save(); // { name: 'no versioning please' }
option: collation
Sets a default collation for every query and aggregation. Here's a beginner-friendly overview of collations.
var schema = new Schema({
name: String
}, { collation: { locale: 'en_US', strength: 1 } });
var MyModel = db.model('MyModel', schema);
MyModel.create([{ name: 'val' }, { name: 'Val' }]).
then(function() {
return MyModel.find({ name: 'val' });
}).
then(function(docs) {
// `docs` will contain both docs, because `strength: 1` means
// MongoDB will ignore case when matching.
});
option: skipVersioning
skipVersioning
allows excluding paths from versioning (i.e., the internal
revision will not be incremented even if these paths are updated). DO NOT
do this unless you know what you're doing. For subdocuments, include this
on the parent document using the fully qualified path.
new Schema({..}, { skipVersioning: { dontVersionMe: true } });
thing.dontVersionMe.push('hey');
thing.save(); // version is not incremented
option: timestamps
If set timestamps
, mongoose assigns createdAt
and updatedAt
fields to
your schema, the type assigned is Date.
By default, the name of two fields are createdAt
and updatedAt
, customize
the field name by setting timestamps.createdAt
and timestamps.updatedAt
.
var thingSchema = new Schema({..}, { timestamps: { createdAt: 'created_at' } });
var Thing = mongoose.model('Thing', thingSchema);
var thing = new Thing();
thing.save(); // `created_at` & `updatedAt` will be included
option: useNestedStrict
In mongoose 4, update()
and findOneAndUpdate()
only check the top-level
schema's strict mode setting.
var childSchema = new Schema({}, { strict: false });
var parentSchema = new Schema({ child: childSchema }, { strict: 'throw' });
var Parent = mongoose.model('Parent', parentSchema);
Parent.update({}, { 'child.name': 'Luke Skywalker' }, function(error) {
// Error because parentSchema has `strict: throw`, even though
// `childSchema` has `strict: false`
});
var update = { 'child.name': 'Luke Skywalker' };
var opts = { strict: false };
Parent.update({}, update, opts, function(error) {
// This works because passing `strict: false` to `update()` overwrites
// the parent schema.
});
If you set useNestedStrict
to true, mongoose will use the child schema's
strict
option for casting updates.
var childSchema = new Schema({}, { strict: false });
var parentSchema = new Schema({ child: childSchema },
{ strict: 'throw', useNestedStrict: true });
var Parent = mongoose.model('Parent', parentSchema);
Parent.update({}, { 'child.name': 'Luke Skywalker' }, function(error) {
// Works!
});
Pluggable
Schemas are also pluggable which allows us to package up reusable features into plugins that can be shared with the community or just between your projects.
Further Reading
To get the most out of MongoDB, you need to learn the basics of MongoDB schema design. SQL schema design (third normal form) was designed to minimize storage costs, whereas MongoDB schema design is about making common queries as fast as possible. The 6 Rules of Thumb for MongoDB Schema Design blog series is an excellent resource for learning the basic rules for making your queries fast.
Users looking to master MongoDB schema design in Node.js should look into The Little MongoDB Schema Design Book by Christian Kvalheim, the original author of the MongoDB Node.js driver. This book shows you how to implement performant schemas for a laundry list of use cases, including ecommerce, wikis, and appointment bookings.
Next Up
Now that we've covered Schemas
, let's take a look at SchemaTypes.