Skip to content
Fetching contributors…
Cannot retrieve contributors at this time
85 lines (71 sloc) 3.05 KB
extends layout
block content
h2 Sub Docs
:markdown
[Sub-documents](./api.html#types-embedded-js) are docs with schemas of their own which are elements of a parents document array:
:js
var childSchema = new Schema({ name: 'string' });
var parentSchema = new Schema({
children: [childSchema]
})
:markdown
Sub-documents enjoy all the same features as normal [documents](./api.html#document-js). The only difference is that they are not saved individually, they are saved whenever their top-level parent document is saved.
:js
var Parent = db.model('Parent', parentSchema);
var parent = new Parent({ children: [{ name: 'Matt' }, { name: 'Sarah' }] })
parent.children[0].name = 'Matthew';
parent.save(callback);
:markdown
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!
:js
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
})
h3 Finding a sub-document
:markdown
Each document has an `_id`. DocumentArrays have a special [id](./api.html#types_documentarray_MongooseDocumentArray-id) method for looking up a document by its `_id`.
:js
var doc = parent.children.id(id);
h3 Adding sub-docs
:markdown
MongooseArray methods such as [push](./api.html#types_array_MongooseArray-push), [unshift](./api.html#types_array_MongooseArray-unshift), [addToSet](./api.html#types_array_MongooseArray-addToSet), and others cast arguments to their proper types transparently:
:js
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!');
});
:markdown
Sub-docs may also be created without adding them to the array by using the [create](./api.html#types_documentarray_MongooseDocumentArray-create) method of MongooseArrays.
:js
var newdoc = post.children.create({ name: 'Aaron' });
h3 Removing docs
:markdown
Each sub-document has it's own [remove](./api.html#types_embedded_EmbeddedDocument-remove) method.
:js
var doc = parent.children.id(id).remove();
parent.save(function (err) {
if (err) return handleError(err);
console.log('the sub-doc was removed')
});
h4#altsyntax Alternate declaration syntax
:markdown
_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:
:js
var parentSchema = new Schema({
children: [{ name: 'string' }]
})
h3#next Next Up
:markdown
Now that we've covered `Sub-documents`, let's take a look at [querying](/docs/queries.html).
Jump to Line
Something went wrong with that request. Please try again.