Mongoose

https://mongoosejs.com/docs
Admin
Mongoose is an Object Data Modeling (ODM) library for Node.js that provides a schema-based solution...
Tokens:428,047
Snippets:3,298
Trust Score:9.6
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Start a MongoDB session with startSession()

Source: https://mongoosejs.com/docs/api/connection.html

Demonstrates starting a MongoDB session for causal consistency, retryable writes, and transactions. Requires MongoDB >= 3.6.0. The example shows how a session ensures consistent reads even from secondary replicas.

```javascript
const session = await conn.startSession();
let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
await doc.deleteOne();
// `doc` will always be null, even if reading from a replica set
// secondary. Without causal consistency, it is possible to
// get a doc back from the below query if the query reads from a
// secondary that is experiencing replication lag.
doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });
```

--------------------------------

### model example

Source: https://mongoosejs.com/docs/api/aggregate.html

Gets or sets the model associated with the aggregate. The example shows checking the current model and changing it.

```javascript
const aggregate = MyModel.aggregate([{ $match: { answer: 42 } }]);
aggregate.model() === MyModel; // true

// Change the model. There's rarely any reason to do this.
aggregate.model(SomeOtherModel);
aggregate.model() === SomeOtherModel; // true
```

--------------------------------

### Connection.prototype.get() example

Source: https://mongoosejs.com/docs/api/connection.html

Gets the value of the option `key`. Equivalent to `conn.options[key]`.

```javascript
conn.get('test'); // returns the 'test' value
```

--------------------------------

### Set and get connection options

Source: https://mongoosejs.com/docs/api/connection.html

Demonstrates setting and getting connection options. The set() method is equivalent to conn.options[key] = val, and get() retrieves the value. Supported options include maxTimeMS and debug.

```javascript
conn.set('test', 'foo');
conn.get('test'); // 'foo'
conn.options.test; // 'foo'
```

--------------------------------

### option example

Source: https://mongoosejs.com/docs/api/aggregate.html

Sets arbitrary options for the aggregation, such as allowDiskUse. The example shows setting the option and accessing it via the options property.

```javascript
const agg = Model.aggregate(..).option({ allowDiskUse: true }); // Set the `allowDiskUse` option
agg.options; // `{ allowDiskUse: true }`
```

--------------------------------

### Install Mongoose with npm

Source: https://mongoosejs.com/docs/index.html

Install Mongoose in your project using npm. Requires MongoDB and Node.js to be installed first.

```bash
npm install mongoose
```

--------------------------------

### Install mongodb-client-encryption package

Source: https://mongoosejs.com/docs/field-level-encryption.html

Install MongoDB's official package for setting up encryption keys. Required for manual field level encryption.

```bash
npm install mongodb-client-encryption
```

--------------------------------

### Connection.prototype.dropDatabase() example

Source: https://mongoosejs.com/docs/api/connection.html

Deletes the entire database, including all collections, documents, and indexes. The example creates a connection to 'mydb' and then drops the database.

```javascript
const conn = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
// Deletes the entire 'mydb' database
await conn.dropDatabase();
```

--------------------------------

### Get and set schema options with Schema.prototype.get()

Source: https://mongoosejs.com/docs/api/schema.html

Gets and sets a schema option using `schema.get()` and `schema.set()`. The example shows getting the 'strict' option, setting it to false, and getting it again.

```javascript
schema.get('strict'); // true
schema.set('strict', false);
schema.get('strict'); // false
```

--------------------------------

### populate() example: populate multiple paths and query options

Source: https://mongoosejs.com/docs/api/document.html

Shows how to use populate() on an existing document to pull in referenced docs. Includes populating multiple paths, sorting, handling deleted references, and using a select projection.

```javascript
// Given a document, `populate()` lets you pull in referenced docs
await doc.populate([
  'stories',
  { path: 'fans', sort: { name: -1 } }
]);
doc.populated('stories'); // Array of ObjectIds
doc.stories[0].title; // 'Casino Royale'
doc.populated('fans'); // Array of ObjectIds

// If the referenced doc has been deleted, `populate()` will
// remove that entry from the array.
await Story.delete({ title: 'Casino Royale' });
await doc.populate('stories'); // Empty array

// You can also pass additional query options to `populate()`,
// like projections:
await doc.populate('fans', '-email');
doc.fans[0].email // undefined because of 2nd param `select`
```

--------------------------------

### explain() example

Source: https://mongoosejs.com/docs/api/aggregate.html

Executes the aggregation with explain, returning execution plan details.

```javascript
Model.aggregate(..).explain()
```

--------------------------------

### Model.prototype.$model() example

Source: https://mongoosejs.com/docs/api/model.html

Shows how to use Model.prototype.$model() to get the model instance that created a document, or to get a model by name. The example demonstrates that $model() returns the same model when no name is given, and can be used to call static methods like findById on another model.

```javascript
const doc = new Tank({});
doc.$model() === Tank; // true
await doc.$model('User').findById(id);
```

--------------------------------

### Query.prototype.getPopulatedPaths() - get populated paths

Source: https://mongoosejs.com/docs/api/query.html

Gets a list of paths to be populated by this query. In this example, it returns ['author'] when called inside a pre('findOne') hook.

```javascript
 bookSchema.pre('findOne', function() {
   let keys = this.getPopulatedPaths(); // ['author']
 });
 ...
 Book.findOne({}).populate('author');
```

--------------------------------

### Query.cursor() examples

Source: https://mongoosejs.com/docs/api/query.html

Shows three ways to use a cursor: as a stream, with .next() and callback, and with async iteration.

```javascript
// There are 2 ways to use a cursor. First, as a stream:
Thing.
  find({ name: /^hello/ }).
  cursor().
  on('data', function(doc) { console.log(doc); }).
  on('end', function() { console.log('Done!'); });

// Or you can use `.next()` to manually get the next doc in the stream.
// `.next()` returns a promise, so you can use promises or callbacks.
const cursor = Thing.find({ name: /^hello/ }).cursor();
cursor.next(function(error, doc) {
  console.log(doc);
});

// Because `.next()` returns a promise, you can use co
// to easily iterate through all documents without loading them
// all into memory.
const cursor = Thing.find({ name: /^hello/ }).cursor();
for (let doc = await cursor.next(); doc != null; doc = await cursor.next()) {
  console.log(doc);
}
```

--------------------------------

### Schema.prototype.alias() example

Source: https://mongoosejs.com/docs/api/schema.html

Adds an alias for a path, making getting or setting the alias equivalent to getting or setting the real path. Shows that saving the document persists the value under the real path.

```javascript
const toySchema = new Schema({ n: String });

// Make 'name' an alias for 'n'
toySchema.alias('n', 'name');

const Toy = mongoose.model('Toy', toySchema);
const turboMan = new Toy({ n: 'Turbo Man' });

turboMan.name; // 'Turbo Man'
turboMan.n; // 'Turbo Man'

turboMan.name = 'Turbo Man Action Figure';
turboMan.n; // 'Turbo Man Action Figure'

await turboMan.save(); // Saves { _id: ..., n: 'Turbo Man Action Figure' }
```

--------------------------------

### Query.prototype.explain() example

Source: https://mongoosejs.com/docs/api/query.html

Sets the explain option to 'queryPlanner' and logs the detailed execution stats returned instead of the actual query result.

```javascript
const query = new Query();
const res = await query.find({ a: 1 }).explain('queryPlanner');
console.log(res);
```

--------------------------------

### Model.create() example

Source: https://mongoosejs.com/docs/api/model.html

Shows how to use Model.create() to insert one or more documents. The example demonstrates inserting a single document, multiple documents, and creating a document within a transaction, noting that options require an array as the first argument.

```javascript
// Insert one new `Character` document
await Character.create({ name: 'Jean-Luc Picard' });

// Insert multiple new `Character` documents
await Character.create([{ name: 'Will Riker' }, { name: 'Geordi LaForge' }]);

// Create a new character within a transaction. Note that you **must**
// pass an array as the first parameter to `create()` if you want to
// specify options.
await Character.create([{ name: 'Jean-Luc Picard' }], { session });
```

--------------------------------

### Aggregate.prototype.session() - Set session for aggregation

Source: https://mongoosejs.com/docs/api/aggregate.html

Sets the session for this aggregation, useful for transactions. The example starts a session and passes it to the aggregate.

```javascript
const session = await Model.startSession();
await Model.aggregate(..).session(session);
```

--------------------------------

### Document.prototype.$init()

Source: https://mongoosejs.com/docs/api/document.html

Alias for `.init`

```APIDOC
## Document.prototype.$init()

### Description
Alias for `.init`

### Method
N/A (Document method)

### Endpoint
N/A (Document method)

### Parameters
None
```

--------------------------------

### Express GET route using lean()

Source: https://mongoosejs.com/docs/tutorials/lean.html

Use this pattern for GET routes that return query results without modification. The lean() method returns plain JavaScript objects, so virtuals and getters are not included. This example does not modify the person document.

```javascript
// As long as you don't need any of the Person model's virtuals or getters,
// you can use `lean()`.
app.get('/person/:id', function(req, res) {
  Person.findOne({ _id: req.params.id }).lean().
    then(person => res.json({ person })).
    catch(error => res.json({ error: error.message }));
});
```

--------------------------------

### Create a Session with startSession()

Source: https://mongoosejs.com/docs/transactions.html

Create a session using Mongoose#startSession or Connection#startSession(). The first uses the default connection, the second uses a custom connection.

```javascript
// Using Mongoose's default connection
const session = await mongoose.startSession();

// Using custom connection
const db = await mongoose.createConnection(mongodbUri).asPromise();
const session = await db.startSession();
```

--------------------------------

### Query.prototype.sanitizeProjection() example

Source: https://mongoosejs.com/docs/api/query.html

Shows how sanitizeProjection(true) forces projection values to numbers and prevents using '+' to override fields with select: false. Without it, string projections starting with '$' can leak sensitive data. The example demonstrates the behavior with and without the option.

```javascript
const userSchema = new Schema({
  name: String,
  password: { type: String, select: false }
});
const UserModel = mongoose.model('User', userSchema);
const { _id } = await UserModel.create({ name: 'John', password: 'secret' })

// The MongoDB server has special handling for string values that start with '$'
// in projections, which can lead to unexpected leaking of sensitive data.
let doc = await UserModel.findOne().select({ name: '$password' });
doc.name; // 'secret'
doc.password; // undefined

// With `sanitizeProjection`, Mongoose forces all projection values to be numbers
doc = await UserModel.findOne().sanitizeProjection(true).select({ name: '$password' });
doc.name; // 'John'
doc.password; // undefined

// By default, Mongoose supports projecting in `password` using `+password`
doc = await UserModel.findOne().select('+password');
doc.password; // 'secret'

// With `sanitizeProjection`, Mongoose prevents projecting in `password` and other
// fields that have `select: false` in the schema.
doc = await UserModel.findOne().sanitizeProjection(true).select('+password');
doc.password; // undefined
```

--------------------------------

### facet() example

Source: https://mongoosejs.com/docs/api/aggregate.html

Combines multiple aggregation pipelines using $facet, producing multiple output documents.

```javascript
const res = await Model.aggregate().facet({
  books: [{ groupBy: '$author' }],
  price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }]
});

// Output: { books: [...], price: [{...}, {...}] }
```

--------------------------------

### Query.prototype.getPopulatedPaths() - deep populate example

Source: https://mongoosejs.com/docs/api/query.html

Gets a list of paths to be populated by this query. For deep populate, it returns nested paths like ['level2', 'level2.level3'].

```javascript
 // Deep populate
 const q = L1.find().populate({
   path: 'level2',
   populate: { path: 'level3' }
 });
 q.getPopulatedPaths(); // ['level2', 'level2.level3']
```

--------------------------------

### Connection.prototype.useDb() example

Source: https://mongoosejs.com/docs/api/connection.html

Switches to a different database using the same connection pool. With useCache: true, repeated calls with the same name return the same connection instance.

```javascript
// Connect to `initialdb` first
const conn = await mongoose.createConnection('mongodb://127.0.0.1:27017/initialdb').asPromise();

// Creates an un-cached connection to `mydb`
const db = conn.useDb('mydb');
// Creates a cached connection to `mydb2`. All calls to `conn.useDb('mydb2', { useCache: true })` will return the same
// connection instance as opposed to creating a new connection instance
const db2 = conn.useDb('mydb2', { useCache: true });
```

--------------------------------

### Mongoose.prototype.sanitizeFilter() example

Source: https://mongoosejs.com/docs/api/mongoose.html

Sanitizes query filters against query selector injection attacks by wrapping any nested objects that have a property whose name starts with `$` in a `$eq`.

```javascript
const obj = { username: 'val', pwd: { $ne: null } };
sanitizeFilter(obj);
obj; // { username: 'val', pwd: { $eq: { $ne: null } } });
```

--------------------------------

### Register a plugin on a connection

Source: https://mongoosejs.com/docs/api/connection.html

Demonstrates registering a plugin on a connection and verifying it is applied to models created on that connection. The plugin logs 'Applied' when a model is created, and the example checks the plugins array length.

```javascript
const db = mongoose.createConnection('mongodb://127.0.0.1:27017/mydb');
db.plugin(() => console.log('Applied'));
db.plugins.length; // 1

db.model('Test', new Schema({})); // Prints "Applied"
```

--------------------------------

### Access parent of subdoc with parent()

Source: https://mongoosejs.com/docs/subdocs.html

Use `parent()` to get the immediate parent of a subdocument. The example shows that `parent()` returns the direct parent, not the top-level document.

```javascript
const schema = new Schema({
  docArr: [{ name: String }],
  singleNested: new Schema({ name: String })
});
const Model = mongoose.model('Test', schema);

const doc = new Model({
  docArr: [{ name: 'foo' }],
  singleNested: { name: 'bar' }
});

doc.singleNested.parent() === doc; // true
doc.docArr[0].parent() === doc; // true
```

--------------------------------

### Set a schema option with Schema.prototype.set()

Source: https://mongoosejs.com/docs/api/schema.html

Sets a schema option. If no value is passed, the option is reset to its default. The example shows getting and setting the `strict` option.

```javascript
schema.set('strict'); // 'true' by default
schema.set('strict', false); // Sets 'strict' to false
schema.set('strict'); // 'false'
```

--------------------------------

### Get required paths with Schema.prototype.requiredPaths()

Source: https://mongoosejs.com/docs/api/schema.html

Returns an array of path strings that are required by the schema. The example shows that `requiredPaths()` returns the required paths in alphabetical order.

```javascript
const s = new Schema({
  name: { type: String, required: true },
  age: { type: String, required: true },
  notes: String
});
s.requiredPaths(); // [ 'age', 'name' ]
```

--------------------------------

### Virtual populate setup

Source: https://mongoosejs.com/docs/populate.html

Enable virtual population by defining a virtual property with `ref`, `localField`, and `foreignField` options. This allows populating the author's posts even though they are not stored on the author document.

```javascript
// Specifying a virtual with a `ref` property is how you enable virtual
// population
AuthorSchema.virtual('posts', {
  ref: 'BlogPost',
  localField: '_id',
  foreignField: 'author'
});

const Author = mongoose.model('Author', AuthorSchema, 'Author');
const BlogPost = mongoose.model('BlogPost', BlogPostSchema, 'BlogPost');
```

--------------------------------

### List databases with listDatabases()

Source: https://mongoosejs.com/docs/api/connection.html

Shows how to list all databases using the `listDatabases()` helper, which returns an object with a `databases` array.

```javascript
const { databases } = await mongoose.connection.listDatabases();
databases; // [{ name: 'mongoose_test', sizeOnDisk: 0, empty: false }]
```

--------------------------------

### Get Mongoose version with npm list

Source: https://mongoosejs.com/docs/check-version.html

Shows the installed Mongoose npm package version. Helpful for identifying multiple installed versions. Other package managers support similar functions: yarn list --pattern "mongoose" and pnpm list "mongoose".

```bash
$ npm list mongoose
test@ /path/to/test
└── mongoose@7.0.3 
```

--------------------------------

### Equivalent JSON doc and query builder examples

Source: https://mongoosejs.com/docs/queries.html

Two equivalent ways to build the same query: with a JSON document and with the query builder chaining syntax. Both use `limit()`, `sort()`, `select()`, and `exec()`.

```javascript
// With a JSON doc
await Person.
  find({
    occupation: /host/,
    'name.last': 'Ghost',
    age: { $gt: 17, $lt: 66 },
    likes: { $in: ['vaporizing', 'talking'] }
  }).
  limit(10).
  sort({ occupation: -1 }).
  select({ name: 1, occupation: 1 }).
  exec();
```

```javascript
// Using query builder
await Person.
  find({ occupation: /host/ }).
  where('name.last').equals('Ghost').
  where('age').gt(17).lt(66).
  where('likes').in(['vaporizing', 'talking']).
  limit(10).
  sort('-occupation').
  select('name occupation').
  exec();
```

--------------------------------

### Skip/Limit Pagination with find() and countDocuments()

Source: https://mongoosejs.com/docs/queries.html

Skip/limit pagination example using sort(), skip(), and limit() to retrieve a page and countDocuments() to get the total number of matching documents.

```javascript
const filter = { active: true };
const options = { sort: { createdAt: -1 }, skip: 20, limit: 20 };

const [documents, total] = await Promise.all([
  User.find(filter, null, options),
  User.countDocuments(filter)
]);
```

--------------------------------

### populated() example: get _id(s) used during population

Source: https://mongoosejs.com/docs/api/document.html

Shows how to use populated() to retrieve the _id(s) used during population of a given path. Returns undefined if the path was not populated.

```javascript
const doc = await Model.findOne().populate('author');

console.log(doc.author.name); // Dr.Seuss
console.log(doc.populated('author')); // '5144cf8050f071d979c118a7'
```

--------------------------------

### Populate a path with Query.prototype.populate()

Source: https://mongoosejs.com/docs/api/query.html

Shows how to use `Query.prototype.populate()` to populate a path with a string or an object specifying `match` and `sort` options. The `match` and `sort` options apply to the Author model, not the Book model, and do not affect which documents are in `books`.

```javascript
let book = await Book.findOne().populate('authors');
book.title; // 'Node.js in Action'
book.authors[0].name; // 'TJ Holowaychuk'
book.authors[1].name; // 'Nathan Rajlich'

let books = await Book.find().populate({
  path: 'authors',
  // `match` and `sort` apply to the Author model,
  // not the Book model. These options do not affect
  // which documents are in `books`, just the order and
  // contents of each book document's `authors`.
  match: { name: new RegExp('.*h.*', 'i') },
  sort: { name: -1 }
});
books[0].title; // 'Node.js in Action'
// Each book's `authors` are sorted by name, descending.
books[0].authors[0].name; // 'TJ Holowaychuk'
books[0].authors[1].name; // 'Marc Harter'

books[1].title; // 'Professional AngularJS'
// Empty array, no authors' name has the letter 'h'
books[1].authors; // []
```

--------------------------------

### SchemaBoolean.convertToTrue - Add custom true values

Source: https://mongoosejs.com/docs/api/schemaboolean.html

Configure which values get casted to true. The example adds 'affirmative' to the convertToTrue set, so that value becomes true instead of undefined.

```javascript
const M = mongoose.model('Test', new Schema({ b: Boolean }));
new M({ b: 'affirmative' }).b; // undefined
mongoose.Schema.Types.Boolean.convertToTrue.add('affirmative');
new M({ b: 'affirmative' }).b; // true
```

--------------------------------

### Connect with mongoose.connect()

Source: https://mongoosejs.com/docs/api/mongoose.html

Shows how to open the default Mongoose connection with a URI, replica set URIs, options, and an await that throws a MongooseServerSelectionError if the server is unreachable.

```javascript
mongoose.connect('mongodb://user:pass@127.0.0.1:port/database');

// replica sets
const uri = 'mongodb://user:pass@127.0.0.1:port,anotherhost:port,yetanother:port/mydatabase';
mongoose.connect(uri);

// with options
mongoose.connect(uri, options);

// Using `await` throws "MongooseServerSelectionError: Server selection timed out after 30000 ms"
// if Mongoose can't connect.
const uri = 'mongodb://nonexistent.domain:27000';
await mongoose.connect(uri);
```

--------------------------------

### SchemaBoolean.convertToFalse - Add custom false values

Source: https://mongoosejs.com/docs/api/schemaboolean.html

Configure which values get casted to false. The example adds 'nay' to the convertToFalse set, so that value becomes false instead of undefined.

```javascript
const M = mongoose.model('Test', new Schema({ b: Boolean }));
new M({ b: 'nay' }).b; // undefined
mongoose.Schema.Types.Boolean.convertToFalse.add('nay');
new M({ b: 'nay' }).b; // false
```

--------------------------------

### Model.createCollection() example

Source: https://mongoosejs.com/docs/api/model.html

Creates the collection for the model explicitly. Use this when no indexes are specified and you need the collection to exist before documents are created, such as before starting a transaction. The promise resolves with the collection object.

```javascript
const userSchema = new Schema({ name: String })
const User = mongoose.model('User', userSchema);

User.createCollection().then(function(collection) {
  console.log('Collection is created!');
});
```

--------------------------------

### Using mongoose.Schema constructor

Source: https://mongoosejs.com/docs/api/mongoose.html

Shows how to access the Schema constructor from the mongoose instance and create a schema.

```javascript
const mongoose = require('mongoose');
const Schema = mongoose.Schema;
const CatSchema = new Schema(..);
```

--------------------------------

### Define schema and create document

Source: https://mongoosejs.com/docs/guide.html

Defines a Mongoose schema with nested `name` fields, compiles a model, and creates a document instance. This is the base setup for the virtuals examples that follow.

```javascript
// define a schema
const personSchema = new Schema({
  name: {
    first: String,
    last: String
  }
});

// compile our model
const Person = mongoose.model('Person', personSchema);

// create a document
const axl = new Person({
  name: { first: 'Axl', last: 'Rose' }
});
```

--------------------------------

### Full loadClass() TypeScript example

Source: https://mongoosejs.com/docs/typescript/statics-and-methods.html

Complete example combining all previous snippets: imports, interface, class with typed methods and getter workaround, schema creation, type definitions, model creation, and usage.

```typescript
import { Model, Schema, model, HydratedDocument } from 'mongoose';

interface RawDocType {
  property1: string;
}

class MyClass {
  myMethod(this: MyCombinedDocument) {
    return this.property1;
  }

  static myStatic(this: MyCombinedModel) {
    return 42;
  }

  get myVirtual() {
    const self = this as MyCombinedDocument;
    return `Hello ${self.property1}`;
  }
}

const schema = new Schema<RawDocType>({ property1: String });
schema.loadClass(MyClass);

type MyCombinedModel = Model<
  RawDocType,
  {},
  Pick<MyClass, 'myMethod'>,
  Pick<MyClass, 'myVirtual'>
> & Pick<typeof MyClass, 'myStatic'>;

type MyCombinedDocument = HydratedDocument<
  RawDocType,
  Pick<MyClass, 'myMethod'>,
  {},
  Pick<MyClass, 'myVirtual'>
>;

const MyModel = model<RawDocType, MyCombinedModel>(
  'MyClass',
  schema
);

const doc = new MyModel({ property1: 'world' });
doc.myMethod(); 
MyModel.myStatic(); 
console.log(doc.myVirtual); 
```

--------------------------------

### SchemaBoolean.set() - Set default option for all booleans

Source: https://mongoosejs.com/docs/api/schemaboolean.html

Set a default option for all Boolean instances. The example sets the default value to false, so new documents without the field get false.

```javascript
// Make all booleans have `default` of false.
mongoose.Schema.Types.Boolean.set('default', false);

const Order = mongoose.model('Order', new Schema({ isPaid: Boolean }));
new Order({ }).isPaid; // false
```

--------------------------------

### Connection.prototype.startSession()

Source: https://mongoosejs.com/docs/api/connection.html

Starts a MongoDB session for transactions and causal consistency.

```APIDOC
## Connection.prototype.startSession([options])

### Description
Starts a MongoDB session for benefits like causal consistency, retryable writes, and transactions. Requires MongoDB >= 3.6.0.

### Parameters
- **options** (object) - Optional - See the MongoDB driver options.
  - **options.causalConsistency** (boolean) - Optional - Defaults to `true`. Set to `false` to disable causal consistency.

### Returns
- **Promise<ClientSession>** - A promise that resolves to a MongoDB driver `ClientSession`.

### Example
```javascript
const session = await conn.startSession();
let doc = await Person.findOne({ name: 'Ned Stark' }, null, { session });
await doc.deleteOne();
// `doc` will always be null, even if reading from a replica set
// secondary. Without causal consistency, it is possible to
// get a doc back from the below query if the query reads from a
// secondary that is experiencing replication lag.
doc = await Person.findOne({ name: 'Ned Stark' }, null, { session, readPreference: 'secondary' });
```
```

--------------------------------

### MongooseMap.prototype.set() key constraints example

Source: https://mongoosejs.com/docs/api/map.html

Shows valid and invalid keys for MongooseMap.set(). Only string keys are allowed; object and number keys throw errors. Keys cannot start with '$' or contain dots.

```javascript
doc.myMap.set('test', 42); // works
doc.myMap.set({ obj: 42 }, 42); // Throws "Mongoose maps only support string keys"
doc.myMap.set(10, 42); // Throws "Mongoose maps only support string keys"
doc.myMap.set("$test", 42); // Throws "Mongoose maps do not support keys that start with "$", got "$test""
```

--------------------------------

### Access top-level document with ownerDocument()

Source: https://mongoosejs.com/docs/subdocs.html

For deeply nested subdocuments, use `ownerDocument()` to get the top-level document. The example shows that `parent()` returns the immediate parent, while `ownerDocument()` returns the top-level document.

```javascript
const schema = new Schema({
  level1: new Schema({
    level2: new Schema({
      test: String
    })
  })
});
const Model = mongoose.model('Test', schema);

const doc = new Model({ level1: { level2: 'test' } });

doc.level1.level2.parent() === doc; // false
doc.level1.level2.parent() === doc.level1; // true
doc.level1.level2.ownerDocument() === doc; // true
```

--------------------------------

### Schema()

Source: https://mongoosejs.com/docs/api/schema.html

Documentation for the Schema constructor, including parameters, options, and usage examples.

```APIDOC
## `Schema()`

### Description
Creates a new Mongoose schema definition. The schema constructor accepts an optional definition object, an existing schema to copy, or an array of objects and schemas, along with optional configuration options.

### Parameters
- `[definition]` (object|Schema|Array) - Optional - Can be one of: object describing schema paths, or schema to copy, or array of objects and schemas
- `[options]` (object) - Optional - Schema options

### Options
- `autoIndex` (bool) - defaults to null (which means use the connection's autoIndex option)
- `autoCreate` (bool) - defaults to null (which means use the connection's autoCreate option)
- `bufferCommands` (bool) - defaults to true
- `bufferTimeoutMS` (number) - defaults to 10000 (10 seconds). If `bufferCommands` is enabled, the amount of time Mongoose will wait for connectivity to be established before erroring out.
- `capped` (bool | number | object) - defaults to false
- `collection` (string) - no default
- `discriminatorKey` (string) - defaults to `__t`
- `id` (bool) - defaults to true
- `_id` (bool) - defaults to true
- `minimize` (bool) - controls document#toObject behavior when called manually - defaults to true
- `read` (string) - no default
- `readConcern` (object) - defaults to null, use to set a default read concern for all queries.
- `writeConcern` (object) - defaults to null, use to override the MongoDB server's default write concern settings
- `shardKey` (object) - defaults to `null`
- `strict` (bool) - defaults to true
- `strictQuery` (bool) - defaults to false
- `strictRead` (bool or 'throw') - defaults to false. If set to `true`, fields not in the schema will be stripped when hydrating documents from MongoDB. If set to `'throw'`, an error will be thrown when a field not in the schema is encountered during document hydration.
- `toJSON` (object) - no default
- `toObject` (object) - no default
- `typeKey` (string) - defaults to 'type'
- `validateBeforeSave` (bool) - defaults to `true`
- `validateModifiedOnly` (bool) - defaults to `false`
- `versionKey` (string or object) - defaults to "__v"
- `optimisticConcurrency` (bool or string[] or { exclude: string[] }) - defaults to false. Set to true to enable optimistic concurrency for all fields. Set to a string array to enable optimistic concurrency only for the specified fields; note that this **replaces** the default array versioning behavior. Set to `{ exclude: string[] }` to enable optimistic concurrency for all fields except the specified ones; this also replaces the default array versioning. Paths may include the map wildcard `$*`, like `'settings.$*'`, to match all keys of a map.
- `collation` (object) - defaults to null (which means use no collation)
- `timeseries` (object) - defaults to null (which means this schema's collection won't be a timeseries collection)
- `selectPopulatedPaths` (boolean) - defaults to `true`
- `skipVersioning` (object) - paths to exclude from versioning
- `timestamps` (object or boolean) - defaults to `false`. If true, Mongoose adds `createdAt` and `updatedAt` properties to your schema and manages those properties for you.
- `pluginTags` (array of strings) - defaults to `undefined`. If set and plugin called with `tags` option, will only apply that plugin to schemas with a matching tag.
- `virtuals` (object) - virtuals to define, alias for `.virtual`
- `[collectionOptions]` (object) - object with options passed to `createCollection()` when calling `Model.createCollection()` or `autoCreate` set to true.
- `[encryptionType]` (string) - the encryption type for the schema. Valid options are `csfle` or `queryableEncryption`. See https://mongoosejs.com/docs/field-level-encryption.html.
- `[lean]` (boolean) - set to true to make all queries use lean by default. Defaults to false.

### Options for Nested Schemas
- `excludeIndexes` (bool) - defaults to `false`. If `true`, skip building indexes on this schema's paths.

### Example
```javascript
const child = new Schema({ name: String });
const schema = new Schema({ name: String, age: Number, children: [child] });
const Tree = mongoose.model('Tree', schema);

// setting schema options
new Schema({ name: String }, { id: false, autoIndex: false })
```

### Note
When nesting schemas, (`children` in the example above), always declare the child schema first before passing it into its parent.
```

--------------------------------

### Use Mongoose in API route

Source: https://mongoosejs.com/docs/nextjs.html

Example of using Mongoose in a Next.js Pages Router API route. Handles GET and POST requests, returning appropriate status codes and JSON responses.

```javascript
// pages/api/users.js
import dbConnect from '@/lib/mongodb';
import User from '@/models/User';

export default async function handler(req, res) {
  await dbConnect();

  if (req.method === 'GET') {
    const users = await User.find({});
    return res.status(200).json({ users });
  }

  if (req.method === 'POST') {
    const user = await User.create(req.body);
    return res.status(201).json({ user });
  }

  res.status(405).json({ error: 'Method not allowed' });
}
```

--------------------------------

### Query.prototype.toConstructor() - Creating reusable query constructor

Source: https://mongoosejs.com/docs/api/query.html

Shows how to create a reusable query constructor with `toConstructor()`. The example builds a query, converts it to a custom constructor, then uses it to narrow results and add custom prototype methods and getters without affecting global queries.

```javascript
// Create a query for adventure movies and read from the primary
// node in the replica-set unless it is down, in which case we'll
// read from a secondary node.
const query = Movie.find({ tags: 'adventure' }).read('primaryPreferred');

// create a custom Query constructor based off these settings
const Adventure = query.toConstructor();

// further narrow down our query results while still using the previous settings
await Adventure().where({ name: /^Life/ }).exec();

// since Adventure is a stand-alone constructor we can also add our own
// helper methods and getters without impacting global queries
Adventure.prototype.startsWith = function (prefix) {
  this.where({ name: new RegExp('^' + prefix) })
  return this;
}
Object.defineProperty(Adventure.prototype, 'highlyRated', {
  get: function () {
    this.where({ rating: { $gt: 4.5 }});
    return this;
  }
})
await Adventure().highlyRated.startsWith('Life').exec();
```

--------------------------------

### SchemaType.prototype.getEmbeddedSchemaType() - Get embedded type

Source: https://mongoosejs.com/docs/api/schematype.html

Returns the embedded schema type for arrays, document arrays, and maps; otherwise returns `undefined`. The example shows `undefined` for a string and the schema type for an array of strings.

```javascript
const schema = new Schema({ name: String, tags: [String] });
schema.path('name').getEmbeddedSchemaType(); // undefined
schema.path('tags').getEmbeddedSchemaType(); // SchemaString { path: 'tags', ... }
```

--------------------------------

### Create a Kitten Document

Source: https://mongoosejs.com/docs/index.html

Instantiate a new Kitten document with a name property and log the name to the console.

```javascript
const silence = new Kitten({ name: 'Silence' });
console.log(silence.name); // 'Silence'
```

--------------------------------

### Create a Band document with a map of member ObjectIds

Source: https://mongoosejs.com/docs/populate.html

Creates two Person documents and a Band document with a map of member ObjectIds. This example sets up the data that will be populated in the subsequent populate() call.

```javascript
const person1 = new Person({ name: 'Vince Neil' });
const person2 = new Person({ name: 'Mick Mars' });

const band = new Band({
  name: 'Motley Crue',
  members: {
    singer: person1._id,
    guitarist: person2._id
  }
});
```

--------------------------------

### Aggregate.prototype.sortByCount() - Append $sortByCount operator

Source: https://mongoosejs.com/docs/api/aggregate.html

Appends a new $sortByCount operator. Accepts a string field name or a pipeline object. Mongoose prepends '$' if the field name doesn't start with '$'. The example shows both forms.

```javascript
aggregate.sortByCount('users');
aggregate.sortByCount({ $mergeObjects: [ "$employee", "$business" ] })
```

--------------------------------

### Aggregate() constructor example

Source: https://mongoosejs.com/docs/api/aggregate.html

Shows how to build an aggregation pipeline using Model.aggregate() and chain methods like unwind() and exec(). The documents returned are plain JavaScript objects, not Mongoose documents.

```javascript
const aggregate = Model.aggregate([
  { $project: { a: 1, b: 1 } },
  { $skip: 5 }
]);

Model.
  aggregate([{ $match: { age: { $gte: 21 }}}]).
  unwind('tags').
  exec();
```

--------------------------------

### Aggregate.prototype.redact() examples

Source: https://mongoosejs.com/docs/api/aggregate.html

Appends a $redact operator to the aggregate pipeline. Shows two forms: using a $cond expression object, and using the shorthand with then/else expressions. Note that string expressions must start with '$$'.

```javascript
await Model.aggregate(pipeline).redact({
  $cond: {
    if: { $eq: [ '$level', 5 ] },
    then: '$$PRUNE',
    else: '$$DESCEND'
  }
});

// $redact often comes with $cond operator, you can also use the following syntax provided by mongoose
await Model.aggregate(pipeline).redact({ $eq: [ '$level', 5 ] }, '$$PRUNE', '$$DESCEND');
```

--------------------------------

### Apply virtuals to a plain object with Model.applyVirtuals()

Source: https://mongoosejs.com/docs/api/model.html

Shows how to define a schema with a virtual, create a model, and apply the virtual to a plain object. The virtual's getter runs with the object as context, and the result is added to the object.

```javascript
const userSchema = new Schema({ name: String });
userSchema.virtual('upper').get(function() { return this.name.toUpperCase(); });
const User = mongoose.model('User', userSchema);

const obj = { name: 'John' };
User.applyVirtuals(obj);
obj.name; // 'John'
obj.upper; // 'JOHN', Mongoose applied the return value of the virtual to the given object
```

--------------------------------

### Use excludeIndexes to skip index creation on subdocument schema

Source: https://mongoosejs.com/docs/guide.html

When excludeIndexes is true on a subdocument schema, Mongoose will not create indexes for that subdocument. The example shows that child1.name gets an index while child2.name does not because excludeIndexes is true on childSchema2.

```javascript
const childSchema1 = Schema({
  name: { type: String, index: true }
});

const childSchema2 = Schema({
  name: { type: String, index: true }
}, { excludeIndexes: true });

// Mongoose will create an index on `child1.name`, but **not** `child2.name`, because `excludeIndexes`
// is true on `childSchema2`
const User = new Schema({
  name: { type: String, index: true },
  child1: childSchema1,
  child2: childSchema2
});
```

--------------------------------

### Model.populate() example

Source: https://mongoosejs.com/docs/api/model.html

Shows how to call Model.populate() on plain objects. Note that the model you call populate() on should be the local field model, not the foreign field model. The example uses select to limit fields, so breed is undefined after population.

```javascript
const Dog = mongoose.model('Dog', new Schema({ name: String, breed: String }));
const Person = mongoose.model('Person', new Schema({
  name: String,
  pet: { type: mongoose.ObjectId, ref: 'Dog' }
}));

const pets = await Pet.create([
  { name: 'Daisy', breed: 'Beagle' },
  { name: 'Einstein', breed: 'Catalan Sheepdog' }
]);

// populate many plain objects
const users = [
  { name: 'John Wick', dog: pets[0]._id },
  { name: 'Doc Brown', dog: pets[1]._id }
];
await User.populate(users, { path: 'dog', select: 'name' });
users[0].dog.name; // 'Daisy'
users[0].dog.breed; // undefined because of `select`
```

--------------------------------

### Get the path of a SchemaType with schema.path('name').path

Source: https://mongoosejs.com/docs/api/schematype.html

Shows how to retrieve the path string of a SchemaType instance. The example creates a schema with a 'name' field and logs the path using schema.path('name').path, which returns 'name'.

```javascript
const schema = new Schema({ name: String });
schema.path('name').path; // 'name'
```

--------------------------------

### Model.init()

Source: https://mongoosejs.com/docs/api/model.html

Initializes the underlying MongoDB connection, creating collections, indexes, and search indexes as configured.

```APIDOC
## Model.init()

### Description
Initializes the underlying connection in MongoDB based on schema options. Performs `createCollection()` unless `autoCreate` is off, `ensureIndexes()` unless `autoIndex` is off, and `createSearchIndex()` on all schema search indexes if `autoSearchIndex` is enabled. Mongoose calls this automatically when a model is created, but you may need to call it to get a promise that resolves when indexes are finished building.

### Method
init

### Endpoint
Model.init()

### Parameters
None

### Returns
- **Promise** - Resolves when indexes are done building.

### Example
```
const eventSchema = new Schema({ thing: { type: 'string', unique: true } })
// This calls `Event.init()` implicitly, so you don't need to call
// `Event.init()` on your own.
const Event = mongoose.model('Event', eventSchema);

await Event.init();
console.log('Indexes are done building!');
```
```
Tokens:
Raw