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 2.x to 3.x please take a moment to read the migration guide.
This page covers Schema
definition, plugins, instance methods, statics, indexes, virtuals and options. Let's start with Schema
definition.
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 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 blogSchema
defines a property in our documents which will be cast to its associated SchemaType. For example, we've defined a title
which will be cast to the String SchemaType and date
which will be cast to a Date
SchemaType.
Keys may also be assigned nested objects containing further key/type definitions (e.g. the `meta` property above).
The permitted SchemaTypes are
- String
- Number
- Date
- Buffer
- Boolean
- Mixed
- ObjectId
- Array
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.
Pluggable
Schemas are pluggable which allows us to package up reusable features into plugins that can be shared with the community or just between your projects.
Instance methods
Models are just fancy constructor
functions. As such they can have prototype methods inherited by their instances. In the case of Mongoose, instances are documents.
Defining an instance method is easy.
var animalSchema = new Schema({ name: String, type: String });
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 it.
var Animal = mongoose.model('Animal', animalSchema);
var dog = new Animal({ type: 'dog' })
dog.findSimilarTypes(function (err, dogs) {
console.log(dogs) // woof
})
Statics
Adding static constructor methods to Models is simple as well. Continuing with our animalSchema
:
animalSchema.statics.findByName = function (name, cb) {
this.find({ name: new RegExp(name, 'i'), cb);
}
var Animal = mongoose.model('Animal', animalSchema);
Animal.findByName('fido', function (err, animals) {
console.log(animals);
})
Indexes
Indexes can be defined at the path level or the schema
level. Defining indexes at the schema level is necessary when defining compound indexes.
animalSchema.index({ name: 1, type: -1 });
When your application starts up, Mongoose automatically calls ensureIndex
for each defined index. This behavior can be disabled by setting the autoIndex
option of your schema to false.
animalSchema.set('autoIndex', false)
// or
new Schema({..}, { autoIndex: false })
See also the Model#ensureIndexes
method.
Virtuals
Virtual attributes are attributes that are convenient to have around but that do not get persisted to MongoDB.
var personSchema = new Schema({
name: {
first: String,
last: String
}
});
var Person = mongoose.model('Person', personSchema);
var bad = new Person({
name: { first: 'Walter', last: 'White' }
});
Suppose we want to log the full name of bad
. We could do this manually like so:
console.log(bad.name.first + ' ' + bad.name.last); // Walter White
Or we could add a virtual
attribute getter to our personSchema
so we don't need to write out this string concatenation mess each time:
personSchema.virtual('name.full').get(function () {
return this.name.first + ' ' + this.name.last;
})
Now, when we access our virtual full name property, our getter function will be invoked and the value returned:
console.log('%s is insane', bad.name.full) // Walter White is insane
It would also be nice to be able to set this.name.first
and this.name.last
by setting this.name.full
. For example, if we wanted to change bad
's name.first
and name.last
to 'Breaking' and 'Bad' respectively, it'd be nice to just:
bad.name.full = 'Breaking Bad';
Mongoose let's you do this as well through its virtual attribute setters:
personSchema.virtual('name.full').set(function (name) {
var split = name.split(' ');
this.name.first = split[0];
this.name.last = split[1];
})
...
mad.name.full = 'Breaking Bad';
console.log(mad.name.first) // Breaking
If you need attributes that you can get and set but that are not themselves persisted to MongoDB, virtual attributes is the Mongoose feature for you.
Options
Schema
s 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:
option: autoIndex
At application startup, Mongoose sends an ensureIndex
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 = db.model('Clock', schema);
Clock.ensureIndexes(callback);
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: 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 = db.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 = db.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 assiged is an ObjectId to coincide with MongoDBs default behavior. If you don't want an _id
added to your schema at all, you may disable it using this option.
Pass this option during schema construction to prevent documents from getting an auto _id
created.
// default behavior
var schema = new Schema({ name: String });
var Page = db.model('Page', schema);
var p = new Page({ name: 'mongodb.org' });
console.log(p); // { _id: '50341373e894ad16347efe01', name: 'mongodb.org' }
// disabled _id
var schema = new Schema({ name: String }, { _id: false });
var Page = db.model('Page', schema);
var p = new Page({ name: 'mongodb.org' });
console.log(p); // { name: 'mongodb.org' }
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 'pp'.
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: if you specify the read pref 'nearest', you must also pass the strategy option when connecting or your reads will not behave predictably:
// pings the replset members periodically to track network latency
// now `nearest` works as intended
var options = { replset: { strategy: 'ping' }};
mongoose.connect(uri, options);
var schema = new Schema({..}, { read: ['n', { disk: 'ssd' }] });
mongoose.model('JellyBean', schema);
option: safe
This option is passed to MongoDB with all operations and let's us specify if errors should be returned to our callbacks as well as tune write behavior.
var safe = true;
new Schema({ .. }, { safe: safe })
By default this is set to true
for all schemas which guarentees that any occurring error gets passed back to our callback.
By setting safe
to something else like { j: 1, w: 2, wtimeout: 10000 }
we can guarantee the write was committed to the MongoDB journal (j: 1), at least 2 replicas (w: 2), and that the write will timeout if it takes longer than 10 seconds (wtimeout: 10000). Errors will still be passed to our callback.
There are other write concerns like { w: "majority" }
too. See the MongoDB docs for more details.
var safe = { w: "majority", wtimeout: 10000 };
new Schema({ .. }, { safe: safe })
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 added to our model instance that were not specified in our schema do not get saved to the db. NOTE: do not set to false unless you have good reason.
var thingSchema = new Schema({..})
var Thing = db.model('Thing', schemaSchema);
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 value can be overridden at the model instance level by passing a second boolean argument:
var Thing = db.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 ignoring the bad data.
NOTE: in mongoose v2 the default was false.
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 });
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" }
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.
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.toObject()); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom is my name' }
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 name of this document property is configurable. The default is __v
. If this conflicts with your application you can configure as such:
var schema = new Schema({ name: 'string' });
var Thing = db.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 = db.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 = db.model('Thing', schema);
var thing = new Thing({ name: 'no versioning please' });
thing.save(); // { name: 'no versioning please' }
Next Up
Now that we've covered Schemas
, let's take a look at SchemaTypes.