Skip to content

Commit fa0eb40

Browse files
committed
docs: clarify disabling _id on subdocs
Fix #14194
1 parent 3bd67a8 commit fa0eb40

File tree

2 files changed

+38
-9
lines changed

2 files changed

+38
-9
lines changed

docs/guide.md

Lines changed: 37 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -109,9 +109,7 @@ const schema = new Schema();
109109
schema.path('_id'); // ObjectId { ... }
110110
```
111111

112-
When you create a new document with the automatically added
113-
`_id` property, Mongoose creates a new [`_id` of type ObjectId](https://masteringjs.io/tutorials/mongoose/objectid)
114-
to your document.
112+
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.
115113

116114
```javascript
117115
const Model = mongoose.model('Test', schema);
@@ -120,13 +118,13 @@ const doc = new Model();
120118
doc._id instanceof mongoose.Types.ObjectId; // true
121119
```
122120

123-
You can also overwrite Mongoose's default `_id` with your
124-
own `_id`. Just be careful: Mongoose will refuse to save a
125-
document that doesn't have an `_id`, so you're responsible
126-
for setting `_id` if you define your own `_id` path.
121+
You can also overwrite Mongoose's default `_id` with your own `_id`.
122+
Just be careful: Mongoose will refuse to save a top-level document that doesn't have an `_id`, so you're responsible for setting `_id` if you define your own `_id` path.
127123

128124
```javascript
129-
const schema = new Schema({ _id: Number });
125+
const schema = new Schema({
126+
_id: Number // <-- overwrite Mongoose's default `_id`
127+
});
130128
const Model = mongoose.model('Test', schema);
131129

132130
const doc = new Model();
@@ -136,6 +134,37 @@ doc._id = 1;
136134
await doc.save(); // works
137135
```
138136

137+
Mongoose also adds an `_id` property to subdocuments.
138+
You can disable the `_id` property on your subdocuments as follows.
139+
Mongoose does allow saving subdocuments without an `_id` property.
140+
141+
```javascript
142+
const nestedSchema = new Schema(
143+
{ name: String },
144+
{ _id: false } // <-- disable `_id`
145+
);
146+
const schema = new Schema({
147+
subdoc: nestedSchema,
148+
docArray: [nestedSchema]
149+
});
150+
const Test = mongoose.model('Test', schema);
151+
152+
// Neither `subdoc` nor `docArray.0` will have an `_id`
153+
await Test.create({
154+
subdoc: { name: 'test 1' },
155+
docArray: [{ name: 'test 2' }]
156+
});
157+
```
158+
159+
Alternatively, you can disable `_id` using the following syntax:
160+
161+
```javascript
162+
const nestedSchema = new Schema({
163+
_id: false, // <-- disable _id
164+
name: String
165+
});
166+
```
167+
139168
<h2 id="methods"><a href="#methods">Instance methods</a></h2>
140169

141170
Instances of `Models` are [documents](documents.html). Documents have

lib/schema.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ const numberRE = /^\d+$/;
4949
* const Tree = mongoose.model('Tree', schema);
5050
*
5151
* // setting schema options
52-
* new Schema({ name: String }, { _id: false, autoIndex: false })
52+
* new Schema({ name: String }, { id: false, autoIndex: false })
5353
*
5454
* #### Options:
5555
*

0 commit comments

Comments
 (0)