mongoose

mongoose

• 英文原版
• 关于中文文档
• 快速上手
• 模式（Schemas）
• 模式类型（SchemaTypes）
• 连接（Connections）
• 模型（Models）
• 文档 （Documents）
• 子文档（Subdocuments）
• 查询 （queries）
• 验证 （validation）
• 中间件 （middleware）
• 填充 （Populate）
• 鉴别器 （Discriminators）
• 插件
• AWS Lambda
• API 文档
• Schema
• Connection
• Document
• Model
• Query
• Aggregate
• SchemaType
• VirtualType
• Error
• Version Compatibility
• FAQ

API Docs

Index

• Mongoose()
• Mongoose.prototypeSTATES
• Mongoose.prototype.set()
• Mongoose.prototype.get ()
• Mongoose.prototype.createConnection()
• Mongoose.prototype.connect()
• Mongoose.prototype.disconnect()
• Mongoose.prototype.pluralize()
• Mongoose.prototype.model()
• Mongoose.prototype.modelNames()
• Mongoose.prototype.plugin()
• Mongoose .prototype.connection
• Mongoose.prototype.Aggregate ()
• Mongoose.prototype.Collection ()
• Mongoose .prototype.Connection ()
• Mongoose.prototype.version
• Mongoose.prototype.Mongoose ()
• Mongoose.prototype.Schema ()
• Mongoose.prototype.SchemaType ()
• Mongoose.prototype.SchemaTypes
• Mongoose.prototype.VirtualType ()
• Mongoose.prototype.Types
• Mongoose.prototype.Query ()
• Mongoose .prototype.Promise
• Mongoose.prototype.PromiseProvider ()
• Mongoose.prototype.Model ()
• Mongoose.prototype.Document ()
• Mongoose.prototype.DocumentProvider ()
• Mongoose.prototype.Error ()
• Mongoose.prototype.CastError ()
• Mongoose.prototype.mongo
• Mongoose.prototype.mquery

Mongoose()

Mongoose constructor.

The exports object of the mongoose module is an instance of this class. Most apps will only use this one instance.

Mongoose.prototypeSTATES

Expose connection states for user-land

Mongoose.prototype.set()

Parameters

• key «String»
• value «String|Function|Boolean»

Sets mongoose options

Example:

mongoose.set('test', value) // sets the 'test' option to `value`
mongoose.set('debug', true) // enable logging collection methods + arguments to the console
mongoose.set('debug', function(collectionName, methodName, arg1, arg2...) {}); // use custom function to log collection methods + arguments

Currently supported options are

• 'debug': prints the operations mongoose sends to MongoDB to the console
• 'bufferCommands': enable/disable mongoose's buffering mechanism for all connections and models
• 'useFindAndModify': true by default. Set to false to make findOneAndUpdate() and findOneAndRemove() use native findOneAndUpdate() rather than findAndModify().

Mongoose.prototype.get ()

Parameters

• key «String»

Gets mongoose options

Example:

mongoose.get('test') // returns the 'test' value

Mongoose.prototype.createConnection()

Parameters

• [uri] «String» a mongodb:// URI
• [options] «Object» passed down to the MongoDB driver's connect() function, except for 4 mongoose-specific options explained below.
• [options.user] «String» username for authentication, equivalent to options.auth.user. Maintained for backwards compatibility.
• [options.pass] «String» password for authentication, equivalent to options.auth.password. Maintained for backwards compatibility.
• [options.autoIndex=true] «Boolean» Mongoose-specific option. Set to false to disable automatic index creation for all models associated with this connection.
• [options.bufferCommands=true] «Boolean» Mongoose specific option. Set to false to disable buffering on all models associated with this connection.

Returns:

• «Connection» the created Connection object. Connections are thenable, so you can do await mongoose.createConnection()

Creates a Connection instance.

Each connection instance maps to a single database. This method is helpful when mangaging multiple db connections.

If arguments are passed, they are proxied to either Connection#open or Connection#openSet appropriately. This means we can pass db, server, and replset options to the driver. Note that the safe option specified in your schema will overwrite the safe db option specified here unless you set your schemas safe option to undefined. See this for more information.

Options passed take precedence over options included in connection strings.

Example:

// with mongodb:// URI
db = mongoose.createConnection('mongodb://user:pass@localhost:port/database');
// and options
var opts = { db: { native_parser: true }}
db = mongoose.createConnection('mongodb://user:pass@localhost:port/database', opts);
// replica sets
db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database');
// and options
var opts = { replset: { strategy: 'ping', rs_name: 'testSet' }}
db = mongoose.createConnection('mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/database', opts);
// with [host, database_name[, port] signature
db = mongoose.createConnection('localhost', 'database', port)
// and options
var opts = { server: { auto_reconnect: false }, user: 'username', pass: 'mypassword' }
db = mongoose.createConnection('localhost', 'database', port, opts)
// initialize now, connect later
db = mongoose.createConnection();
db.open('localhost', 'database', port, [opts]);

Mongoose.prototype.connect()

Parameters

• uri(s) «String»
• [options] «Object» passed down to the MongoDB driver's connect() function, except for 4 mongoose-specific options explained below.
• [options.user] «String» username for authentication, equivalent to options.auth.user. Maintained for backwards compatibility.
• [options.pass] «String» password for authentication, equivalent to options.auth.password. Maintained for backwards compatibility.
• [options.autoIndex=true] «Boolean» Mongoose-specific option. Set to false to disable automatic index creation for all models associated with this connection.
• [options.bufferCommands=true] «Boolean» Mongoose specific option. Set to false to disable buffering on all models associated with this connection.
• [callback] «Function»

Returns:

• «Promise» resolves to this if connection succeeded

Opens the default mongoose connection.

Example:

mongoose.connect('mongodb://user:pass@localhost:port/database');
// replica sets
var uri = 'mongodb://user:pass@localhost:port,anotherhost:port,yetanother:port/mydatabase';
mongoose.connect(uri);
// with options
mongoose.connect(uri, options);
// optional callback that gets fired when initial connection completed
var uri = 'mongodb://nonexistent.domain:27000';
mongoose.connect(uri, function(error) {
  // if error is truthy, the initial connection failed.
})

Mongoose.prototype.disconnect()

Parameters

• [callback] «Function» called after all connection close, or when first error occurred.

Returns:

• «Promise» resolves when all connections are closed, or rejects with the first error that occurred.

Runs .close() on all connections in parallel.

Mongoose.prototype.pluralize()

Parameters

• [fn] «Function|null» overwrites the function used to pluralize connection names

Returns:

• «Function,null» the current function used to pluralize connection names, undefined by default.

Getter/setter around function for pluralizing collection names.

Mongoose.prototype.model()

Parameters

• name «String|Function» model name or class extending Model
• [schema] «Schema»
• [collection] «String» name (optional, inferred from model name)
• [skipInit] «Boolean» whether to skip initialization (defaults to false)

Returns:

• «Model »

Defines a model or retrieves it.

Models defined on the mongoose instance are available to all connection created by the same mongoose instance.

Example:

var mongoose = require('mongoose');
// define an Actor model with this mongoose instance
mongoose.model('Actor', new Schema({ name: String }));
// create a new connection
var conn = mongoose.createConnection(..);
// retrieve the Actor model
var Actor = conn.model('Actor');

When no collection argument is passed, Mongoose uses the model name. If you don't like this behavior, either pass a collection name, use mongoose.pluralize(), or set your schemas collection name option.

Example:

var schema = new Schema({ name: String }, { collection: 'actor' });
// or
schema.set('collection', 'actor');
// or
var collectionName = 'actor'
var M = mongoose.model('Actor', schema, collectionName)

Mongoose.prototype.modelNames()

Returns:

• «Array»

Returns an array of model names created on this instance of Mongoose.

Note:

Does not include names of models created using connection.model().

Mongoose.prototype.plugin()

Parameters

• fn «Function» plugin callback
• [opts] «Object» optional options

Returns:

• «Mongoose» this

Declares a global plugin executed on all Schemas.

Equivalent to calling .plugin(fn) on each Schema you create.

Mongoose .prototype.connection

Returns:

• «Connection »

The default connection of the mongoose module.

Example:

var mongoose = require('mongoose');
mongoose.connect(...);
mongoose.connection.on('error', cb);

This is the connection used by default for every model created using mongoose.model.

Mongoose.prototype.Aggregate ()

The Mongoose Aggregate constructor

Mongoose.prototype.Collection ()

The Mongoose Collection constructor

Mongoose .prototype.Connection ()

The Mongoose Connection constructor

Mongoose.prototype.version

The Mongoose version

Mongoose.prototype.Mongoose ()

The Mongoose constructor

The exports of the mongoose module is an instance of this class.

Example:

var mongoose = require('mongoose');
var mongoose2 = new mongoose.Mongoose();

Mongoose.prototype.Schema ()

The Mongoose Schema constructor

Example:

var mongoose = require('mongoose');
var Schema = mongoose.Schema;
var CatSchema = new Schema(..);

Mongoose.prototype.SchemaType ()

The Mongoose SchemaType constructor

Mongoose.prototype.SchemaTypes

The various Mongoose SchemaTypes.

Note:

Alias of mongoose.Schema.Types for backwards compatibility.

Mongoose.prototype.VirtualType ()

The Mongoose VirtualType constructor

Mongoose.prototype.Types

The various Mongoose Types.

Example:

var mongoose = require('mongoose');
var array = mongoose.Types.Array;

Types:

• ObjectId
• Buffer
• SubDocument
• Array
• DocumentArray

Using this exposed access to the ObjectId type, we can construct ids on demand.

var ObjectId = mongoose.Types.ObjectId;
var id1 = new ObjectId;

Mongoose.prototype.Query ()

The Mongoose Query constructor.

Mongoose .prototype.Promise

The Mongoose Promise constructor.

Mongoose.prototype.PromiseProvider ()

Storage layer for mongoose promises

Mongoose.prototype.Model ()

The Mongoose Model constructor.

Mongoose.prototype.Document ()

The Mongoose Document constructor.

Mongoose.prototype.DocumentProvider ()

The Mongoose DocumentProvider constructor.

Mongoose.prototype.Error ()

The MongooseError constructor.

Mongoose.prototype.CastError ()

Parameters

• type «String» The name of the type
• value «Any» The value that failed to cast
• path «String» The path a.b.c in the doc where this cast error occurred
• [reason] «Error» The original error that was thrown

The Mongoose CastError constructor

Mongoose.prototype.mongo

The node-mongodb-native driver Mongoose uses.

Mongoose.prototype.mquery

The mquery query builder Mongoose uses.

Schema

• Schema()
• Schema.prototype.childSchemas
• Schema.prototype.obj
• Schema.prototype.paths
• Schema.prototype.tree
• Schema.prototype.clone()
• Schema.prototype.add()
• Schema.reserved
• Schema.prototype.path()
• Schema.prototype.eachPath()
• Schema.prototype.requiredPaths()
• Schema.prototype.indexedPaths()
• Schema.prototype.pathType()
• Schema.prototype.queue()
• Schema.prototype.pre()
• Schema.prototype.post()
• Schema.prototype.plugin()
• Schema.prototype.method()
• Schema.prototype.static()
• Schema.prototype.index()
• Schema.prototype.set()
• Schema.prototype.get()
• indexTypes
• Schema.prototype.indexes()
• Schema.prototype.virtual()
• Schema.prototype.virtualpath()
• Schema.prototype.remove()
• Schema.prototype.loadClass()
• Schema.Types

Schema()

Parameters

• definition «Object»
• [options] «Object»

Schema 构造函数。

示例:

var child = new Schema({ name: String });
var schema = new Schema({ name: String, age: Number, children: [child] });
var Tree = mongoose.model('Tree', schema);
// 设置 schema 选项参数
new Schema({ name: String }, { _id: false, autoIndex: false })

Options:

• autoIndex: bool - 缺省值 null （即使用数据库连接自带的 autoIndex 选项）
• bufferCommands: bool - 缺省值 true
• capped: bool - 缺省值 false
• collection: string - 没有缺省值
• id: bool - 缺省值 true
• _id: bool - 缺省值 true
• minimize: bool - 当 document#toObject 被手动调用时控制其行为 - 缺省值 true
• read: string
• safe: bool - 缺省值 true.
• shardKey: bool - 缺省值 null
• strict: bool - 缺省值 true
• toJSON - object - 没有缺省值
• toObject - object - 没有缺省值
• typeKey - string - 缺省值 'type'
• useNestedStrict - boolean - 缺省值 false
• validateBeforeSave - bool - 缺省值 true
• versionKey: string - 缺省值 "__v"
• collation: object - 缺省值 null （即不使用 collation 功能）

注意:

对 schema 进行嵌套时， （上例中的 children）， 传给父 schema 引用之前一定要先声明子 schema。

Schema.prototype.childSchemas

一个数组，包含子 schema （document 数组中的，和单个的嵌套 subdoc） 和对应已编译的 model。每个元素都是个对象，包含2个属性：schema 和 model。

这个属性通常只有插件开发者和高级用户会使用。 你完全没必要操作它。

Schema.prototype.obj

传给 schema 构造函数的原始对象

示例:

var schema = new Schema({ a: String }).add({ b: String });
schema.obj; // { a: String }

Schema.prototype.paths

Schema 字段路径的扁平结构

示例:

{
    '_id'        : SchemaType,
  , 'nested.key' : SchemaType,
}

Schema.prototype.tree

Schema 字段路径的树形结构

示例:

{
    '_id'     : ObjectId
  , 'nested'  : {
        'key' : String
    }
}

Schema.prototype.clone()

Returns:

• «Schema» 克隆的 schema

返回 schema 的一个深克隆（deep copy）

Schema.prototype.add()

Parameters

• obj «Object»
• prefix «String»

向 schema 中添加 路径/类型(key path / schema type) 键值对

示例:

var ToySchema = new Schema;
ToySchema.add({ name: 'string', color: 'string', price: 'number' });

Schema.reserved

document 中被保留的字段。

在 schema 的声明中禁止使用这个属性中的键作为字段名称，因为跟 mongoose 的功能存在冲突。使用这些名字会抛出错误。

on, emit, _events, db, get, set, init, isNew, errors, schema, options, modelName, collection, _pres, _posts, toObject

注意: 允许使用这些名字作为方法名，但是自负风险， 因为它们可能是 mongoose document 中已经存在的方法名。

var schema = new Schema(..);
 schema.methods.init = function () {} // potentially breaking

Schema.prototype.path()

Parameters

• path «String»
• constructor «Object»

读/写 schema 路径。

Sets a path (2个参数)

Gets a path (1个参数)

示例

schema.path('name') // 返回该路径的数据类型
schema.path('name', Number) // 把路径 `name` 的数据类型设置为 Number

Schema.prototype.eachPath()

Parameters

• fn «Function» 回调函数

Returns:

• «Schema» this

像 Array#forEach 一样遍历 schema 的所有路径。

每次遍历向回调函数传入路径和数据类型（schemaType）两个参数。

Schema.prototype.requiredPaths()

Parameters

• invalidate «Boolean» 刷新缓存

Returns:

• «Array»

返回一个数组，包含 schema 中必需的 (required) 路径字符串

Schema.prototype.indexedPaths()

Returns:

• «Array»

返回字段上的索引和 schema-level 的索引（已被缓存的）

Schema.prototype.pathType()

Parameters

• path «String»

Returns:

• «String »

返回 schema 中路径(path)的类型

给定一个路径，返回它是 real, virtual, nested 还是 ad-hoc/undefined

Schema.prototype.queue()

Parameters

• name «String» 待调用方法的名称
• args «Array» 传给方法的参数 (arguments)

向方法调用的队列中增加一条

Schema.prototype.pre()

Parameters

• method «String»
• callback «Function»

给 document 定义一个前置钩子 (pre hook)

示例

var toySchema = new Schema(..);
toySchema.pre('save', function (next) {
  if (!this.created) this.created = new Date;
  next();
})
toySchema.pre('validate', function (next) {
  if (this.name !== 'Woody') this.name = 'Woody';
  next();
})

Schema.prototype.post()

Parameters

• method «String» name of the method to hook
• fn «Function» callback

给 document 定义一个后置钩子 (post hook)

示例

var schema = new Schema(..);
schema.post('save', function (doc) {
  console.log('this fired after a document was saved');
});
schema.post('find', function(docs) {
  console.log('this fired after you run a find query');
});
var Model = mongoose.model('Model', schema);
var m = new Model(..);
m.save(function(err) {
  console.log('this fires after the `post` hook');
});
m.find(function(err, docs) {
  console.log('this fires after the post find hook');
});

Schema.prototype.plugin()

Parameters

• plugin «Function» callback
• [opts] «Object»

给 schema 注册一个插件

Schema.prototype.method()

Parameters

• method «String|Object» name
• [fn] «Function»

向由该 schema 编译的 model 构造的 document 添加一个实例方法

示例

var schema = kittySchema = new Schema(..);
schema.method('meow', function () {
  console.log('meeeeeoooooooooooow');
})
var Kitty = mongoose.model('Kitty', schema);
var fizz = new Kitty;
fizz.meow(); // meeeeeooooooooooooow

如果参数只有一个，是 名称/函数 哈希键值对，那么每一对 名称/函数 都被加为实例方法。

schema.method({
    purr: function () {}
  , scratch: function () {}
});
// later
fizz.purr();
fizz.scratch();

Schema.prototype.static()

Parameters

• name «String|Object»
• [fn] «Function»

向由该 schema 编译生成的 Model 添加静态类方法

示例

var schema = new Schema(..);
schema.static('findByName', function (name, callback) {
  return this.find({ name: name }, callback);
});
var Drink = mongoose.model('Drink', schema);
Drink.findByName('sanpellegrino', function (err, drinks) {
  //
});

如果参数只有一个，是 名称/函数 哈希键值对，那么每一对 名称/函数 都被加为静态方法。

Schema.prototype.index()

Parameters

• fields «Object»
• [options] «Object» 传给 MongoDB 驱动程序的 createIndex() 函数 的选项
• [options.expires=null] «String» Mongoose 语法糖， 用 ms 把 expires 选项转换成上面链接中 expireAfterSeconds 选项所需要的秒格式。

为该 schema 定义一个索引（大多是复合索引）

示例

schema.index({ first: 1, last: -1 })

Schema.prototype.set()

Parameters

• key «String» 选项的名字
• [value] «Object» 如果没有传值，选项的当前值被返回

读/写 schema 的一个选项。

示例

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

Schema.prototype.get()

Parameters

• key «String» 选项的名字

读取 schema 的一个选项。

indexTypes

可用的索引类型

Schema.prototype.indexes()

返回 schema 的索引列表，定义自 schema.index() 或者字段选项 index: true

Schema.prototype.virtual()

Parameters

• name «String»
• [options] «Object»

Returns:

• «VirtualType»

以给定名称创建一个虚拟类型 (virtual type)

Schema.prototype.virtualpath()

Parameters

• name «String»

Returns:

• «VirtualType»

返回给定名称的虚拟类型。

Schema.prototype.remove()

Parameters

• path «String|Array»

删除给定的路径 (path 或者 [paths])

Schema.prototype.loadClass()

Parameters

• model «Function»
• [virtualsOnly] «Boolean» 如果值为 true，从类中只加载 virtual 字段，忽略实例方法和静态方法。

向 schema 中加载一个 ES6 类。把类中的 setters + getters, static methods, 和 instance methods 映射成为 schema 中的 virtuals,statics, 和 methods。

示例:

const md5 = require('md5');
const userSchema = new Schema({ email: String });
class UserClass {
  // `gravatarImage` becomes a virtual
  get gravatarImage() {
    const hash = md5(this.email.toLowerCase());
    return `https://www.gravatar.com/avatar/${hash}`;
  }
 
  // `getProfileUrl()` becomes a document method
  getProfileUrl() {
    return `https://mysite.com/${this.email}`;
  }
 
  // `findByEmail()` becomes a static
  static findByEmail(email) {
    return this.findOne({ email });
  }
}
 
// `schema` will now have a `gravatarImage` virtual, a `getProfileUrl()` method,
// and a `findByEmail()` static
userSchema.loadClass(UserClass);

Schema.Types

内建的 Mongoose Schema Types.

示例:

var mongoose = require('mongoose');
var ObjectId = mongoose.Schema.Types.ObjectId;

Types:

• String
• Number
• Boolean | Bool
• Array
• Buffer
• Date
• ObjectId | Oid
• Mixed

通过这里的暴露入口，我们可以在 schema 中使用 Mixed SchemaType

var Mixed = mongoose.Schema.Types.Mixed;
new mongoose.Schema({ _user: Mixed })

Connection

• Connection()
• Connection .prototype.readyState
• Connection .prototype.collections
• Connection .prototype.name
• Connection .prototype.host
• Connection .prototype.port
• Connection .prototype.user
• Connection .prototype.pass
• Connection .prototype.db
• Connection .prototype.config
• Connection.prototype.createCollection ()
• Connection.prototype.dropCollection ()
• Connection.prototype.dropDatabase ()
• Connection.prototype.close()
• Connection.prototype.collection()
• Connection.prototype.model()
• Connection.prototype.modelNames()
• Connection.prototype.shouldAuthenticate()
• Connection.prototype.authMechanismDoesNotRequirePassword()
• Connection.prototype.optionsProvideAuthenticationData()

Connection()

Parameters

• base «Mongoose» a mongoose instance

Connection constructor

For practical reasons, a Connection equals a Db.

Connection .prototype.readyState

Connection ready state

• 0 = disconnected
• 1 = connected
• 2 = connecting
• 3 = disconnecting

Each state change emits its associated event name.

Example

conn.on('connected', callback);
conn.on('disconnected', callback);

Connection .prototype.collections

A hash of the collections associated with this connection

Connection .prototype.name

The name of the database this connection points to.

Example

mongoose.createConnection('mongodb://localhost:27017/mydb').name; // "mydb"

Connection .prototype.host

The host name portion of the URI. If multiple hosts, such as a replica set, this will contain the first host name in the URI

Example

mongoose.createConnection('mongodb://localhost:27017/mydb').host; // "localhost"

Connection .prototype.port

The port portion of the URI. If multiple hosts, such as a replica set, this will contain the port from the first host name in the URI.

Example

mongoose.createConnection('mongodb://localhost:27017/mydb').port; // 27017

Connection .prototype.user

The username specified in the URI

Example

mongoose.createConnection('mongodb://val:psw@localhost:27017/mydb').user; // "val"

Connection .prototype.pass

The password specified in the URI

Example

mongoose.createConnection('mongodb://val:psw@localhost:27017/mydb').pass; // "psw"

Connection .prototype.db

The mongodb.Db instance, set when the connection is opened

Connection .prototype.config

A hash of the global options that are associated with this connection

Connection.prototype.createCollection ()

Parameters

• collection «string» The collection to delete
• [options] «Object» see MongoDB driver docs
• [callback] «Function»

Returns:

• «Promise »

Helper for createCollection(). Will explicitly create the given collection with specified options. Used to create capped collections and views from mongoose.

Options are passed down without modification to the MongoDB driver's createCollection() function

Connection.prototype.dropCollection ()

Parameters

• collection «string» The collection to delete
• [callback] «Function»

Returns:

• «Promise »

Helper for dropCollection(). Will delete the given collection, including all documents and indexes.

Connection.prototype.dropDatabase ()

Parameters

• [callback] «Function»

Returns:

• «Promise »

Helper for dropDatabase(). Deletes the given database, including all collections, documents, and indexes.

Connection.prototype.close()

Parameters

• [force] «Boolean» optional
• [callback] «Function» optional

Returns:

• «Connection» self

Closes the connection

Connection.prototype.collection()

Parameters

• name «String» of the collection
• [options] «Object» optional collection options

Returns:

• «Collection» collection instance

Retrieves a collection, creating it if not cached.

Not typically needed by applications. Just talk to your collection through your model.

Connection.prototype.model()

Parameters

• name «String» the model name
• [schema] «Schema» a schema. necessary when defining a model
• [collection] «String» name of mongodb collection (optional) if not given it will be induced from model name

Returns:

• «Model» The compiled model

Defines or retrieves a model.

var mongoose = require('mongoose');
var db = mongoose.createConnection(..);
db.model('Venue', new Schema(..));
var Ticket = db.model('Ticket', new Schema(..));
var Venue = db.model('Venue');

When no collection argument is passed, Mongoose produces a collection name by passing the model name to the utils.toCollectionName method. This method pluralizes the name. If you don't like this behavior, either pass a collection name or set your schemas collection name option.

Example:

var schema = new Schema({ name: String }, { collection: 'actor' });
// or
schema.set('collection', 'actor');
// or
var collectionName = 'actor'
var M = conn.model('Actor', schema, collectionName)

Connection.prototype.modelNames()

Returns:

• «Array»

Returns an array of model names created on this connection.

Connection.prototype.shouldAuthenticate()

Returns:

• «Boolean» true if the connection should be authenticated after it is opened, otherwise false.

@brief Returns if the connection requires authentication after it is opened. Generally if a username and password are both provided than authentication is needed, but in some cases a password is not required.

Connection.prototype.authMechanismDoesNotRequirePassword()

Returns:

• «Boolean» true if the authentication mechanism specified in the options object requires

@brief Returns a boolean value that specifies if the current authentication mechanism needs a password to authenticate according to the auth objects passed into the open/openSet methods.

Connection.prototype.optionsProvideAuthenticationData()

Parameters

• [options] «Object» the options object passed into the open/openSet methods.

Returns:

• «Boolean» true if the provided options object provides enough data to authenticate with,

@brief Returns a boolean value that specifies if the provided objects object provides enough data to authenticate with. Generally this is true if the username and password are both specified but in some authentication methods, a password is not required for authentication so only a username is required.

Document

• Document.prototype.schema
• Document.prototype.isNew
• Document.prototype.id
• Document.prototype.errors
• Document.prototype.$__buildDoc ()
• Document.prototype.init()
• Document.prototype.update()
• Document .prototype.$set ()
• Document.prototype.set ()
• Document.prototype.$__shouldModify ()
• Document.prototype.$__set ()
• Document.prototype.get()
• Document.prototype.$__path ()
• Document.prototype.markModified()
• Document.prototype.unmarkModified()
• Document .prototype.$ignore ()
• Document.prototype.modifiedPaths()
• Document.prototype.isModified()
• Document .prototype.$isDefault ()
• Document .prototype.$isDeleted ()
• Document.prototype.isDirectModified()
• Document.prototype.isInit()
• Document.prototype.isSelected()
• Document.prototype.isDirectSelected()
• Document.prototype.validate()
• Document.prototype.validateSync()
• Document.prototype.invalidate()
• Document .prototype.$markValid()
• Document .prototype.save ()
• Document.prototype.$__reset ()
• Document.prototype.$__dirty ()
• Document.prototype.$__setSchema ()
• Document.prototype.$__getArrayPathsToValidate ()
• Document.prototype.$__getAllSubdocs ()
• Document.prototype.$toObject ()
• Document.prototype.toObject()
• Document.prototype.toJSON()
• Document.prototype.inspect ()
• Document.prototype.toString ()
• Document.prototype.equals()
• Document.prototype.populate()
• Document.prototype.execPopulate()
• Document .prototype.populated()
• Document.prototype.depopulate()
• Document.prototype.$__fullPath ()

Document.prototype.schema

The documents schema.

Document.prototype.isNew

Boolean flag specifying if the document is new.

Document.prototype.id

The string version of this documents _id.

Note:

This getter exists on all documents by default. The getter can be disabled by setting the id option of its Schema to false at construction time.

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

Document.prototype.errors

Hash containing current validation errors.

Document.prototype.$__buildDoc ()

Parameters

• obj «Object»
• [fields] «Object»
• [skipId] «Boolean»

Builds the default doc structure

Document.prototype.init()

Parameters

• doc «Object» document returned by mongo

Initializes the document without setters or marking anything modified.

Called internally after a document is returned from mongodb.

Document.prototype.update()

Parameters

• doc «Object»
• options «Object»
• callback «Function»

Returns:

• «Query »

Sends an update command with this document _id as the query selector.

Example:

weirdCar.update({$inc: {wheels:1}}, { w: 1 }, callback);

Valid options:

• same as in Model.update

Document .prototype.$set ()

Parameters

• path «String|Object» path or object of key/vals to set
• val «Any» the value to set
• [type] «Schema|String|Number|Buffer|*» optionally specify a type for "on-the-fly" attributes
• [options] «Object» optionally specify options that modify the behavior of the set

Alias for set(), used internally to avoid conflicts

Document.prototype.set ()

Parameters

• path «String|Object» path or object of key/vals to set
• val «Any» the value to set
• [type] «Schema|String|Number|Buffer|*» optionally specify a type for "on-the-fly" attributes
• [options] «Object» optionally specify options that modify the behavior of the set

Sets the value of a path, or many paths.

Example:

// path, value
doc.set(path, value)
// object
doc.set({
    path  : value
  , path2 : {
       path  : value
    }
})
// on-the-fly cast to number
doc.set(path, value, Number)
// on-the-fly cast to string
doc.set(path, value, String)
// changing strict mode behavior
doc.set(path, value, { strict: false });

Document.prototype.$__shouldModify ()

Returns:

• «Boolean »

Determine if we should mark this change as modified.

Document.prototype.$__set ()

Handles the actual setting of the value and marking the path modified if appropriate.

Document.prototype.get()

Parameters

• path «String»
• [type] «Schema|String|Number|Buffer|*» optionally specify a type for on-the-fly attributes

Returns the value of a path.

Example

// path
doc.get('age') // 47
// dynamic casting to a string
doc.get('age', String) // "47"

Document.prototype.$__path ()

Parameters

• path «String»

Returns the schematype for the given path.

Document.prototype.markModified()

Parameters

• path «String» the path to mark modified
• [scope] «Document» the scope to run validators with

Marks the path as having pending changes to write to the db.

Very helpful when using Mixed types.

Example:

doc.mixed.type = 'changed';
doc.markModified('mixed.type');
doc.save() // changes to mixed.type are now persisted

Document.prototype.unmarkModified()

Parameters

• path «String» the path to unmark modified

Clears the modified state on the specified path.

Example:

doc.foo = 'bar';
doc.unmarkModified('foo');
doc.save() // changes to foo will not be persisted

Document .prototype.$ignore ()

Parameters

• path «String» the path to ignore

Don't run validation on this path or persist changes to this path.

Example:

doc.foo = null;
doc.$ignore('foo');
doc.save() // changes to foo will not be persisted and validators won't be run

Document.prototype.modifiedPaths()

Parameters

• [options] «Object»
• [options.includeChildren=false] «Boolean» if true, returns children of modified paths as well. For example, if false, the list of modified paths for doc.colors = { primary: 'blue' }; will not contain colors.primary

Returns:

• «Array »

Returns the list of paths that have been modified.

Document.prototype.isModified()

Parameters

• [path] «String» optional

Returns:

• «Boolean »

Returns true if this document was modified, else false.

If path is given, checks if a path or any full path containing path as part of its path chain has been modified.

Example

doc.set('documents.0.title', 'changed');
doc.isModified()                      // true
doc.isModified('documents')           // true
doc.isModified('documents.0.title')   // true
doc.isModified('documents otherProp') // true
doc.isDirectModified('documents')     // false

Document .prototype.$isDefault ()

Parameters

• [path] «String»

Returns:

• «Boolean »

Checks if a path is set to its default.

Example

MyModel = mongoose.model('test', { name: { type: String, default: 'Val '} });
var m = new MyModel();
m.$isDefault('name'); // true

Document .prototype.$isDeleted ()

Parameters

• [val] «Boolean» optional, overrides whether mongoose thinks the doc is deleted

Returns:

• «Boolean» whether mongoose thinks this doc is deleted.

Getter/setter, determines whether the document was removed or not.

Example:

product.remove(function (err, product) {
  product.isDeleted(); // true
  product.remove(); // no-op, doesn't send anything to the db
  product.isDeleted(false);
  product.isDeleted(); // false
  product.remove(); // will execute a remove against the db
})

Document.prototype.isDirectModified()

Parameters

• path «String»

Returns:

• «Boolean »

Returns true if path was directly set and modified, else false.

Example

doc.set('documents.0.title', 'changed');
doc.isDirectModified('documents.0.title') // true
doc.isDirectModified('documents') // false

Document.prototype.isInit()

Parameters

• path «String»

Returns:

• «Boolean »

Checks if path was initialized.

Document.prototype.isSelected()

Parameters

• path «String»

Returns:

• «Boolean »

Checks if path was selected in the source query which initialized this document.

Example

Thing.findOne().select('name').exec(function (err, doc) {
   doc.isSelected('name') // true
   doc.isSelected('age')  // false
})

Document.prototype.isDirectSelected()

Parameters

• path «String»

Returns:

• «Boolean »

Checks if path was explicitly selected. If no projection, always returns true.

Example

Thing.findOne().select('nested.name').exec(function (err, doc) {
   doc.isDirectSelected('nested.name') // true
   doc.isDirectSelected('nested.otherName') // false
   doc.isDirectSelected('nested')  // false
})

Document.prototype.validate()

Parameters

• optional «Object» options internal options
• callback «Function» optional callback called after validation completes, passing an error if one occurred

Returns:

• «Promise» Promise

Executes registered validation rules for this document.

Note:

This method is called pre save and if a validation rule is violated, save is aborted and the error is returned to your callback.

Example:

doc.validate(function (err) {
  if (err) handleError(err);
  else // validation passed
});

Document.prototype.validateSync()

Parameters

• pathsToValidate «Array|string» only validate the given paths

Returns:

• «MongooseError,undefined» MongooseError if there are errors during validation, or undefined if there is no error.

Executes registered validation rules (skipping asynchronous validators) for this document.

Note:

This method is useful if you need synchronous validation.

Example:

var err = doc.validateSync();
if ( err ){
  handleError( err );
} else {
  // validation passed
}

Document.prototype.invalidate()

Parameters

• path «String» the field to invalidate
• errorMsg «String|Error» the error which states the reason path was invalid
• value «Object|String|Number|any» optional invalid value
• [kind] «String» optional kind property for the error

Returns:

• «ValidationError» the current ValidationError, with all currently invalidated paths

Marks a path as invalid, causing validation to fail.

The errorMsg argument will become the message of the ValidationError.

The value argument (if passed) will be available through the ValidationError.value property.

doc.invalidate('size', 'must be less than 20', 14);
doc.validate(function (err) {
  console.log(err)
  // prints
  { message: 'Validation failed',
    name: 'ValidationError',
    errors:
     { size:
        { message: 'must be less than 20',
          name: 'ValidatorError',
          path: 'size',
          type: 'user defined',
          value: 14 } } }
})

Document .prototype.$markValid()

Parameters

• path «String» the field to mark as valid

Marks a path as valid, removing existing validation errors.

Document .prototype.save ()

Parameters

• [options] «Object» options optional options
• [options.safe] «Object» overrides schema's safe option
• [options.validateBeforeSave] «Boolean» set to false to save without validating.
• [fn] «Function» optional callback

Returns:

• «Promise» Promise

Saves this document.

Example:

product.sold = Date.now();
product.save(function (err, product, numAffected) {
  if (err) ..
})

The callback will receive three parameters

• err if an error occurred
• product which is the saved product
• numAffected will be 1 when the document was successfully persisted to MongoDB, otherwise 0. Unless you tweak mongoose's internals, you don't need to worry about checking this parameter for errors - checking err is sufficient to make sure your document was properly saved.

As an extra measure of flow control, save will return a Promise.

Example:

product.save().then(function(product) {
   ...
});

Document.prototype.$__reset ()

Returns:

• «Document »

Resets the internal modified state of this document.

Document.prototype.$__dirty ()

Returns this documents dirty paths / vals.

Document.prototype.$__setSchema ()

Parameters

• schema «Schema»

Assigns/compiles schema into this documents prototype.

Document.prototype.$__getArrayPathsToValidate ()

Get active path that were changed and are arrays

Document.prototype.$__getAllSubdocs ()

Get all subdocs (by bfs)

Document.prototype.$toObject ()

Internal helper for toObject() and toJSON() that doesn't manipulate options

Document.prototype.toObject()

Parameters

• [options] «Object»

Returns:

• «Object» js object

Converts this document into a plain javascript object, ready for storage in MongoDB.

Buffers are converted to instances of mongodb.Binary for proper storage.

Options:

• getters apply all getters (path and virtual getters)
• virtuals apply virtual getters (can override getters option)
• minimize remove empty objects (defaults to true)
• transform a transform function to apply to the resulting document before returning
• depopulate depopulate any populated paths, replacing them with their original refs (defaults to false)
• versionKey whether to include the version key (defaults to true)

Getters/Virtuals

Example of only applying path getters

doc.toObject({ getters: true, virtuals: false })

Example of only applying virtual getters

doc.toObject({ virtuals: true })

Example of applying both path and virtual getters

doc.toObject({ getters: true })

To apply these options to every document of your schema by default, set your schemas toObject option to the same argument.

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

Transform

We may need to perform a transformation of the resulting object based on some criteria, say to remove some sensitive information or return a custom object. In this case we set the optional transform function.

Transform functions receive three arguments

function (doc, ret, options) {}

• doc The mongoose document which is being converted
• ret The plain object representation which has been converted
• options The options in use (either schema options or the options passed inline)

Example

// specify the transform schema option
if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.transform = function (doc, ret, options) {
  // remove the _id of every document before returning the result
  delete ret._id;
  return ret;
}
// without the transformation in the schema
doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }
// with the transformation
doc.toObject(); // { name: 'Wreck-it Ralph' }

With transformations we can do a lot more than remove properties. We can even return completely new customized objects:

if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.transform = function (doc, ret, options) {
  return { movie: ret.name }
}
// without the transformation in the schema
doc.toObject(); // { _id: 'anId', name: 'Wreck-it Ralph' }
// with the transformation
doc.toObject(); // { movie: 'Wreck-it Ralph' }

Note: if a transform function returns undefined, the return value will be ignored.

Transformations may also be applied inline, overridding any transform set in the options:

function xform (doc, ret, options) {
  return { inline: ret.name, custom: true }
}
// pass the transform as an inline option
doc.toObject({ transform: xform }); // { inline: 'Wreck-it Ralph', custom: true }

If you want to skip transformations, use transform: false:

if (!schema.options.toObject) schema.options.toObject = {};
schema.options.toObject.hide = '_id';
schema.options.toObject.transform = function (doc, ret, options) {
  if (options.hide) {
    options.hide.split(' ').forEach(function (prop) {
      delete ret[prop];
    });
  }
  return ret;
}
var doc = new Doc({ _id: 'anId', secret: 47, name: 'Wreck-it Ralph' });
doc.toObject();                                        // { secret: 47, name: 'Wreck-it Ralph' }
doc.toObject({ hide: 'secret _id', transform: false });// { _id: 'anId', secret: 47, name: 'Wreck-it Ralph' }
doc.toObject({ hide: 'secret _id', transform: true }); // { name: 'Wreck-it Ralph' }

Transforms are applied only to the document and are not applied to sub-documents.

Transforms, like all of these options, are also available for toJSON.

See schema options for some more details.

During save, no custom options are applied to the document before being sent to the database.

Document.prototype.toJSON()

Parameters

• options «Object»

Returns:

• «Object »

The return value of this method is used in calls to JSON.stringify(doc).

This method accepts the same options as Document#toObject. To apply the options to every document of your schema by default, set your schemas toJSON option to the same argument.

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

See schema options for details.

Document.prototype.inspect ()

Helper for console.log

Document.prototype.toString ()

Helper for console.log

Document.prototype.equals()

Parameters

• doc «Document» a document to compare

Returns:

• «Boolean »

Returns true if the Document stores the same data as doc.

Documents are considered equal when they have matching _ids, unless neither document has an _id, in which case this function falls back to using deepEqual().

Document.prototype.populate()

Parameters

• [path] «String|Object» The path to populate or an options object
• [callback] «Function» When passed, population is invoked

Returns:

• «Document» this

Populates document references, executing the callback when complete. If you want to use promises instead, use this function with execPopulate()

Example:

doc
.populate('company')
.populate({
  path: 'notes',
  match: /airline/,
  select: 'text',
  model: 'modelName'
  options: opts
}, function (err, user) {
  assert(doc._id === user._id) // the document itself is passed
})
// summary
doc.populate(path)                   // not executed
doc.populate(options);               // not executed
doc.populate(path, callback)         // executed
doc.populate(options, callback);     // executed
doc.populate(callback);              // executed
doc.populate(options).execPopulate() // executed, returns promise

NOTE:

Population does not occur unless a callback is passed or you explicitly call execPopulate(). Passing the same path a second time will overwrite the previous path options. See Model.populate() for explaination of options.

Document.prototype.execPopulate()

Returns:

• «Promise» promise that resolves to the document when population is done

Explicitly executes population and returns a promise. Useful for ES2015 integration.

Example:

var promise = doc.
  populate('company').
  populate({
    path: 'notes',
    match: /airline/,
    select: 'text',
    model: 'modelName'
    options: opts
  }).
  execPopulate();
// summary
doc.execPopulate().then(resolve, reject);

Document .prototype.populated()

Parameters

• path «String»

Returns:

• «Array,ObjectId,Number,Buffer,String,undefined »

Gets _id(s) used during population of the given path.

Example:

Model.findOne().populate('author').exec(function (err, doc) {
  console.log(doc.author.name)         // Dr.Seuss
  console.log(doc.populated('author')) // '5144cf8050f071d979c118a7'
})

If the path was not populated, undefined is returned.

Document.prototype.depopulate()

Parameters

• path «String»

Returns:

• «Document» this

Takes a populated field and returns it to its unpopulated state.

Example:

Model.findOne().populate('author').exec(function (err, doc) {
  console.log(doc.author.name); // Dr.Seuss
  console.log(doc.depopulate('author'));
  console.log(doc.author); // '5144cf8050f071d979c118a7'
})