mongoose/docs/guide.html at refactor-8554 · JavaScriptBach/mongoose

History

900 lines (809 loc) · 77.3 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no"><title>Mongoose v5.6.0: Schemas</title><link rel="apple-touch-icon" sizes="57x57" href="images/favicon/apple-icon-57x57.png"><link rel="apple-touch-icon" sizes="60x60" href="images/favicon/apple-icon-60x60.png"><link rel="apple-touch-icon" sizes="72x72" href="images/favicon/apple-icon-72x72.png"><link rel="apple-touch-icon" sizes="76x76" href="images/favicon/apple-icon-76x76.png"><link rel="apple-touch-icon" sizes="114x114" href="images/favicon/apple-icon-114x114.png"><link rel="apple-touch-icon" sizes="120x120" href="images/favicon/apple-icon-120x120.png"><link rel="apple-touch-icon" sizes="144x144" href="images/favicon/apple-icon-144x144.png"><link rel="apple-touch-icon" sizes="152x152" href="images/favicon/apple-icon-152x152.png"><link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-icon-180x180.png"><link rel="icon" type="image/png" sizes="192x192" href="images/favicon/android-icon-192x192.png"><link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"><link rel="icon" type="image/png" sizes="96x96" href="images/favicon/favicon-96x96.png"><link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"><link rel="stylesheet" href="https://unpkg.com/[email protected]/build/pure-min.css" integrity="sha384-nn4HPE8lTHyVtfCBi5yW9d20FjT8BJwUXyWZT9InLYax14RDjBj46LmSztkmNP9w" crossorigin="anonymous"><link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans"><link rel="stylesheet" href="/docs/css/github.css"><link rel="stylesheet" href="/docs/css/mongoose5.css"><link rel="apple-touch-icon" sizes="57x57" href="images/favicon/apple-icon-57x57.png"><link rel="apple-touch-icon" sizes="60x60" href="images/favicon/apple-icon-60x60.png"><link rel="apple-touch-icon" sizes="72x72" href="images/favicon/apple-icon-72x72.png"><link rel="apple-touch-icon" sizes="76x76" href="images/favicon/apple-icon-76x76.png"><link rel="apple-touch-icon" sizes="114x114" href="images/favicon/apple-icon-114x114.png"><link rel="apple-touch-icon" sizes="120x120" href="images/favicon/apple-icon-120x120.png"><link rel="apple-touch-icon" sizes="144x144" href="images/favicon/apple-icon-144x144.png"><link rel="apple-touch-icon" sizes="152x152" href="images/favicon/apple-icon-152x152.png"><link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-icon-180x180.png"><link rel="icon" type="image/png" sizes="192x192" href="images/favicon/android-icon-192x192.png"><link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"><link rel="icon" type="image/png" sizes="96x96" href="images/favicon/favicon-96x96.png"><link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"><link rel="manifest" href="images/favicon/manifest.json"><meta name="msapplication-TileColor" content="#ffffff"><meta name="msapplication-TileImage" content="images/favicon/ms-icon-144x144.png"><meta name="theme-color" content="#ffffff"><link rel="stylesheet" href="/docs/css/inlinecpc.css"><script type="text/javascript" src="/docs/js/native.js"></script></head><body><div id="layout"><div id="mobile-menu"><a class="menu-link" id="menuLink" href="#menu"></a><div id="mobile-logo-container"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png">mongoose</a></div></div><div id="menu"><div class="pure-menu"><div class="pure-menu-heading" id="logo-container"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png">mongoose</a></div><ul class="pure-menu-list" id="navbar"><li class="pure-menu-horizontal pure-menu-item pure-menu-has-children pure-menu-allow-hover version"><a class="pure-menu-link" href="#">Version 5.6.0</a><ul class="pure-menu-children"><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/4.x">Version 4.13.18</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/3.8.x">Version 3.8.40</a></li></ul></li><li class="pure-menu-item search"><input id="search-input-nav" type="text" placeholder="Search"><button id="search-button-nav"><img src="/docs/images/search.svg"></button></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/index.html">Quick Start</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/guides.html">Guides</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/guide.html">Schemas</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/schematypes.html">SchemaTypes</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/connections.html">Connections</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/models.html">Models</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/documents.html">Documents</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/subdocs.html">Subdocuments</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/queries.html">Queries</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/validation.html">Validation</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/middleware.html">Middleware</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/populate.html">Populate</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/discriminators.html">Discriminators</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/plugins.html">Plugins</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/api.html">API</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/mongoose.html">Mongoose</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/schema.html">Schema</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/connection.html">Connection</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/document.html">Document</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/model.html">Model</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/query.html">Query</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/aggregate.html">Aggregate</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/schematype.html">SchemaType</a></li><li class="pure-menu-item sub-item"><a class="pure-menu-link" href="/docs/api/virtualtype.html">VirtualType</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/compatibility.html">Version Compatibility</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/faq.html">FAQ</a></li><li class="pure-menu-item"><a class="pure-menu-link" href="/docs/further_reading.html">Further Reading</a></li></ul><div class="cpc-ad"><script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=mongoosejscom" id="_carbonads_js"></script></div></div></div><div class="container"><div id="content"><h2 id="schemas">Schemas</h2>

_native.init("CK7DT53U",{

targetClass: 'native-inline'

});

</script>

<a href="#native_link#">Sponsor #native_company# — #native_desc#</a>

</div>

<div class="important">If you haven't yet done so, please take a minute to read the <a href="./index.html">quickstart</a> to get an idea of how Mongoose works.

If you are migrating from 4.x to 5.x please take a moment to read the <a href="/docs/migrating_to_5.html">migration guide</a>.

</div><ul class="toc">

<li><a href="#models">Defining your schema</a></li>

<li><a href="#models">Creating a model</a></li>

<li><a href="#methods">Instance methods</a></li>

<li><a href="#statics">Statics</a></li>

<li><a href="#query-helpers">Query Helpers</a></li>

<li><a href="#indexes">Indexes</a></li>

<li><a href="#virtuals">Virtuals</a></li>

<li><a href="#aliases">Aliases</a></li>

<li><a href="#options">Options</a></li>

<li><a href="#plugins">Pluggable</a></li>

</ul>

<h3 id="definition"><a href="#definition">Defining your schema</a></h3>

Everything in Mongoose starts with a Schema. Each schema maps to a MongoDB

collection and defines the shape of the documents within that collection.

<pre><code class="language-javascript"> var mongoose = require('mongoose');

var Schema = mongoose.Schema;

var blogSchema = new Schema({

title: String,

author: String,

body: String,

comments: [{ body: String, date: Date }],

date: { type: Date, default: Date.now },

hidden: Boolean,

meta: {

votes: Number,

favs: Number

}

});</code></pre>

If you want to add additional keys later, use the

<a href="./api.html#schema_Schema-add">Schema#add</a> method.

Each key in our code <code>blogSchema</code> defines a property in our documents which

will be cast to its associated <a href="./api.html#schematype_SchemaType">SchemaType</a>.

For example, we've defined a property <code>title</code> which will be cast to the

<a href="./api.html#schema-string-js">String</a> SchemaType and property <code>date</code>

which will be cast to a <code>Date</code> SchemaType. Keys may also be assigned

nested objects containing further key/type definitions like

the <code>meta</code> property above.

The permitted SchemaTypes are:

<ul>

<li><a href="./schematypes.html#strings">String</a></li>

<li><a href="./schematypes.html#numbers">Number</a></li>

<li><a href="./schematypes.html#buffers">Buffer</a></li>

<li><a href="./schematypes.html#booleans">Boolean</a></li>

<li><a href="./schematypes.html#mixed">Mixed</a></li>

<li><a href="./schematypes.html#objectids">ObjectId</a></li>

<li><a href="./schematypes.html#arrays">Array</a></li>

<li>Decimal128</li>

</ul>

Read more about <a href="./schematypes.html">SchemaTypes here</a>.

Schemas not only define the structure of your document and casting of

properties, they also define document <a href="#methods">instance methods</a>,

<a href="#statics">static Model methods</a>, <a href="#indexes">compound indexes</a>,

and document lifecycle hooks called <a href="./middleware.html">middleware</a>.

<h3 id="models"><a href="#models">Creating a model</a></h3>

To use our schema definition, we need to convert our <code>blogSchema</code> into a

<a href="./models.html">Model</a> we can work with.

To do so, we pass it into <code>mongoose.model(modelName, schema)</code>:

<pre><code class="language-javascript"> var Blog = mongoose.model('Blog', blogSchema);

// ready to go!</code></pre>

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

Instances of <code>Models</code> are <a href="./documents.html">documents</a>. Documents have

many of their own <a href="./api.html#document-js">built-in instance methods</a>.

We may also define our own custom document instance methods too.

<pre><code class="language-javascript"> // define a schema

var animalSchema = new Schema({ name: String, type: String });

// assign a function to the "methods" object of our animalSchema

animalSchema.methods.findSimilarTypes = function(cb) {

return this.model('Animal').find({ type: this.type }, cb);

};</code></pre>

Now all of our <code>animal</code> instances have a <code>findSimilarTypes</code> method available

to them.

<pre><code class="language-javascript"> var Animal = mongoose.model('Animal', animalSchema);

var dog = new Animal({ type: 'dog' });

dog.findSimilarTypes(function(err, dogs) {

console.log(dogs); // woof

});</code></pre>

<ul>

<li>Overwriting a default mongoose document method may lead to unpredictable results. See <a href="./api.html#schema_Schema.reserved">this</a> for more details.</li>

<li>The example above uses the <code>Schema.methods</code> object directly to save an instance method. You can also use the <code>Schema.method()</code> helper as described <a href="./api.html#schema_Schema-method">here</a>.</li>

<li>Do not declare methods using ES6 arrow functions (<code>=></code>). Arrow functions <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#No_binding_of_this">explicitly prevent binding <code>this</code></a>, so your method will not have access to the document and the above examples will not work.</li>

</ul>

<h3 id="statics"><a href="#statics">Statics</a></h3>

You can also add static functions to your model. There are 2 equivalent

ways to add a static:

<ul>

<li>Add a function property to <code>schema.statics</code></li>

<li>Call the <a href="/docs/api.html#schema_Schema-static"><code>Schema#static()</code> function</a></li>

</ul>

<pre><code class="language-javascript"> // Assign a function to the "statics" object of our animalSchema

animalSchema.statics.findByName = function(name) {

return this.find({ name: new RegExp(name, 'i') });

};

// Or, equivalently, you can call `animalSchema.static()`.

animalSchema.static('findByBreed', function(breed) {

return this.find({ breed });

});

const Animal = mongoose.model('Animal', animalSchema);

let animals = await Animal.findByName('fido');

animls = animals.concat(await Animal.findByBreed('Poodle'));</code></pre>

Do not declare statics using ES6 arrow functions (<code>=></code>). Arrow functions <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/Arrow_functions#No_binding_of_this">explicitly prevent binding <code>this</code></a>, so the above examples will not work because of the value of <code>this</code>.

<h3 id="query-helpers"><a href="#query-helpers">Query Helpers</a></h3>

You can also add query helper functions, which are like instance methods

but for mongoose queries. Query helper methods let you extend mongoose's

<a href="./queries.html">chainable query builder API</a>.

<pre><code class="language-javascript"> animalSchema.query.byName = function(name) {

return this.where({ name: new RegExp(name, 'i') });

};

var Animal = mongoose.model('Animal', animalSchema);

Animal.find().byName('fido').exec(function(err, animals) {

console.log(animals);

});

Animal.findOne().byName('fido').exec(function(err, animal) {

console.log(animal);

});</code></pre>

<h3 id="indexes"><a href="#indexes">Indexes</a></h3>

MongoDB supports <a href="http://docs.mongodb.org/manual/indexes/">secondary indexes</a>.

With mongoose, we define these indexes within our <code>Schema</code> <a href="./api.html#schematype_SchemaType-index">at</a> <a href="./api.html#schematype_SchemaType-unique">the</a> <a href="./api.html#schematype_SchemaType-sparse">path</a> <a href="./api.html#schema_date_SchemaDate-expires">level</a> or the <code>schema</code> level.

Defining indexes at the schema level is necessary when creating

<a href="https://docs.mongodb.com/manual/core/index-compound/">compound indexes</a>.

<pre><code class="language-javascript"> var animalSchema = new Schema({

type: String,

tags: { type: [String], index: true } // field level

});

animalSchema.index({ name: 1, type: -1 }); // schema level</code></pre>

When your application starts up, Mongoose automatically calls <a href="https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#db.collection.createIndex"><code>createIndex</code></a> for each defined index in your schema.

Mongoose will call <code>createIndex</code> for each index sequentially, and emit an 'index' event on the model when all the <code>createIndex</code> calls succeeded or when there was an error.

While nice for development, it is recommended this behavior be disabled in production since index creation can cause a <a href="http://docs.mongodb.org/manual/core/indexes/#index-creation-operations">significant performance impact</a>. Disable the behavior by setting the <code>autoIndex</code> option of your schema to <code>false</code>, or globally on the connection by setting the option <code>autoIndex</code> to <code>false</code>.

<pre><code class="language-javascript"> mongoose.connect('mongodb://user:pass@localhost:port/database', { autoIndex: false });

// or

mongoose.createConnection('mongodb://user:pass@localhost:port/database', { autoIndex: false });

// or

animalSchema.set('autoIndex', false);

// or

new Schema({..}, { autoIndex: false });</code></pre>

Mongoose will emit an <code>index</code> event on the model when indexes are done

building or an error occurred.

<pre><code class="language-javascript"> // Will cause an error because mongodb has an _id index by default that

// is not sparse

animalSchema.index({ _id: 1 }, { sparse: true });

var Animal = mongoose.model('Animal', animalSchema);

Animal.on('index', function(error) {

// "_id index cannot be sparse"

console.log(error.message);

});</code></pre>

See also the <a href="./api.html#model_Model.ensureIndexes">Model#ensureIndexes</a> method.

<h3 id="virtuals"><a href="#virtuals">Virtuals</a></h3>

<a href="./api.html#schema_Schema-virtual">Virtuals</a> are document properties that

you can get and set but that do not get persisted to MongoDB. The getters

are useful for formatting or combining fields, while setters are useful for

de-composing a single value into multiple values for storage.

<pre><code class="language-javascript"> // define a schema

var personSchema = new Schema({

first: String,

last: String

}

});

// compile our model

var Person = mongoose.model('Person', personSchema);

// create a document

var axl = new Person({

});</code></pre>

Suppose you want to print out the person's full name. You could do it yourself:

<pre><code class="language-javascript">console.log(axl.name.first + ' ' + axl.name.last); // Axl Rose</code></pre>

But concatenating the first and last name every time can get cumbersome.

And what if you want to do some extra processing on the name, like

<a href="https://www.npmjs.com/package/diacritics">removing diacritics</a>? A

<a href="./api.html#virtualtype_VirtualType-get">virtual property getter</a> lets you

define a <code>fullName</code> property that won't get persisted to MongoDB.

<pre><code class="language-javascript">personSchema.virtual('fullName').get(function () {

return this.name.first + ' ' + this.name.last;

});</code></pre>

Now, mongoose will call your getter function every time you access the

<code>fullName</code> property:

<pre><code class="language-javascript">console.log(axl.fullName); // Axl Rose</code></pre>

If you use <code>toJSON()</code> or <code>toObject()</code> mongoose will not include virtuals

by default. This includes the output of calling <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify"><code>JSON.stringify()</code></a>

on a Mongoose document, because <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description"><code>JSON.stringify()</code> calls <code>toJSON()</code></a>.

Pass <code>{ virtuals: true }</code> to either

<a href="./api.html#document_Document-toObject"><code>toObject()</code></a> or <a href="./api.html#document_Document-toJSON"><code>toJSON()</code></a>.

You can also add a custom setter to your virtual that will let you set both

first name and last name via the <code>fullName</code> virtual.

<pre><code class="language-javascript">personSchema.virtual('fullName').

get(function() { return this.name.first + ' ' + this.name.last; }).

set(function(v) {

this.name.first = v.substr(0, v.indexOf(' '));

this.name.last = v.substr(v.indexOf(' ') + 1);

});

axl.fullName = 'William Rose'; // Now `axl.name.first` is "William"</code></pre>

Virtual property setters are applied before other validation. So the example

above would still work even if the <code>first</code> and <code>last</code> name fields were

required.

Only non-virtual properties work as part of queries and for field selection.

Since virtuals are not stored in MongoDB, you can't query with them.

<h5 id="aliases"><a href="#aliases">Aliases</a></h5>

Aliases are a particular type of virtual where the getter and setter

seamlessly get and set another property. This is handy for saving network

bandwidth, so you can convert a short property name stored in the database

into a longer name for code readability.

<pre><code class="language-javascript">var personSchema = new Schema({

n: {

type: String,

// Now accessing `name` will get you the value of `n`, and setting `n` will set the value of `name`

alias: 'name'

}

});

// Setting `name` will propagate to `n`

var person = new Person({ name: 'Val' });

console.log(person); // { n: 'Val' }

console.log(person.toObject({ virtuals: true })); // { n: 'Val', name: 'Val' }

console.log(person.name); // "Val"

person.name = 'Not Val';

console.log(person); // { n: 'Not Val' }</code></pre>

You can also declare aliases on nested paths. It is easier to use nested

schemas and <a href="/docs/subdocs.html">subdocuments</a>, but you can also declare

nested path aliases inline as long as you use the full nested path

<code>nested.myProp</code> as the alias.

<pre><code class="language-javascript">const childSchema = new Schema({

n: {

type: String,

alias: 'name'

}

}, { _id: false });

const parentSchema = new Schema({

// If in a child schema, alias doesn't need to include the full nested path

c: childSchema,

f: {

type: String,

// Alias needs to include the full nested path if declared inline

alias: 'name.first'

}

});</code></pre>

<h3 id="options"><a href="#options">Options</a></h3>

Schemas have a few configurable options which can be passed to the

constructor or <code>set</code> directly:

<pre><code class="language-javascript">new Schema({..}, options);

// or

var schema = new Schema({..});

schema.set(option, value);</code></pre>

Valid options:

<ul>

<li><a href="#autoIndex">autoIndex</a></li>

<li><a href="#autoCreate">autoCreate</a></li>

<li><a href="#bufferCommands">bufferCommands</a></li>

<li><a href="#capped">capped</a></li>

<li><a href="#collection">collection</a></li>

<li><a href="#minimize">minimize</a></li>

<li><a href="#writeConcern">writeConcern</a></li>

<li><a href="#shardKey">shardKey</a></li>

<li><a href="#strict">strict</a></li>

<li><a href="#strictQuery">strictQuery</a></li>

<li><a href="#toJSON">toJSON</a></li>

<li><a href="#toObject">toObject</a></li>

<li><a href="#typeKey">typeKey</a></li>

<li><a href="#useNestedStrict">useNestedStrict</a></li>

<li><a href="#validateBeforeSave">validateBeforeSave</a></li>

<li><a href="#versionKey">versionKey</a></li>

<li><a href="#collation">collation</a></li>

<li><a href="#selectPopulatedPaths">selectPopulatedPaths</a></li>

<li><a href="#skipVersioning">skipVersioning</a></li>

<li><a href="#timestamps">timestamps</a></li>

<li><a href="#storeSubdocValidationError">storeSubdocValidationError</a></li>

</ul>

<h3 id="autoIndex"><a href="#autoIndex">option: autoIndex</a></h3>

By default, Mongoose's <a href="/docs/api.html#model_Model.init"><code>init()</code> function</a>

creates all the indexes defined in your model's schema by calling

<a href="/docs/api.html#model_Model.createIndexes"><code>Model.createIndexes()</code></a>

after you successfully connect to MongoDB. Creating indexes automatically is

great for development and test environments. But index builds can also create

significant load on your production database. If you want to manage indexes

carefully in production, you can set <code>autoIndex</code> to false.

<pre><code class="language-javascript">const schema = new Schema({..}, { autoIndex: false });

const Clock = mongoose.model('Clock', schema);

Clock.ensureIndexes(callback);</code></pre>

The <code>autoIndex</code> option is set to <code>true</code> by default. You can change this

default by setting <code>mongoose.use('autoIndex', false);</code>

<h3 id="autoCreate"><a href="#autoCreate">option: autoCreate</a></h3>

Before Mongoose builds indexes, it calls <code>Model.createCollection()</code>

to create the underlying collection in MongoDB if <code>autoCreate</code> is set to true.

Calling <code>createCollection()</code>

sets the <a href="https://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations">collection's default collation</a>

based on the <a href="#collation">collation option</a> and establishes the collection as

a capped collection if you set the <a href="#capped"><code>capped</code> schema option</a>. Like

<code>autoIndex</code>, setting <code>autoCreate</code> to true is helpful for development and

test environments.

Unfortunately, <code>createCollection()</code> cannot change an existing collection.

For example, if you add <code>capped: 1024</code> to your schema and the existing

collection is not capped, <code>createCollection()</code> will throw an error.

Generally, <code>autoCreate</code> should be <code>false</code> for production environments.

<pre><code class="language-javascript">const schema = new Schema({..}, { autoCreate: true, capped: 1024 });

const Clock = mongoose.model('Clock', schema);

// Mongoose will create the capped collection for you.</code></pre>

Unlike <code>autoIndex</code>, <code>autoCreate</code> is <code>false</code> by default. You can change this

default by setting <code>mongoose.use('autoCreate', true);</code>

<h3 id="bufferCommands"><a href="#bufferCommands">option: bufferCommands</a></h3>

By default, mongoose buffers commands when the connection goes down until

the driver manages to reconnect. To disable buffering, set <code>bufferCommands</code>

to false.

<pre><code class="language-javascript">var schema = new Schema({..}, { bufferCommands: false });</code></pre>

The schema <code>bufferCommands</code> option overrides the global <code>bufferCommands</code> option.

<pre><code class="language-javascript">mongoose.set('bufferCommands', true);

// Schema option below overrides the above, if the schema option is set.

var schema = new Schema({..}, { bufferCommands: false });</code></pre>

<h3 id="capped"><a href="#capped">option: capped</a></h3>

Mongoose supports MongoDBs <a href="http://www.mongodb.org/display/DOCS/Capped+Collections">capped</a>

collections. To specify the underlying MongoDB collection be <code>capped</code>, set

the <code>capped</code> option to the maximum size of the collection in

<a href="http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-size.">bytes</a>.

<pre><code class="language-javascript">new Schema({..}, { capped: 1024 });</code></pre>

The <code>capped</code> option may also be set to an object if you want to pass

additional options like <a href="http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-max">max</a>

or <a href="http://www.mongodb.org/display/DOCS/Capped+Collections#CappedCollections-autoIndexId">autoIndexId</a>.

In this case you must explicitly pass the <code>size</code> option, which is required.

<pre><code class="language-javascript">new Schema({..}, { capped: { size: 1024, max: 1000, autoIndexId: true } });</code></pre>

<h3 id="collection"><a href="#collection">option: collection</a></h3>

Mongoose by default produces a collection name by passing the model name to

the <a href="./api.html#utils_exports.toCollectionName">utils.toCollectionName</a> method.

This method pluralizes the name. Set this option if you need a different name

for your collection.

<pre><code class="language-javascript">var dataSchema = new Schema({..}, { collection: 'data' });</code></pre>

<h3 id="id"><a href="#id">option: id</a></h3>

Mongoose assigns each of your schemas an <code>id</code> virtual getter by default

which returns the documents <code>_id</code> field cast to a string, or in the case of

ObjectIds, its hexString. If you don't want an <code>id</code> getter added to your

schema, you may disable it passing this option at schema construction time.

<pre><code class="language-javascript">// default behavior

var schema = new Schema({ name: String });

var Page = mongoose.model('Page', schema);

var p = new Page({ name: 'mongodb.org' });

console.log(p.id); // '50341373e894ad16347efe01'

// disabled id

var schema = new Schema({ name: String }, { id: false });

var Page = mongoose.model('Page', schema);

var p = new Page({ name: 'mongodb.org' });

console.log(p.id); // undefined</code></pre>

<h3 id="_id"><a href="#_id">option: _id</a></h3>

Mongoose assigns each of your schemas an <code>_id</code> field by default if one

is not passed into the <a href="/docs/api.html#schema-js">Schema</a> constructor.

The type assigned is an <a href="/docs/api.html#schema_Schema.Types">ObjectId</a>

to coincide with MongoDB's default behavior. If you don't want an <code>_id</code>

added to your schema at all, you may disable it using this option.

You can only use this option on subdocuments. Mongoose can't

save a document without knowing its id, so you will get an error if

you try to save a document without an <code>_id</code>.

<pre><code class="language-javascript">// default behavior

var schema = new Schema({ name: String });

var Page = mongoose.model('Page', schema);

var p = new Page({ name: 'mongodb.org' });

console.log(p); // { _id: '50341373e894ad16347efe01', name: 'mongodb.org' }

// disabled _id

var childSchema = new Schema({ name: String }, { _id: false });

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

var Model = mongoose.model('Model', parentSchema);

Model.create({ children: [{ name: 'Luke' }] }, function(error, doc) {

// doc.children[0]._id will be undefined

});</code></pre>

<h3 id="minimize"><a href="#minimize">option: minimize</a></h3>

Mongoose will, by default, "minimize" schemas by removing empty objects.

<pre><code class="language-javascript">const schema = new Schema({ name: String, inventory: {} });

const Character = mongoose.model('Character', schema);

// will store `inventory` field if it is not empty

const frodo = new Character({ name: 'Frodo', inventory: { ringOfPower: 1 }});

await frodo.save();

let doc = await Character.findOne({ name: 'Frodo' }).lean();

doc.inventory; // { ringOfPower: 1 }

// will not store `inventory` field if it is empty

const sam = new Character({ name: 'Sam', inventory: {}});

await sam.save();

doc = await Character.findOne({ name: 'Sam' }).lean();

doc.inventory; // undefined</code></pre>

This behavior can be overridden by setting <code>minimize</code> option to <code>false</code>. It

will then store empty objects.

const Character = mongoose.model('Character', schema);

// will store `inventory` if empty

const sam = new Character({ name: 'Sam', inventory: {} });

await sam.save();

doc = await Character.findOne({ name: 'Sam' }).lean();

doc.inventory; // {}</code></pre>

To check whether an object is empty, you can use the <code>$isEmpty()</code> helper:

<pre><code class="language-javascript">const sam = new Character({ name: 'Sam', inventory: {} });

sam.$isEmpty('inventory'); // true

sam.inventory.barrowBlade = 1;

sam.$isEmpty('inventory'); // false</code></pre>

<h3 id="read"><a href="#read">option: read</a></h3>

Allows setting <a href="/docs/api.html#query_Query-read">query#read</a> options at the

schema level, providing us a way to apply default

<a href="http://docs.mongodb.org/manual/applications/replication/#replica-set-read-preference">ReadPreferences</a>

to all queries derived from a model.

<pre><code class="language-javascript">var schema = new Schema({..}, { read: 'primary' }); // also aliased as 'p'

var schema = new Schema({..}, { read: 'primaryPreferred' }); // aliased as 'pp'

var schema = new Schema({..}, { read: 'secondary' }); // aliased as 's'

var schema = new Schema({..}, { read: 'secondaryPreferred' }); // aliased as 'sp'

var schema = new Schema({..}, { read: 'nearest' }); // aliased as 'n'</code></pre>

The alias of each pref is also permitted so instead of having to type out

'secondaryPreferred' and getting the spelling wrong, we can simply pass 'sp'.

The read option also allows us to specify tag sets. These tell the

<a href="https://github.com/mongodb/node-mongodb-native/">driver</a> from which members

of the replica-set it should attempt to read. Read more about tag sets

<a href="http://docs.mongodb.org/manual/applications/replication/#tag-sets">here</a> and

<a href="http://mongodb.github.com/node-mongodb-native/driver-articles/anintroductionto1_1and2_2.html#read-preferences">here</a>.

NOTE: you may also specify the driver read pref <a href="http://mongodb.github.com/node-mongodb-native/api-generated/replset.html?highlight=strategy">strategy</a>

option when connecting:

<pre><code class="language-javascript">// pings the replset members periodically to track network latency

var options = { replset: { strategy: 'ping' }};

mongoose.connect(uri, options);

var schema = new Schema({..}, { read: ['nearest', { disk: 'ssd' }] });

mongoose.model('JellyBean', schema);</code></pre>

<h3 id="writeConcern"><a href="#writeConcern">option: writeConcern</a></h3>

Allows setting <a href="https://docs.mongodb.com/manual/reference/write-concern/">write concern</a>

at the schema level.

<pre><code class="language-javascript">const schema = new Schema({ name: String }, {

writeConcern: {

w: 'majority',

j: true,

wtimeout: 1000

}

});</code></pre>

<h3 id="shardKey"><a href="#shardKey">option: shardKey</a></h3>

The <code>shardKey</code> option is used when we have a <a href="http://www.mongodb.org/display/DOCS/Sharding+Introduction">sharded MongoDB architecture</a>.

Each sharded collection is given a shard key which must be present in all

insert/update operations. We just need to set this schema option to the same

shard key and we’ll be all set.

<pre><code class="language-javascript">new Schema({ .. }, { shardKey: { tag: 1, name: 1 }})</code></pre>

Note that Mongoose does not send the <code>shardcollection</code> command for you. You

must configure your shards yourself.

<h3 id="strict">option: strict</h3>

The strict option, (enabled by default), ensures that values passed to our

model constructor that were not specified in our schema do not get saved to

the db.

<pre><code class="language-javascript">var thingSchema = new Schema({..})

var Thing = mongoose.model('Thing', thingSchema);

var thing = new Thing({ iAmNotInTheSchema: true });

thing.save(); // iAmNotInTheSchema is not saved to the db

// set to false..

var thingSchema = new Schema({..}, { strict: false });

var thing = new Thing({ iAmNotInTheSchema: true });

thing.save(); // iAmNotInTheSchema is now saved to the db!!</code></pre>

This also affects the use of <code>doc.set()</code> to set a property value.

<pre><code class="language-javascript">var thingSchema = new Schema({..})

var Thing = mongoose.model('Thing', thingSchema);

var thing = new Thing;

thing.set('iAmNotInTheSchema', true);

thing.save(); // iAmNotInTheSchema is not saved to the db</code></pre>

This value can be overridden at the model instance level by passing a second

boolean argument:

<pre><code class="language-javascript">var Thing = mongoose.model('Thing');

var thing = new Thing(doc, true); // enables strict mode

var thing = new Thing(doc, false); // disables strict mode</code></pre>

The <code>strict</code> option may also be set to <code>"throw"</code> which will cause errors

to be produced instead of dropping the bad data.

NOTE: Any key/val set on the instance that does not exist in your schema is always ignored, regardless of schema option.

<pre><code class="language-javascript">var thingSchema = new Schema({..})

var Thing = mongoose.model('Thing', thingSchema);

var thing = new Thing;

thing.iAmNotInTheSchema = true;

thing.save(); // iAmNotInTheSchema is never saved to the db</code></pre>

<h3 id="strictQuery">option: strictQuery</h3>

For backwards compatibility, the <code>strict</code> option does not apply to

the <code>filter</code> parameter for queries.

<pre><code class="language-javascript">const mySchema = new Schema({ field: Number }, { strict: true });

const MyModel = mongoose.model('Test', mySchema);

// Mongoose will **not** filter out `notInSchema: 1`, despite `strict: true`

MyModel.find({ notInSchema: 1 });</code></pre>

The <code>strict</code> option does apply to updates.

<pre><code class="language-javascript">// Mongoose will strip out `notInSchema` from the update if `strict` is

// not `false`

MyModel.updateMany({}, { $set: { notInSchema: 1 } });</code></pre>

Mongoose has a separate <code>strictQuery</code> option to toggle strict mode for

the <code>filter</code> parameter to queries.

<pre><code class="language-javascript">const mySchema = new Schema({ field: Number }, {

strict: true,

strictQuery: true // Turn on strict mode for query filters

});

const MyModel = mongoose.model('Test', mySchema);

// Mongoose will strip out `notInSchema: 1` because `strictQuery` is `true`

MyModel.find({ notInSchema: 1 });</code></pre>

<h3 id="toJSON"><a href="#toJSON">option: toJSON</a></h3>

Exactly the same as the <a href="#toObject">toObject</a> option but only applies when

the documents <code>toJSON</code> method is called.

<pre><code class="language-javascript">var schema = new Schema({ name: String });

schema.path('name').get(function (v) {

return v + ' is my name';

});

schema.set('toJSON', { getters: true, virtuals: false });

var M = mongoose.model('Person', schema);

var m = new M({ name: 'Max Headroom' });

console.log(m.toObject()); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom' }

console.log(m.toJSON()); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom is my name' }

// since we know toJSON is called whenever a js object is stringified:

console.log(JSON.stringify(m)); // { "_id": "504e0cd7dd992d9be2f20b6f", "name": "Max Headroom is my name" }</code></pre>

To see all available <code>toJSON/toObject</code> options, read <a href="/docs/api.html#document_Document-toObject">this</a>.

<h3 id="toObject"><a href="#toObject">option: toObject</a></h3>

Documents have a <a href="/docs/api.html#document_Document-toObject">toObject</a> method

which converts the mongoose document into a plain javascript object. This

method accepts a few options. Instead of applying these options on a

per-document basis we may declare the options here and have it applied to

all of this schemas documents by default.

To have all virtuals show up in your <code>console.log</code> output, set the

<code>toObject</code> option to <code>{ getters: true }</code>:

<pre><code class="language-javascript">var schema = new Schema({ name: String });

schema.path('name').get(function (v) {

return v + ' is my name';

});

schema.set('toObject', { getters: true });

var M = mongoose.model('Person', schema);

var m = new M({ name: 'Max Headroom' });

console.log(m); // { _id: 504e0cd7dd992d9be2f20b6f, name: 'Max Headroom is my name' }</code></pre>

To see all available <code>toObject</code> options, read <a href="/docs/api.html#document_Document-toObject">this</a>.

<h3 id="typeKey"><a href="#typeKey">option: typeKey</a></h3>

By default, if you have an object with key 'type' in your schema, mongoose

will interpret it as a type declaration.

<pre><code class="language-javascript">// Mongoose interprets this as 'loc is a String'

var schema = new Schema({ loc: { type: String, coordinates: [Number] } });</code></pre>

However, for applications like <a href="http://docs.mongodb.org/manual/reference/geojson/">geoJSON</a>,

the 'type' property is important. If you want to control which key mongoose

uses to find type declarations, set the 'typeKey' schema option.

<pre><code class="language-javascript">var schema = new Schema({

// Mongoose interpets this as 'loc is an object with 2 keys, type and coordinates'

loc: { type: String, coordinates: [Number] },

// Mongoose interprets this as 'name is a String'

}, { typeKey: '$type' }); // A '$type' key means this object is a type declaration</code></pre>

<h3 id="validateBeforeSave"><a href="#validateBeforeSave">option: validateBeforeSave</a></h3>

By default, documents are automatically validated before they are saved to

the database. This is to prevent saving an invalid document. If you want to

handle validation manually, and be able to save objects which don't pass

validation, you can set <code>validateBeforeSave</code> to false.

<pre><code class="language-javascript">var schema = new Schema({ name: String });

schema.set('validateBeforeSave', false);

schema.path('name').validate(function (value) {

return v != null;

});

var M = mongoose.model('Person', schema);

var m = new M({ name: null });

m.validate(function(err) {

console.log(err); // Will tell you that null is not allowed.

});

m.save(); // Succeeds despite being invalid</code></pre>

<h3 id="versionKey"><a href="#versionKey">option: versionKey</a></h3>

The <code>versionKey</code> is a property set on each document when first created by

Mongoose. This keys value contains the internal

<a href="http://aaronheckmann.tumblr.com/post/48943525537/mongoose-v3-part-1-versioning">revision</a>

of the document. The <code>versionKey</code> option is a string that represents the

path to use for versioning. The default is <code>__v</code>. If this conflicts with

your application you can configure as such:

<pre><code class="language-javascript">const schema = new Schema({ name: 'string' });

const Thing = mongoose.model('Thing', schema);

const thing = new Thing({ name: 'mongoose v3' });

await thing.save(); // { __v: 0, name: 'mongoose v3' }

// customized versionKey

new Schema({..}, { versionKey: '_somethingElse' })

const Thing = mongoose.model('Thing', schema);

const thing = new Thing({ name: 'mongoose v3' });

thing.save(); // { _somethingElse: 0, name: 'mongoose v3' }</code></pre>

Note that Mongoose versioning is not a full <a href="https://en.wikipedia.org/wiki/Optimistic_concurrency_control">optimistic concurrency</a>

solution. Use <a href="https://github.com/eoin-obrien/mongoose-update-if-current">mongoose-update-if-current</a>

for OCC support. Mongoose versioning only operates on arrays:

<pre><code class="language-javascript">// 2 copies of the same document

const doc1 = await Model.findOne({ _id });

const doc2 = await Model.findOne({ _id });

// Delete first 3 comments from `doc1`

doc1.comments.splice(0, 3);

await doc1.save();

// The below `save()` will throw a VersionError, because you're trying to

// modify the comment at index 1, and the above `splice()` removed that

// comment.

doc2.set('comments.1.body', 'new comment');

await doc2.save();</code></pre>

Document versioning can also be disabled by setting the <code>versionKey</code> to

<code>false</code>.

DO NOT disable versioning unless you <a href="http://aaronheckmann.tumblr.com/post/48943525537/mongoose-v3-part-1-versioning">know what you are doing</a>.

<pre><code class="language-javascript">new Schema({..}, { versionKey: false });

const Thing = mongoose.model('Thing', schema);

const thing = new Thing({ name: 'no versioning please' });

thing.save(); // { name: 'no versioning please' }</code></pre>

Mongoose only updates the version key when you use <a href="/docs/api.html#document_Document-save"><code>save()</code></a>.

If you use <code>update()</code>, <code>findOneAndUpdate()</code>, etc. Mongoose will not

update the version key. As a workaround, you can use the below middleware.

<pre><code class="language-javascript">schema.pre('findOneAndUpdate', function() {

const update = this.getUpdate();

if (update.__v != null) {

delete update.__v;

}

const keys = ['$set', '$setOnInsert'];

for (const key of keys) {

if (update[key] != null && update[key].__v != null) {

delete update[key].__v;

if (Object.keys(update[key]).length === 0) {

delete update[key];

}

update.$inc = update.$inc || {};

update.$inc.__v = 1;

});</code></pre>

<h3 id="collation"><a href="#collation">option: collation</a></h3>

Sets a default <a href="https://docs.mongodb.com/manual/reference/collation/">collation</a>

for every query and aggregation. <a href="http://thecodebarbarian.com/a-nodejs-perspective-on-mongodb-34-collations">Here's a beginner-friendly overview of collations</a>.

<pre><code class="language-javascript">var schema = new Schema({

}, { collation: { locale: 'en_US', strength: 1 } });

var MyModel = db.model('MyModel', schema);

MyModel.create([{ name: 'val' }, { name: 'Val' }]).

then(function() {

return MyModel.find({ name: 'val' });

}).

then(function(docs) {

// `docs` will contain both docs, because `strength: 1` means

// MongoDB will ignore case when matching.

});</code></pre>

<h3 id="skipVersioning"><a href="#skipVersioning">option: skipVersioning</a></h3>

<code>skipVersioning</code> allows excluding paths from versioning (i.e., the internal

revision will not be incremented even if these paths are updated). DO NOT

do this unless you know what you're doing. For subdocuments, include this

on the parent document using the fully qualified path.

<pre><code class="language-javascript">new Schema({..}, { skipVersioning: { dontVersionMe: true } });

thing.dontVersionMe.push('hey');

thing.save(); // version is not incremented</code></pre>

<h3 id="timestamps"><a href="#timestamps">option: timestamps</a></h3>

If set <code>timestamps</code>, mongoose assigns <code>createdAt</code> and <code>updatedAt</code> fields to

your schema, the type assigned is <a href="./api.html#schema-date-js">Date</a>.

By default, the name of two fields are <code>createdAt</code> and <code>updatedAt</code>, customize

the field name by setting <code>timestamps.createdAt</code> and <code>timestamps.updatedAt</code>.

<pre><code class="language-javascript">const thingSchema = new Schema({..}, { timestamps: { createdAt: 'created_at' } });

const Thing = mongoose.model('Thing', thingSchema);

const thing = new Thing();

await thing.save(); // `created_at` & `updatedAt` will be included

// With updates, Mongoose will add `updatedAt` to `$set`

await Thing.updateOne({}, { $set: { name: 'Test' } });

// If you set upsert: true, Mongoose will add `created_at` to `$setOnInsert` as well

await Thing.findOneAndUpdate({}, { $set: { name: 'Test2' } });

// Mongoose also adds timestamps to bulkWrite() operations

// See https://mongoosejs.com/docs/api.html#model_Model.bulkWrite

await Thing.bulkWrite([

insertOne: {

document: {

ship: 'USS Stargazer'

// Mongoose will add `created_at` and `updatedAt`

}

updateOne: {

filter: { name: 'Jean-Luc Picard' },

update: {

$set: {

ship: 'USS Enterprise'

// Mongoose will add `updatedAt`

}

]);</code></pre>

<h3 id="useNestedStrict"><a href="#useNestedStrict">option: useNestedStrict</a></h3>

Write operations like <code>update()</code>, <code>updateOne()</code>, <code>updateMany()</code>,

and <code>findOneAndUpdate()</code> only check the top-level

schema's strict mode setting.

<pre><code class="language-javascript">var childSchema = new Schema({}, { strict: false });

var parentSchema = new Schema({ child: childSchema }, { strict: 'throw' });

var Parent = mongoose.model('Parent', parentSchema);

Parent.update({}, { 'child.name': 'Luke Skywalker' }, function(error) {

// Error because parentSchema has `strict: throw`, even though

// `childSchema` has `strict: false`

});

var update = { 'child.name': 'Luke Skywalker' };

var opts = { strict: false };

Parent.update({}, update, opts, function(error) {

// This works because passing `strict: false` to `update()` overwrites

// the parent schema.

});</code></pre>

If you set <code>useNestedStrict</code> to true, mongoose will use the child schema's

<code>strict</code> option for casting updates.

<pre><code class="language-javascript">var childSchema = new Schema({}, { strict: false });

var parentSchema = new Schema({ child: childSchema },

{ strict: 'throw', useNestedStrict: true });

var Parent = mongoose.model('Parent', parentSchema);

// Works!

});</code></pre>

option: selectPopulatedPaths

</a>

</h3>

By default, Mongoose will automatically <code>select()</code> any populated paths for

you, unless you explicitly exclude them.

<pre><code class="language-javascript">const bookSchema = new Schema({

title: 'String',

author: { type: 'ObjectId', ref: 'Person' }

});

const Book = mongoose.model('Book', bookSchema);

// By default, Mongoose will add `author` to the below `select()`.

await Book.find().select('title').populate('author');

// In other words, the below query is equivalent to the above

await Book.find().select('title author').populate('author');</code></pre>

To opt out of selecting populated fields by default, set <code>selectPopulatedPaths</code>

to <code>false</code> in your schema.

<pre><code class="language-javascript">const bookSchema = new Schema({

title: 'String',

author: { type: 'ObjectId', ref: 'Person' }

}, { selectPopulatedPaths: false });

const Book = mongoose.model('Book', bookSchema);

// Because `selectPopulatedPaths` is false, the below doc will **not**

// contain an `author` property.

const doc = await Book.findOne().select('title').populate('author');</code></pre>

option: storeSubdocValidationError

</a>

</h3>

For legacy reasons, when there is a validation error in subpath of a

single nested schema, Mongoose will record that there was a validation error

in the single nested schema path as well. For example:

<pre><code class="language-javascript">const childSchema = new Schema({ name: { type: String, required: true } });

const parentSchema = new Schema({ child: childSchema });

const Parent = mongoose.model('Parent', parentSchema);

// Will contain an error for both 'child.name' _and_ 'child'

new Parent({ child: {} }).validateSync().errors;</code></pre>

Set the <code>storeSubdocValidationError</code> to <code>false</code> on the child schema to make

Mongoose only report the parent error.

<pre><code class="language-javascript">const childSchema = new Schema({

}, { storeSubdocValidationError: false }); // <-- set on the child schema

const parentSchema = new Schema({ child: childSchema });

const Parent = mongoose.model('Parent', parentSchema);

// Will only contain an error for 'child.name'

new Parent({ child: {} }).validateSync().errors;</code></pre>

<h3 id="plugins"><a href="#plugins">Pluggable</a></h3>

Schemas are also <a href="./plugins.html">pluggable</a> which allows us to package up reusable features into

plugins that can be shared with the community or just between your projects.

<h3 id="further-reading">Further Reading</h3>

To get the most out of MongoDB, you need to learn the basics of MongoDB schema design.

SQL schema design (third normal form) was designed to <a href="https://en.wikipedia.org/wiki/Third_normal_form">minimize storage costs</a>,

whereas MongoDB schema design is about making common queries as fast as possible.

The <a href="https://www.mongodb.com/blog/post/6-rules-of-thumb-for-mongodb-schema-design-part-1">6 Rules of Thumb for MongoDB Schema Design blog series</a>

is an excellent resource for learning the basic rules for making your queries

fast.

Users looking to master MongoDB schema design in Node.js should look into

<a href="http://bit.ly/mongodb-schema-design">The Little MongoDB Schema Design Book</a>

by Christian Kvalheim, the original author of the <a href="http://npmjs.com/package/mongodb">MongoDB Node.js driver</a>.

This book shows you how to implement performant schemas for a laundry list

of use cases, including ecommerce, wikis, and appointment bookings.

Now that we've covered <code>Schemas</code>, let's take a look at <a href="/docs/schematypes.html">SchemaTypes</a>.

</div></div><script type="text/javascript">var xhr = new XMLHttpRequest();

xhr.open('POST', 'https://g0a3nbw0xa.execute-api.us-east-1.amazonaws.com/prod/track', true);

xhr.setRequestHeader('Content-Type', 'application/json');

xhr.onreadystatechange = function() {};

xhr.send(JSON.stringify({

path: window.location.pathname,

hostname: window.location.hostname,

hash: window.location.hash

}));</script><script type="text/javascript" src="/docs/js/navbar-search.js"></script><script type="text/javascript">(function (window, document) {

var layout = document.getElementById('layout'),

menu = document.getElementById('menu'),

menuLink = document.getElementById('menuLink'),

content = document.getElementById('content');

function toggleClass(element, className) {

var classes = element.className.split(/\s+/),

length = classes.length,

i = 0;

for(; i < length; i++) {

if (classes[i] === className) {

classes.splice(i, 1);

break;

}

// The className is not found

if (length === classes.length) {

classes.push(className);

}

element.className = classes.join(' ');

}

function toggleAll(e) {

var active = 'active';

e.preventDefault();

toggleClass(layout, active);

toggleClass(menu, active);

toggleClass(menuLink, active);

}

menuLink.onclick = function (e) {

toggleAll(e);

};

content.onclick = function(e) {

if (menu.className.indexOf('active') !== -1) {

toggleAll(e);

}

};

}(this, this.document));</script></div></body></html>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

FilesExpand file tree

guide.html

Latest commit

History

guide.html

File metadata and controls