Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify disabling _id on subdocs #14195

Merged
merged 2 commits into from Dec 27, 2023
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
45 changes: 37 additions & 8 deletions docs/guide.md
Expand Up @@ -109,9 +109,7 @@ 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.
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);
Expand All @@ -120,13 +118,13 @@ 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.
You can also overwrite Mongoose's default `_id` with your own `_id`.
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.

```javascript
const schema = new Schema({ _id: Number });
const schema = new Schema({
_id: Number // <-- overwrite Mongoose's default `_id`
});
const Model = mongoose.model('Test', schema);

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

Mongoose also adds an `_id` property to subdocuments.
You can disable the `_id` property on your subdocuments as follows.
Mongoose does allow saving subdocuments without an `_id` property.

```javascript
const nestedSchema = new Schema(
{ name: String },
{ _id: false } // <-- disable `_id`
);
const schema = new Schema({
subdoc: nestedSchema,
docArray: [nestedSchema]
});
const Test = mongoose.model('Test', schema);

// Neither `subdoc` nor `docArray.0` will have an `_id`
await Test.create({
subdoc: { name: 'test 1' },
docArray: [{ name: 'test 2' }]
});
```

Alternatively, you can disable `_id` using the following syntax:

```javascript
const nestedSchema = new Schema({
_id: false, // <-- disable _id
name: String
});
```

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

Instances of `Models` are [documents](documents.html). Documents have
Expand Down
2 changes: 1 addition & 1 deletion lib/schema.js
Expand Up @@ -49,7 +49,7 @@ const numberRE = /^\d+$/;
* const Tree = mongoose.model('Tree', schema);
*
* // setting schema options
* new Schema({ name: String }, { _id: false, autoIndex: false })
* new Schema({ name: String }, { id: false, autoIndex: false })
*
* #### Options:
*
Expand Down