mongoose/docs/guide.html at 5.2 · JavaScriptBach/mongoose

History

733 lines (660 loc) · 63 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

<!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.1.8-pre: 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"></head><body><div id="layout"><div id="mobile-menu"><a id="menuLink" href="#menu" class="menu-link"></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 id="logo-container" class="pure-menu-heading"><a href="/"><img id="logo" src="/docs/images/mongoose5_62x30_transparent.png">mongoose</a></div><ul class="pure-menu-list"><li class="pure-menu-horizontal pure-menu-item pure-menu-has-children pure-menu-allow-hover version"><a href="#" class="pure-menu-link">Version 5.1.8-pre</a><ul class="pure-menu-children"><li class="pure-menu-item"><a href="/docs/4.x" class="pure-menu-link">Version 4.13.14</a></li><li class="pure-menu-item"><a href="/docs/3.8.x" class="pure-menu-link">Version 3.8.40</a></li></ul></li><li class="pure-menu-item"><a href="/docs/index.html" class="pure-menu-link">Quick Start</a></li><li class="pure-menu-item"><a href="/docs/guides.html" class="pure-menu-link">Guides</a></li><li class="pure-menu-item sub-item"><a href="/docs/guide.html" class="pure-menu-link">Schemas</a></li><li class="pure-menu-item sub-item"><a href="/docs/schematypes.html" class="pure-menu-link">SchemaTypes</a></li><li class="pure-menu-item sub-item"><a href="/docs/connections.html" class="pure-menu-link">Connections</a></li><li class="pure-menu-item sub-item"><a href="/docs/models.html" class="pure-menu-link">Models</a></li><li class="pure-menu-item sub-item"><a href="/docs/documents.html" class="pure-menu-link">Documents</a></li><li class="pure-menu-item sub-item"><a href="/docs/subdocs.html" class="pure-menu-link">Subdocuments</a></li><li class="pure-menu-item sub-item"><a href="/docs/queries.html" class="pure-menu-link">Queries</a></li><li class="pure-menu-item sub-item"><a href="/docs/validation.html" class="pure-menu-link">Validation</a></li><li class="pure-menu-item sub-item"><a href="/docs/middleware.html" class="pure-menu-link">Middleware</a></li><li class="pure-menu-item sub-item"><a href="/docs/populate.html" class="pure-menu-link">Populate</a></li><li class="pure-menu-item sub-item"><a href="/docs/discriminators.html" class="pure-menu-link">Discriminators</a></li><li class="pure-menu-item sub-item"><a href="/docs/plugins.html" class="pure-menu-link">Plugins</a></li><li class="pure-menu-item"><a href="/docs/api.html" class="pure-menu-link">API</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#mongoose_Mongoose" class="pure-menu-link">Mongoose</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Schema" class="pure-menu-link">Schema</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Connection" class="pure-menu-link">Connection</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Document" class="pure-menu-link">Document</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Model" class="pure-menu-link">Model</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Query" class="pure-menu-link">Query</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Aggregate" class="pure-menu-link">Aggregate</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Schematype" class="pure-menu-link">SchemaType</a></li><li class="pure-menu-item sub-item"><a href="/docs/api.html#Virtualtype" class="pure-menu-link">VirtualType</a></li><li class="pure-menu-item"><a href="/docs/compatibility.html" class="pure-menu-link">Version Compatibility</a></li><li class="pure-menu-item"><a href="/docs/faq.html" class="pure-menu-link">FAQ</a></li><li class="carbon-ad"><script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?zoneid=1673&serve=C6AILKT&placement=mongoosejscom" id="_carbonads_js"></script></li></ul></div></div><div class="container"><div id="content"><h2>Schemas</h2><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="https://github.com/Automattic/mongoose/blob/master/migrating_to_5.md">migration guide</a>.

</div><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="lang-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>String</li>

<li>Number</li>

<li>Buffer</li>

<li>Boolean</li>

<li>Mixed</li>

<li>ObjectId</li>

<li>Array</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="lang-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="lang-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="lang-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>

Adding static methods to a <code>Model</code> is simple as well. Continuing with our

<code>animalSchema</code>:

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

animalSchema.statics.findByName = function(name, cb) {

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

};

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

Animal.findByName('fido', function(err, animals) {

console.log(animals);

});

</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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-javascript">console.log(axl.fullName); // Axl Rose

</code></pre>

If you use <code>toJSON()</code> or <code>toObject()</code> (or use <code>JSON.stringify()</code> on a

mongoose document) mongoose will not include virtuals by default.

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

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

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="lang-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="lang-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>

<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="lang-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="#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="#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="#validateBeforeSave">validateBeforeSave</a></li>

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

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

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

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

</ul>

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

At application startup, Mongoose sends a <a href="https://docs.mongodb.com/manual/reference/method/db.collection.createIndex/#db.collection.createIndex"><code>createIndex</code> command</a> for each index declared in your <code>Schema</code>. As of Mongoose v3, indexes are created in the <code>background</code> by default. If you wish to disable the auto-creation feature and manually handle when indexes are created, set your <code>Schema</code>s <code>autoIndex</code> option to <code>false</code> and use the <a href="./api.html#model_Model.ensureIndexes">ensureIndexes</a> method on your model.

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

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

Clock.ensureIndexes(callback);

</code></pre>

<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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-javascript">var schema = new Schema({ name: String, inventory: {} });

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

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

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

Character.findOne({ name: 'Frodo' }, function(err, character) {

console.log(character); // { name: 'Frodo', inventory: { ringOfPower: 1 }}

});

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

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

Character.findOne({ name: 'Sam' }, function(err, character) {

console.log(character); // { name: 'Sam' }

});

</code></pre>

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

will then store empty objects.

<pre><code class="lang-javascript">var schema = new Schema({ name: String, inventory: {} }, { minimize: false });

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

// will store `inventory` if empty

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

Character.findOne({ name: 'Sam' }, function(err, character) {

console.log(character); // { name: 'Sam', inventory: {}}

});

</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="lang-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="lang-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="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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-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="lang-javascript">var schema = new Schema({ name: 'string' });

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

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

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

// customized versionKey

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

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

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

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

</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="lang-javascript">new Schema({..}, { versionKey: false });

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

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

thing.save(); // { name: 'no versioning please' }

</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="lang-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="lang-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="lang-javascript">var thingSchema = new Schema({..}, { timestamps: { createdAt: 'created_at' } });

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

var thing = new Thing();

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

</code></pre>

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

In mongoose 4, <code>update()</code> and <code>findOneAndUpdate()</code> only check the top-level

schema's strict mode setting.

<pre><code class="lang-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="lang-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>

<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">!function(name,path,ctx){

var latest,prev=name!=='Keen'&&window.Keen?window.Keen:false;ctx[name]=ctx[name]||{ready:function(fn){var h=document.getElementsByTagName('head')[0],s=document.createElement('script'),w=window,loaded;s.onload=s.onerror=s.onreadystatechange=function(){if((s.readyState&&!(/^c|loade/.test(s.readyState)))||loaded){return}s.onload=s.onreadystatechange=null;loaded=1;latest=w.Keen;if(prev){w.Keen=prev}else{try{delete w.Keen}catch(e){w.Keen=void 0}}ctx[name]=latest;ctx[name].ready(fn)};s.async=1;s.src=path;h.parentNode.insertBefore(s,h)}}

}('KeenAsync','https://d26b395fwzu5fz.cloudfront.net/keen-tracking-1.1.3.min.js',this);

KeenAsync.ready(function(){

// Configure a client instance

var client = new KeenAsync({

projectId: '59aad9cbc9e77c0001ce1b32',

writeKey: '4B38B0046086885E425D368BFAEAD8FD0D4F2DC2FA2F936FDE058D79508AEFAD9886BC020B96520823BB9C8241D9D9BCFDC0EF52E6033BD89D06E4B24FC13AE955896BF443406269A84DD009CEB5862DCEC944874DB2107FD648DA91ADC1E6DE'

});

client.recordEvent('pageView', {

host: window.location.host,

pathname: window.location.pathname,

hash: window.location.hash

});

});</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