guide.pug

extends layout

append style
  link(rel="stylesheet", href="/docs/css/inlinecpc.css")
  script(type="text/javascript" src="/docs/js/native.js")

block content
  <a class="edit-docs-link" href="#{editLink}">
    <img src="/docs/images/pencil.svg" />
  </a>

  :markdown
    ## Schemas

    <script>
      _native.init("CK7DT53U",{
        targetClass: 'native-inline'
      });
    </script>

    <div class="native-inline">
      <a href="#native_link#"><span class="sponsor">Sponsor</span> #native_company# — #native_desc#</a>
    </div>

  .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 4.x to 5.x please take a moment to read the [migration guide](/docs/migrating_to_5.html).
  :markdown
    <ul class="toc">
      <li><a href="#definition">Defining your schema</a></li>
      <li><a href="#models">Creating a model</a></li>
      <li><a href="#_id">Ids</a></li>
      <li><a href="#methods">Instance methods</a></li>
      <li><a href="#statics">Statics</a></li>
      <li><a href="#query-helpers">Query Helpers</a></li>
      <li><a href="#indexes">Indexes</a></li>
      <li><a href="#virtuals">Virtuals</a></li>
      <li><a href="#aliases">Aliases</a></li>
      <li><a href="#options">Options</a></li>
      <li><a href="#es6-classes">With ES6 Classes</a></li>
      <li><a href="#plugins">Pluggable</a></li>
      <li><a href="#further-reading">Further Reading</a></li>
    </ul>

    <h3 id="definition"><a href="#definition">Defining your schema</a></h3>

    Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB
    collection and defines the shape of the documents within that collection.

    ```javascript
      var mongoose = require('mongoose');
      var Schema = mongoose.Schema;

      var blogSchema = new Schema({
        title:  String, // String is shorthand for {type: 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](./api.html#schema_Schema-add) method.

    Each key in our code `blogSchema` defines a property in our documents which
    will be cast to its associated [SchemaType](./api.html#schematype_SchemaType).
    For example, we've defined a property `title` which will be cast to the
    [String](./api.html#schema-string-js) SchemaType and property `date`
    which will be cast to a `Date` SchemaType.

    Notice above that if a property only requires a type, it can be specified using
    a shorthand notation (contrast the `title` property above with the `date`
    property).
    
    Keys may also be assigned nested objects containing further key/type definitions
    like the `meta` property above.  This will happen whenever a key's value is a POJO
    that doesn't have a `type` property.
    
    In these cases, Mongoose only creates actual schema paths for leaves
    in the tree. (like `meta.votes` and `meta.favs` above),
    and the branches do not have actual paths.  A side-effect of this is that `meta`
    above cannot have its own validation.  If validation is needed up the tree, a path
    needs to be created up the tree - see the [Subdocuments](./subdocs.html) section
    for more information on how to do this.  Also read the [Mixed](./schematypes.html)
    subsection of the SchemaTypes guide for some gotchas.

    The permitted SchemaTypes are:

    * [String](./schematypes.html#strings)
    * [Number](./schematypes.html#numbers)
    * [Date](./schematypes.html#dates)
    * [Buffer](./schematypes.html#buffers)
    * [Boolean](./schematypes.html#booleans)
    * [Mixed](./schematypes.html#mixed)
    * [ObjectId](./schematypes.html#objectids)
    * [Array](./schematypes.html#arrays)
    * [Decimal128](./api.html#mongoose_Mongoose-Decimal128)
    * [Map](./schematypes.html#maps)

    Read more about [SchemaTypes here](./schematypes.html).

    Schemas not only define the structure of your document and casting of
    properties, they also define document [instance methods](#methods),
    [static Model methods](#statics), [compound indexes](#indexes),
    and document lifecycle hooks called [middleware](./middleware.html).

    <h3 id="models"><a href="#models">Creating a model</a></h3>

    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)`:

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

    <h3 id="_id"><a href="#_id">Ids</a></h3>

    By default, Mongoose adds an `_id` property to your schemas.

    ```javascript
    const schema = new Schema();

    schema.path('_id'); // ObjectId { ... }
    ```

    When you create a new document with the automatically added
    `_id` property, Mongoose creates a new [`_id` of type ObjectId](https://masteringjs.io/tutorials/mongoose/objectid)
    to your document.

    ```javascript
    const Model = mongoose.model('Test', schema);

    const doc = new Model();
    doc._id instanceof mongoose.Types.ObjectId; // true
    ```

    You can also overwrite Mongoose's default `_id` with your
    own `_id`. Just be careful: Mongoose will refuse to save a
    document that doesn't have an `_id`, so you're responsible
    for setting `_id` if you define your own `_id` path.

    ```javascript
    const schema = new Schema({ _id: Number });
    const Model = mongoose.model('Test', schema);

    const doc = new Model();
    await doc.save(); // Throws "document must have an _id before saving"
    
    doc._id = 1;
    await doc.save(); // works
    ```

    <h3 id="methods"><a href="#methods">Instance methods</a></h3>

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

    ```javascript
      // 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 mongoose.model('Animal').find({ type: this.type }, cb);
      };
    ```

    Now all of our `animal` instances have a `findSimilarTypes` method available
    to them.

    ```javascript
      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](./api.html#schema_Schema.reserved) for more details.
    * The example above uses the `Schema.methods` object directly to save an instance method. You can also use the `Schema.method()` helper as described [here](./api.html#schema_Schema-method).
    * Do **not** declare methods using ES6 arrow functions (`=>`). Arrow functions [explicitly prevent binding `this`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#No_binding_of_this), so your method will **not** have access to the document and the above examples will not work.

    <h3 id="statics"><a href="#statics">Statics</a></h3>

    You can also add static functions to your model. There are two equivalent
    ways to add a static:

    - Add a function property to `schema.statics`
    - Call the [`Schema#static()` function](/docs/api.html#schema_Schema-static)

    ```javascript
      // Assign a function to the "statics" object of our animalSchema
      animalSchema.statics.findByName = function(name) {
        return this.find({ name: new RegExp(name, 'i') });
      };
      // Or, equivalently, you can call `animalSchema.static()`.
      animalSchema.static('findByBreed', function(breed) {
        return this.find({ breed });
      });

      const Animal = mongoose.model('Animal', animalSchema);
      let animals = await Animal.findByName('fido');
      animals = animals.concat(await Animal.findByBreed('Poodle'));
    ```

    Do **not** declare statics using ES6 arrow functions (`=>`). Arrow functions [explicitly prevent binding `this`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#No_binding_of_this), so the above examples will not work because of the value of `this`.

    <h3 id="query-helpers"><a href="#query-helpers">Query Helpers</a></h3>

    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](./queries.html).

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

    <h3 id="indexes"><a href="#indexes">Indexes</a></h3>

    MongoDB supports [secondary indexes](http://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://docs.mongodb.com/manual/core/index-compound/).

    ```javascript
      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`](https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#db.collection.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](https://docs.mongodb.com/manual/core/index-creation/#index-build-impact-on-database-performance).
    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`.

    ```javascript
      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.

    ```javascript
      // 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](./api.html#model_Model.ensureIndexes) method.

    <h3 id="virtuals"><a href="#virtuals">Virtuals</a></h3>

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

    ```javascript
      // 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:

    ```javascript
    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](https://www.npmjs.com/package/diacritics)? A
    [virtual property getter](./api.html#virtualtype_VirtualType-get) lets you
    define a `fullName` property that won't get persisted to MongoDB.

    ```javascript
    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:

    ```javascript
    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()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
    on a Mongoose document, because [`JSON.stringify()` calls `toJSON()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description).
    Pass `{ virtuals: true }` to either
    [`toObject()`](./api.html#document_Document-toObject) or [`toJSON()`](./api.html#document_Document-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.

    ```javascript
    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.

    <h5 id="aliases"><a href="#aliases">Aliases</a></h5>

    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.

    ```javascript
    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](/docs/subdocs.html), but you can also declare
    nested path aliases inline as long as you use the full nested path
    `nested.myProp` as the alias.

    ```javascript
    [require:gh-6671]
    ```

    <h3 id="options"><a href="#options">Options</a></h3>

    Schemas have a few configurable options which can be passed to the
    constructor or to the `set` method:

    ```javascript
    new Schema({..}, options);

    // or

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

    Valid options:

    - [autoIndex](#autoIndex)
    - [autoCreate](#autoCreate)
    - [bufferCommands](#bufferCommands)
    - [capped](#capped)
    - [collection](#collection)
    - [id](#id)
    - [_id](#_id)
    - [minimize](#minimize)
    - [read](#read)
    - [writeConcern](#writeConcern)
    - [shardKey](#shardKey)
    - [strict](#strict)
    - [strictQuery](#strictQuery)
    - [toJSON](#toJSON)
    - [toObject](#toObject)
    - [typeKey](#typeKey)
    - [useNestedStrict](#useNestedStrict)
    - [validateBeforeSave](#validateBeforeSave)
    - [versionKey](#versionKey)
    - [collation](#collation)
    - [selectPopulatedPaths](#selectPopulatedPaths)
    - [skipVersioning](#skipVersioning)
    - [timestamps](#timestamps)
    - [storeSubdocValidationError](#storeSubdocValidationError)

    <h3 id="autoIndex"><a href="#autoIndex">option: autoIndex</a></h3>

    By default, Mongoose's [`init()` function](/docs/api.html#model_Model.init)
    creates all the indexes defined in your model's schema by calling
    [`Model.createIndexes()`](/docs/api.html#model_Model.createIndexes)
    after you successfully connect to MongoDB. Creating indexes automatically is
    great for development and test environments. But index builds can also create
    significant load on your production database. If you want to manage indexes
    carefully in production, you can set `autoIndex` to false.

    ```javascript
    const schema = new Schema({..}, { autoIndex: false });
    const Clock = mongoose.model('Clock', schema);
    Clock.ensureIndexes(callback);
    ```

    The `autoIndex` option is set to `true` by default. You can change this
    default by setting [`mongoose.set('autoIndex', false);`](/docs/api/mongoose.html#mongoose_Mongoose-set)

    <h3 id="autoCreate"><a href="#autoCreate">option: autoCreate</a></h3>

    Before Mongoose builds indexes, it calls `Model.createCollection()`
    to create the underlying collection in MongoDB if `autoCreate` is set to true.
    Calling `createCollection()`
    sets the [collection's default collation](https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations)
    based on the [collation option](#collation) and establishes the collection as
    a capped collection if you set the [`capped` schema option](#capped). Like
    `autoIndex`, setting `autoCreate` to true is helpful for development and
    test environments.
    
    Unfortunately, `createCollection()` cannot change an existing collection.
    For example, if you add `capped: 1024` to your schema and the existing
    collection is not capped, `createCollection()` will throw an error.
    Generally, `autoCreate` should be `false` for production environments.

    ```javascript
    const schema = new Schema({..}, { autoCreate: true, capped: 1024 });
    const Clock = mongoose.model('Clock', schema);
    // Mongoose will create the capped collection for you.
    ```

    Unlike `autoIndex`, `autoCreate` is `false` by default. You can change this
    default by setting [`mongoose.set('autoCreate', true);`](/docs/api/mongoose.html#mongoose_Mongoose-set)

    <h3 id="bufferCommands"><a href="#bufferCommands">option: bufferCommands</a></h3>

    By default, mongoose buffers commands when the connection goes down until
    the driver manages to reconnect. To disable buffering, set `bufferCommands`
    to false.

    ```javascript
    var schema = new Schema({..}, { bufferCommands: false });
    ```

    The schema `bufferCommands` option overrides the global `bufferCommands` option.

    ```javascript
    mongoose.set('bufferCommands', true);
    // Schema option below overrides the above, if the schema option is set.
    var schema = new Schema({..}, { bufferCommands: false });
    ```

    <h3 id="capped"><a href="#capped">option: capped</a></h3>

    Mongoose supports MongoDBs [capped](http://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](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-size.).

    ```javascript
    new Schema({..}, { capped: 1024 });
    ```

    The `capped` option may also be set to an object if you want to pass
    additional options like [max](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-max)
    or [autoIndexId](http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-autoIndexId).
    In this case you must explicitly pass the `size` option, which is required.

    ```javascript
    new Schema({..}, { capped: { size: 1024, max: 1000, autoIndexId: true } });
    ```

    <h3 id="collection"><a href="#collection">option: collection</a></h3>

    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.

    ```javascript
    var dataSchema = new Schema({..}, { collection: 'data' });
    ```

    <h3 id="id"><a href="#id">option: id</a></h3>

    Mongoose assigns each of your schemas an `id` virtual getter by default
    which returns the document's `_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 by passing this option at schema construction time.

    ```javascript
    // 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
    ```

    <h3 id="_id"><a href="#_id">option: _id</a></h3>

    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 assigned is an [ObjectId](/docs/api.html#schema_Schema.Types)
    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`.

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

    <h3 id="minimize"><a href="#minimize">option: minimize</a></h3>

    Mongoose will, by default, "minimize" schemas by removing empty objects.

    ```javascript
    const schema = new Schema({ name: String, inventory: {} });
    const Character = mongoose.model('Character', schema);

    // will store `inventory` field if it is not empty
    const frodo = new Character({ name: 'Frodo', inventory: { ringOfPower: 1 }});
    await frodo.save();
    let doc = await Character.findOne({ name: 'Frodo' }).lean();
    doc.inventory; // { ringOfPower: 1 }

    // will not store `inventory` field if it is empty
    const sam = new Character({ name: 'Sam', inventory: {}});
    await sam.save();
    doc = await Character.findOne({ name: 'Sam' }).lean();
    doc.inventory; // undefined
    ```

    This behavior can be overridden by setting `minimize` option to `false`. It
    will then store empty objects.

    ```javascript
    const schema = new Schema({ name: String, inventory: {} }, { minimize: false });
    const Character = mongoose.model('Character', schema);

    // will store `inventory` if empty
    const sam = new Character({ name: 'Sam', inventory: {} });
    await sam.save();
    doc = await Character.findOne({ name: 'Sam' }).lean();
    doc.inventory; // {}
    ```

    To check whether an object is empty, you can use the `$isEmpty()` helper:

    ```javascript
    const sam = new Character({ name: 'Sam', inventory: {} });
    sam.$isEmpty('inventory'); // true

    sam.inventory.barrowBlade = 1;
    sam.$isEmpty('inventory'); // false
    ```

    <h3 id="read"><a href="#read">option: read</a></h3>

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

    ```javascript
    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](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](http://docs.mongodb.org/manual/applications/replication/#tag-sets) and
    [here](http://mongodb.github.com/node-mongodb-native/driver-articles/anintroductionto1_1and2_2.html#read-preferences).

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

    ```javascript
    // 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);
    ```

    <h3 id="writeConcern"><a href="#writeConcern">option: writeConcern</a></h3>

    Allows setting [write concern](https://docs.mongodb.com/manual/reference/write-concern/)
    at the schema level.

    ```javascript
    const schema = new Schema({ name: String }, {
      writeConcern: {
        w: 'majority',
        j: true,
        wtimeout: 1000
      }
    });
    ```

    <h3 id="shardKey"><a href="#shardKey">option: shardKey</a></h3>

    The `shardKey` option is used when we have a [sharded MongoDB architecture](http://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.

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

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

    <h3 id="strict"><a href="#strict">option: strict</a></h3>

    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.

    ```javascript
    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.

    ```javascript
    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:

    ```javascript
    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._

    ```javascript
    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
    ```

    <h3 id="strictQuery"><a href="#strictQuery">option: strictQuery</a></h3>

    For backwards compatibility, the `strict` option does **not** apply to
    the `filter` parameter for queries.

    ```javascript
    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.

    ```javascript
    // 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.

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

    <h3 id="toJSON"><a href="#toJSON">option: toJSON</a></h3>

    Exactly the same as the [toObject](#toObject) option but only applies when
    the document's `toJSON` method is called.

    ```javascript
    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](/docs/api.html#document_Document-toObject).

    <h3 id="toObject"><a href="#toObject">option: toObject</a></h3>

    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 at the schema level and have
    them applied to all of the schema's documents by default.

    To have all virtuals show up in your `console.log` output, set the
    `toObject` option to `{ getters: true }`:

    ```javascript
    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](/docs/api.html#document_Document-toObject).

    <h3 id="typeKey"><a href="#typeKey">option: typeKey</a></h3>

    By default, if you have an object with key 'type' in your schema, mongoose
    will interpret it as a type declaration.

    ```javascript
    // Mongoose interprets this as 'loc is a String'
    var schema = new Schema({ loc: { type: String, coordinates: [Number] } });
    ```

    However, for applications like [geoJSON](http://docs.mongodb.org/manual/reference/geojson/),
    the 'type' property is important. If you want to control which key mongoose
    uses to find type declarations, set the 'typeKey' schema option.

    ```javascript
    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
    ```

    <h3 id="validateBeforeSave"><a href="#validateBeforeSave">option: validateBeforeSave</a></h3>

    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.

    ```javascript
    var schema = new Schema({ name: String });
    schema.set('validateBeforeSave', false);
    schema.path('name').validate(function (value) {
        return value != 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
    ```

    <h3 id="versionKey"><a href="#versionKey">option: versionKey</a></h3>

    The `versionKey` is a property set on each document when first created by
    Mongoose. This keys value contains the internal
    [revision](http://aaronheckmann.blogspot.com/2012/06/mongoose-v3-part-1-versioning.html)
    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:

    ```javascript
    const schema = new Schema({ name: 'string' });
    const Thing = mongoose.model('Thing', schema);
    const thing = new Thing({ name: 'mongoose v3' });
    await thing.save(); // { __v: 0, name: 'mongoose v3' }

    // customized versionKey
    new Schema({..}, { versionKey: '_somethingElse' })
    const Thing = mongoose.model('Thing', schema);
    const thing = new Thing({ name: 'mongoose v3' });
    thing.save(); // { _somethingElse: 0, name: 'mongoose v3' }
    ```

    Note that Mongoose versioning is **not** a full [optimistic concurrency](https://en.wikipedia.org/wiki/Optimistic_concurrency_control)
    solution. Use [mongoose-update-if-current](https://github.com/eoin-obrien/mongoose-update-if-current)
    for OCC support. Mongoose versioning only operates on arrays:

    ```javascript
    // 2 copies of the same document
    const doc1 = await Model.findOne({ _id });
    const doc2 = await Model.findOne({ _id });

    // Delete first 3 comments from `doc1`
    doc1.comments.splice(0, 3);
    await doc1.save();

    // The below `save()` will throw a VersionError, because you're trying to
    // modify the comment at index 1, and the above `splice()` removed that
    // comment.
    doc2.set('comments.1.body', 'new comment');
    await doc2.save();
    ```

    Document versioning can also be disabled by setting the `versionKey` to
    `false`.
    _DO NOT disable versioning unless you [know what you are doing](http://aaronheckmann.blogspot.com/2012/06/mongoose-v3-part-1-versioning.html)._

    ```javascript
    new Schema({..}, { versionKey: false });
    const Thing = mongoose.model('Thing', schema);
    const thing = new Thing({ name: 'no versioning please' });
    thing.save(); // { name: 'no versioning please' }
    ```

    Mongoose _only_ updates the version key when you use [`save()`](/docs/api.html#document_Document-save).
    If you use `update()`, `findOneAndUpdate()`, etc. Mongoose will **not**
    update the version key. As a workaround, you can use the below middleware.

    ```javascript
    schema.pre('findOneAndUpdate', function() {
      const update = this.getUpdate();
      if (update.__v != null) {
        delete update.__v;
      }
      const keys = ['$set', '$setOnInsert'];
      for (const key of keys) {
        if (update[key] != null && update[key].__v != null) {
          delete update[key].__v;
          if (Object.keys(update[key]).length === 0) {
            delete update[key];
          }
        }
      }
      update.$inc = update.$inc || {};
      update.$inc.__v = 1;
    });
    ```

    <h3 id="collation"><a href="#collation">option: collation</a></h3>

    Sets a default [collation](https://docs.mongodb.com/manual/reference/collation/)
    for every query and aggregation. [Here's a beginner-friendly overview of collations](http://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations).

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

    <h3 id="skipVersioning"><a href="#skipVersioning">option: skipVersioning</a></h3>

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

    ```javascript
    new Schema({..}, { skipVersioning: { dontVersionMe: true } });
    thing.dontVersionMe.push('hey');
    thing.save(); // version is not incremented
    ```

    <h3 id="timestamps"><a href="#timestamps">option: timestamps</a></h3>

    The `timestamps` option tells mongoose to assign `createdAt` and `updatedAt` fields
    to your schema. The type assigned is [Date](./api.html#schema-date-js).

    By default, the names of the fields are `createdAt` and `updatedAt`. Customize
    the field names by setting `timestamps.createdAt` and `timestamps.updatedAt`.

    ```javascript
    const thingSchema = new Schema({..}, { timestamps: { createdAt: 'created_at' } });
    const Thing = mongoose.model('Thing', thingSchema);
    const thing = new Thing();
    await thing.save(); // `created_at` & `updatedAt` will be included

    // With updates, Mongoose will add `updatedAt` to `$set`
    await Thing.updateOne({}, { $set: { name: 'Test' } });

    // If you set upsert: true, Mongoose will add `created_at` to `$setOnInsert` as well
    await Thing.findOneAndUpdate({}, { $set: { name: 'Test2' } });

    // Mongoose also adds timestamps to bulkWrite() operations
    // See https://mongoosejs.com/docs/api.html#model_Model.bulkWrite
    await Thing.bulkWrite([
      insertOne: {
        document: {
          name: 'Jean-Luc Picard',
          ship: 'USS Stargazer'
          // Mongoose will add `created_at` and `updatedAt`
        }
      },
      updateOne: {
        filter: { name: 'Jean-Luc Picard' },
        update: {
          $set: {
            ship: 'USS Enterprise'
            // Mongoose will add `updatedAt`
          }
        }
      }
    ]);
    ```

    By default, Mongoose uses `new Date()` to get the current time.
    If you want to overwrite the function
    Mongoose uses to get the current time, you can set the
    `timestamps.currentTime` option. Mongoose will call the
    `timestamps.currentTime` function whenever it needs to get
    the current time.

    ```javascript
    const schema = Schema({
      createdAt: Number,
      updatedAt: Number,
      name: String
    }, {
      // Make Mongoose use Unix time (seconds since Jan 1, 1970)
      timestamps: { currentTime: () => Math.floor(Date.now() / 1000) }
    });
    ```

    <h3 id="useNestedStrict"><a href="#useNestedStrict">option: useNestedStrict</a></h3>

    Write operations like `update()`, `updateOne()`, `updateMany()`,
    and `findOneAndUpdate()` only check the top-level
    schema's strict mode setting.

    ```javascript
    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.

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

    <h3 id="selectPopulatedPaths">
      <a href="#selectPopulatedPaths">
        option: selectPopulatedPaths
      </a>
    </h3>

    By default, Mongoose will automatically `select()` any populated paths for
    you, unless you explicitly exclude them.

    ```javascript
    const bookSchema = new Schema({
      title: 'String',
      author: { type: 'ObjectId', ref: 'Person' }
    });
    const Book = mongoose.model('Book', bookSchema);

    // By default, Mongoose will add `author` to the below `select()`.
    await Book.find().select('title').populate('author');

    // In other words, the below query is equivalent to the above
    await Book.find().select('title author').populate('author');
    ```

    To opt out of selecting populated fields by default, set `selectPopulatedPaths`
    to `false` in your schema.

    ```javascript
    const bookSchema = new Schema({
      title: 'String',
      author: { type: 'ObjectId', ref: 'Person' }
    }, { selectPopulatedPaths: false });
    const Book = mongoose.model('Book', bookSchema);

    // Because `selectPopulatedPaths` is false, the below doc will **not**
    // contain an `author` property.
    const doc = await Book.findOne().select('title').populate('author');
    ```

    <h3 id="storeSubdocValidationError">
      <a href="#storeSubdocValidationError">
        option: storeSubdocValidationError
      </a>
    </h3>

    For legacy reasons, when there is a validation error in subpath of a
    single nested schema, Mongoose will record that there was a validation error
    in the single nested schema path as well. For example:

    ```javascript
    const childSchema = new Schema({ name: { type: String, required: true } });
    const parentSchema = new Schema({ child: childSchema });

    const Parent = mongoose.model('Parent', parentSchema);

    // Will contain an error for both 'child.name' _and_ 'child'
    new Parent({ child: {} }).validateSync().errors;
    ```

    Set the `storeSubdocValidationError` to `false` on the child schema to make
    Mongoose only reports the parent error.

    ```javascript
    const childSchema = new Schema({
      name: { type: String, required: true }
    }, { storeSubdocValidationError: false }); // <-- set on the child schema
    const parentSchema = new Schema({ child: childSchema });

    const Parent = mongoose.model('Parent', parentSchema);

    // Will only contain an error for 'child.name'
    new Parent({ child: {} }).validateSync().errors;
    ```

    <h3 id="es6-classes"><a href="#es6-classes">With ES6 Classes</a></h3>

    Schemas have a [`loadClass()` method](/docs/api/schema.html#schema_Schema-loadClass)
    that you can use to create a Mongoose schema from an [ES6 class](https://thecodebarbarian.com/an-overview-of-es6-classes):

    * [ES6 class methods](https://masteringjs.io/tutorials/fundamentals/class#methods) become [Mongoose methods](/docs/guide.html#methods)
    * [ES6 class statics](https://masteringjs.io/tutorials/fundamentals/class#statics) become [Mongoose statics](/docs/guide.html#statics)
    * [ES6 getters and setters](https://masteringjs.io/tutorials/fundamentals/class#getterssetters) become [Mongoose virtuals](/docs/tutorials/virtuals.html)

    Here's an example of using `loadClass()` to create a schema from an ES6 class:

    ```javascript
    class MyClass {
      myMethod() { return 42; }
      static myStatic() { return 42; }
      get myVirtual() { return 42; }
    }

    const schema = new mongoose.Schema();
    schema.loadClass(MyClass);

    console.log(schema.methods); // { myMethod: [Function: myMethod] }
    console.log(schema.statics); // { myStatic: [Function: myStatic] }
    console.log(schema.virtuals); // { myVirtual: VirtualType { ... } }
    ```

    <h3 id="plugins"><a href="#plugins">Pluggable</a></h3>

    Schemas are also [pluggable](./plugins.html) which allows us to package up reusable features into
    plugins that can be shared with the community or just between your projects.

    <h3 id="further-reading">Further Reading</h3>

    Here's an [alternative introduction to Mongoose schemas](https://masteringjs.io/tutorials/mongoose/schema).

    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](https://en.wikipedia.org/wiki/Third_normal_form),
    whereas MongoDB schema design is about making common queries as fast as possible.
    The [_6 Rules of Thumb for MongoDB Schema Design_ blog series](https://www.mongodb.com/blog/post/6-rules-of-thumb-for-mongodb-schema-design-part-1)
    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_](http://bit.ly/mongodb-schema-design)
    by Christian Kvalheim, the original author of the [MongoDB Node.js driver](http://npmjs.com/package/mongodb).
    This book shows you how to implement performant schemas for a laundry list
    of use cases, including e-commerce, wikis, and appointment bookings.

    <h3 id="next">Next Up</h3>

    Now that we've covered `Schemas`, let's take a look at [SchemaTypes](/docs/schematypes.html).