Skip to content

Commit

Permalink
docs(subdocs): clarify that populated docs are not subdocs
Browse files Browse the repository at this point in the history
Fix #12398
  • Loading branch information
vkarpov15 committed Oct 4, 2022
1 parent b4aaf62 commit e800193
Showing 1 changed file with 21 additions and 5 deletions.
26 changes: 21 additions & 5 deletions docs/subdocs.md
Expand Up @@ -11,15 +11,31 @@ const childSchema = new Schema({ name: 'string' });
const parentSchema = new Schema({
// Array of subdocuments
children: [childSchema],
// Single nested subdocuments. Caveat: single nested subdocs only work
// in mongoose >= 4.2.0
// Single nested subdocuments
child: childSchema
});
```

Aside from code reuse, one important reason to use subdocuments is to create
a path where there would otherwise not be one to allow for validation over
a group of fields (e.g. dateRange.fromDate <= dateRange.toDate).
Note that populated documents are **not** subdocuments in Mongoose.
Subdocument data is embedded in the top-level document.
Referenced documents are separate top-level documents.

```javascript
const childSchema = new Schema({ name: 'string' });
const Child = mongoose.model('Child', childSchema);

const parentSchema = new Schema({
child: {
type: mongoose.ObjectId,
ref: 'Child'
}
});
const Parent = mongoose.model('Parent', parentSchema);

const doc = await Parent.findOne().populate('child');
// NOT a subdocument. `doc.child` is a separate top-level document.
doc.child;
```

<ul class="toc">
<li><a href="#what-is-a-subdocument-">What is a Subdocument?</a></li>
Expand Down

0 comments on commit e800193

Please sign in to comment.