#
Mongoose

- home
- plugins
- change log
- support
- fork
- guide
  - schemas
    - schematypes
  - documents
    - sub docs
  - models
  - queries
  - plugins
  - middleware
  - validation
  - populate
  - migrating from 2.x
  - contributing
- api docs
- quick start
- contributors
- prior releases

## Sub Docs

Sub-documents are docs with schemas of their own which are elements of a parents document array:

    var childSchema = new Schema({ name: 'string' });

    var parentSchema = new Schema({
      children: [childSchema]
    })

Sub-documents enjoy all the same features as normal documents. The only difference is that they are not saved individually, they are saved whenever their top-level parent document is saved.

    var Parent = db.model('Parent', parentSchema);
    var parent = new Parent({ children: [{ name: 'Matt' }, { name: 'Sarah' }] })
    parent.children[0].name = 'Matthew';
    parent.save(callback);

If an error occurs in a sub-documents' middleware, it is bubbled up to the `save()` callback of the parent, so error handling is a snap!

    childSchema.pre('save', function (next) {
      if ('invalid' == this.name) return next(new Error('#sadpanda'));
      next();
    });

    var parent = new Parent({ children: [{ name: 'invalid' }] });
    parent.save(function (err) {
      console.log(err.message) // #sadpanda
    })

### Finding a sub-document

Each document has an `_id`. DocumentArrays have a special id method for looking up a document by its `_id`.

    var doc = parent.children.id(id);

### Adding sub-docs

MongooseArray methods such as push, unshift, addToSet, and others cast arguments to their proper types transparently:

    var Parent = db.model('Parent');
    var parent = new Parent;

    // create a comment
    post.children.push({ name: 'Liesl' });
    var doc = post.children[0];
    console.log(doc) // { _id: '501d86090d371bab2c0341c5', name: 'Liesl' }
    doc.isNew; // true

    post.save(function (err) {
      if (err) return handleError(err)
      console.log('Success!');
    });

Sub-docs may also be created without adding them to the array by using the create method of MongooseArrays.

    var newdoc = post.children.create({ name: 'Aaron' });

### Removing docs

Each sub-document has it's own remove method.

    var doc = parent.children.id(id).remove();
    parent.save(function (err) {
      if (err) return handleError(err);
      console.log('the sub-doc was removed')
    });

#### Alternate declaration syntax

New in v3 If you don't need access to the sub-document schema instance, you may also declare sub-docs by simply passing an object literal:

    var parentSchema = new Schema({
      children: [{ name: 'string' }]
    })