guide.jade

extends layout

block content
  h2 Schemas
  .important
    :markdown
      If you haven't yet done so, please take a minute to read the [quickstart](./index.html) 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](./migration.html).
  h3#definition Defining your schema
  p
    | Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB collection and defines the shape of the documents within that collection.
  :js
    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
      }
    });
  p
    em
      | If you want to add additional keys later, use the 
      a(href="./api.html#schema_Schema-add") Schema#add
      |  method.
  p 
    | Each key in our 
    code blogSchema
    |  defines a property in our documents which will be cast to its associated 
    a(href="./api.html#schematype_SchemaType") SchemaType
    |.  For example, we've defined a 
    code title
    |  which will be cast to the 
    a(href="./api.html#schema-string-js") String
    |  SchemaType and 
    code date
    |  which will be cast to a 
    code Date
    |  SchemaType.
    | Keys may also be assigned nested objects containing further key/type definitions 
    em (e.g. the `meta` property above).
  p
    | The permitted SchemaTypes are 
    ul
      li String
      li Number
      li Date
      li Buffer
      li Boolean
      li Mixed
      li ObjectId
      li Array
    | Read more about them 
    a(href="./schematypes.html") here
    | .
  p
    | Schemas not only define the structure of your document and casting of properties, they also define document 
    a(href="#methods") instance methods
    |, static 
    a(href="#statics") Model methods
    |, 
    a(href="#indexes") compound indexes
    |  and document lifecycle hooks called 
    a(href="./middleware.html") middleware
    |.

  h3#models Creating a model
  :markdown
    To use our schema definition, we need to convert our `blogSchema` into a [Model](./models.html) we can work with.
    To do so, we pass it into `mongoose.model(modelName, schema)`:

  :js
    var Blog = mongoose.model('Blog', blogSchema);
    // ready to go!

  h3#methods Instance methods
  :markdown
    Instances of `Models` are [documents](./documents.html). Documents have many of their own [built-in instance methods](./api.html#document-js). We may also define our own custom document instance methods too.

  :js
    // 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);
    }
  p
    | Now all of our 
    code animal
    |  instances have a 
    code findSimilarTypes
    |  method available to it.
  :js
    var Animal = mongoose.model('Animal', animalSchema);
    var dog = new Animal({ type: 'dog' });

    dog.findSimilarTypes(function (err, dogs) {
      console.log(dogs); // woof
    });

  .important
    :markdown
      Overwriting a default mongoose document method may lead to unpredictible results. See [this](./api.html#schema_Schema.reserved) for more details.

  h3#statics Statics
  :markdown
    Adding static methods to a `Model` is simple as well. Continuing with our `animalSchema`:

  :js
    // 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);
    });

  h3#indexes Indexes
  :markdown
    MongoDB supports [secondary indexes](https://docs.mongodb.org/manual/indexes/).
    With mongoose, we define these indexes within our `Schema` [at](./api.html#schematype_SchemaType-index) [the](./api.html#schematype_SchemaType-unique) [path](./api.html#schematype_SchemaType-sparse) [level](./api.html#schema_date_SchemaDate-expires) or the `schema` level.
    Defining indexes at the schema level is necessary when creating 
    [compound indexes](https://www.mongodb.org/display/DOCS/Indexes#Indexes-CompoundKeys).

  :js
    var animalSchema = new Schema({
      name: String,
      type: String,
      tags: { type: [String], index: true } // field level
    });

    animalSchema.index({ name: 1, type: -1 }); // schema level

  .important
    :markdown
      When your application starts up, Mongoose automatically calls `ensureIndex` for each defined index in your schema.
      While nice for development, it is recommended this behavior be disabled in production since index creation can cause a [significant performance impact](https://docs.mongodb.org/manual/core/indexes/#index-creation-operations). Disable the behavior by setting the `autoIndex` option of your schema to `false`.

  :js
    animalSchema.set('autoIndex', false);
    // or
    new Schema({..}, { autoIndex: false });

  :markdown
    See also the [Model#ensureIndexes](./api.html#model_Model.ensureIndexes) method.

  h3#virtuals Virtuals
  :markdown
    [Virtuals](./api.html#schema_Schema-virtual) 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.

  :js
    // 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 bad = new Person({
        name: { first: 'Walter', last: 'White' }
    });

  :markdown
    Suppose we want to log the full name of `bad`. We could do this manually like so:

  :js
    console.log(bad.name.first + ' ' + bad.name.last); // Walter White

  :markdown
    Or we could define a [virtual property getter](./api.html#virtualtype_VirtualType-get) on our `personSchema` so we don't need to write out this string concatenation mess each time:

  :js
    personSchema.virtual('name.full').get(function () {
      return this.name.first + ' ' + this.name.last;
    });

  :markdown
    Now, when we access our virtual "name.full" property, our getter function will be invoked and the value returned:

  :js
    console.log('%s is insane', bad.name.full); // Walter White is insane

  :markdown
    Note that if the resulting record is converted to an object or JSON, virtuals are not included by default.
    Pass `virtuals : true` to either [toObject()](./api.html#document_Document-toObject) or to toJSON() to have them returned. 

    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:

  :js
    bad.name.full = 'Breaking Bad';

  :markdown
    Mongoose lets you do this as well through its [virtual property setters](./api.html#virtualtype_VirtualType-set):

  :js
    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
    console.log(mad.name.last);  // Bad

  :markdown
    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.

  h3#options Options
  :markdown
    `Schema`s have a few configurable options which can be passed to the constructor or `set` directly:
  :js
    new Schema({..}, options);

    // or

    var schema = new Schema({..});
    schema.set(option, value);

  :markdown
    Valid options:

    - [autoIndex](#autoIndex)
    - [capped](#capped)
    - [collection](#collection)
    - [id](#id)
    - [_id](#_id)
    - [read](#read)
    - [safe](#safe)
    - [shardKey](#shardKey)
    - [strict](#strict)
    - [toJSON](#toJSON)
    - [toObject](#toObject)
    - [validateBeforeSave](#validateBeforeSave)
    - [versionKey](#versionKey)

  h4#autoIndex option: autoIndex
  :markdown
    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](./api.html#model_Model.ensureIndexes) method on your model.
  :js
    var schema = new Schema({..}, { autoIndex: false });
    var Clock = mongoose.model('Clock', schema);
    Clock.ensureIndexes(callback);

  h4#bufferCommands option: bufferCommands
  :markdown
    When running with the drivers `autoReconnect` option disabled and connected to a single `mongod` (non-replica-set), mongoose buffers commands when the connection goes down until you manually reconnect. To disable mongoose buffering under these conditions, set this option to `false`.
  :js
    var schema = new Schema({..}, { bufferCommands: false });

  h4#capped option: capped
  :markdown
    Mongoose supports MongoDBs [capped](https://www.mongodb.org/display/DOCS/Capped+Collections) collections. To specify the underlying MongoDB collection be `capped`, set the `capped` option to the maximum size of the collection in [bytes](https://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-size.).
  :js
    new Schema({..}, { capped: 1024 });
  :markdown
    The `capped` option may also be set to an object if you want to pass additional options like [max](https://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-max) or [autoIndexId](https://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-autoIndexId). In this case you must explicitly pass the `size` option which is required.
  :js
    new Schema({..}, { capped: { size: 1024, max: 1000, autoIndexId: true } });

  h4#collection option: collection
  :markdown
    Mongoose by default produces a collection name by passing the model name to the [utils.toCollectionName](./api.html#utils_exports.toCollectionName) method. This method pluralizes the name. Set this option if you need a different name for your collection.
  :js
    var dataSchema = new Schema({..}, { collection: 'data' });

  h4#id option: id
  :markdown
    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.
  :js
    // 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

  h4#_id option: _id
  :markdown
    Mongoose assigns each of your schemas an `_id` field by default if one is not passed into the [Schema](/docs/api.html#schema-js) constructor. The type assiged is an [ObjectId](/docs/api.html#schema_Schema.Types) 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 `_id` created by Mongoose (parent documents will still have an `_id` created by MongoDB when inserted). _Passing the option later using `Schema.set('_id', false)` will not work. See issue [#1512](https://github.com/LearnBoost/mongoose/issues/1512)._
  :js
    // 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 schema = new Schema({ name: String }, { _id: false });

    // Don't set _id to false after schema construction as in
    // var schema = new Schema({ name: String });
    // schema.set('_id', false);

    var Page = mongoose.model('Page', schema);
    var p = new Page({ name: 'mongodb.org' });
    console.log(p); // { name: 'mongodb.org' }

    // MongoDB will create the _id when inserted
    p.save(function (err) {
      if (err) return handleError(err);
      Page.findById(p, function (err, doc) {
        if (err) return handleError(err);
        console.log(doc); // { name: 'mongodb.org', _id: '50341373e894ad16347efe12' }
      })
    })

  :markdown
    Note that currently you must disable the `_id` 

  h4#read option: read
  :markdown
    Allows setting [query#read](/docs/api.html#query_Query-read) options at the schema level, providing us a way to apply default [ReadPreferences](https://docs.mongodb.org/manual/applications/replication/#replica-set-read-preference) to all queries derived from a model.

  :js
    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'

  :markdown
    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](https://github.com/mongodb/node-mongodb-native/) from which members of the replica-set it should attempt to read. Read more about tag sets [here](https://docs.mongodb.org/manual/applications/replication/#tag-sets) and [here](https://mongodb.github.com/node-mongodb-native/driver-articles/anintroductionto1_1and2_2.html#read-preferences).

    _NOTE: you may also specify the driver read pref [strategy](https://mongodb.github.com/node-mongodb-native/api-generated/replset.html?highlight=strategy) option when connecting:_

  :js
    // 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);

  h4#safe option: safe
  :markdown
    This option is passed to MongoDB with all operations and specifies if errors should be returned to our callbacks as well as tune write behavior.

  :js
    var safe = true;
    new Schema({ .. }, { safe: safe });

  :markdown
    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.
    
    NOTE: In 3.6.x, you also need to turn [versioning](#versionKey) off. In 3.7.x and above, versioning will **automatically be disabled** when `safe` is set to `false`

    **NOTE: this setting overrides any setting specified by passing db options while [creating a connection](/docs/api.html#index_Mongoose-createConnection).

    There are other write concerns like `{ w: "majority" }` too. See the MongoDB [docs](https://www.mongodb.org/display/DOCS/getLastError+Command) for more details.

  :js
    var safe = { w: "majority", wtimeout: 10000 };
    new Schema({ .. }, { safe: safe });

  h4#shardKey option: shardKey
  :markdown
    The `shardKey` option is used when we have a [sharded MongoDB architecture](https://www.mongodb.org/display/DOCS/Sharding+Introduction). 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.

  :js
    new Schema({ .. }, { shardKey: { tag: 1, name: 1 }})

  :markdown
    _Note that Mongoose does not send the `shardcollection` command for you. You must configure your shards yourself._

  h4#strict option: strict
  :markdown
    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.

  :js
    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!!

  :markdown
    This also affects the use of `doc.set()` to set a property value.

  :js
    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

  :markdown
    This value can be overridden at the model instance level by passing a second boolean argument:

  :js
    var Thing = mongoose.model('Thing');
    var thing = new Thing(doc, true);  // enables strict mode
    var thing = new Thing(doc, false); // disables strict mode

  :markdown
    The `strict` option may also be set to `"throw"` which will cause errors to be produced instead of dropping the bad data.

  :markdown
    _NOTE: do not set to false unless you have good reason._

    _NOTE: in mongoose v2 the default was false._

    _NOTE: Any key/val set on the instance that does not exist in your schema is always ignored, regardless of schema option._

  :js
    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

  h4#toJSON option: toJSON
  :markdown
    Exactly the same as the [toObject](#toObject) option but only applies when the documents `toJSON` method is called.
  :js
    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" }

  :markdown
    To see all available `toJSON/toObject` options, read [this](/docs/api.html#document_Document-toObject).

  h4#toObject option: toObject
  :markdown
    Documents have a [toObject](/docs/api.html#document_Document-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 }`:

  :js
    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' }

  :markdown
    To see all available `toObject` options, read [this](/docs/api.html#document_Document-toObject).
    
  h4#validateBeforeSave option: validateBeforeSave
  :markdown
    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.

  :js
    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

  h4#versionKey option: versionKey
  :markdown
    The `versionKey` is a property set on each document when first created by Mongoose. This keys value contains the internal [revision](https://aaronheckmann.tumblr.com/post/48943525537/mongoose-v3-part-1-versioning) 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:
  :js
    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' }

  :markdown
    Document versioning can also be disabled by setting the `versionKey` to false. _DO NOT disable versioning unless you [know what you are doing](https://aaronheckmann.tumblr.com/post/48943525537/mongoose-v3-part-1-versioning)._
  :js
    new Schema({..}, { versionKey: false });
    var Thing = mongoose.model('Thing', schema);
    var thing = new Thing({ name: 'no versioning please' });
    thing.save(); // { name: 'no versioning please' }

  h3#plugins Pluggable
  p
    | Schemas are also 
    a(href="./plugins.html") pluggable
    |  which allows us to package up reusable features into 
    a(href="https://plugins.mongoosejs.com") plugins
    |  that can be shared with the community or just between your projects.

  h3#next Next Up
  :markdown
    Now that we've covered `Schemas`, let's take a look at [SchemaTypes](/docs/schematypes.html).

script.
document.body.className = 'load';
include includes/googleanalytics