API Docs

Mongoose constructor.

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

Expose connection states for user-land

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().

Gets mongoose options

Example:

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

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]);

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.
})

Runs .close() on all connections in parallel.

Getter/setter around function for pluralizing collection names.

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)

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

Note:

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

Declares a global plugin executed on all Schemas.

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

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.

The Mongoose Aggregate constructor

The Mongoose Collection constructor

The Mongoose Connection constructor

The Mongoose version

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();

The Mongoose Schema constructor

Example:

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

The Mongoose SchemaType constructor

The various Mongoose SchemaTypes.

Note:

Alias of mongoose.Schema.Types for backwards compatibility.

The Mongoose VirtualType constructor

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;

The Mongoose Query constructor.

The Mongoose Promise constructor.

Storage layer for mongoose promises

The Mongoose Model constructor.

The Mongoose Document constructor.

The Mongoose DocumentProvider constructor.

The MongooseError constructor.

The Mongoose CastError constructor

The node-mongodb-native driver Mongoose uses.

The mquery query builder Mongoose uses.

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 （document 数组中的，和单个的嵌套 subdoc） 和对应已编译的 model。每个元素都是个对象，包含2个属性：schema 和 model。

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

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

示例:

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

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

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

示例:

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

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 路径。

Sets a path (2个参数)

Gets a path (1个参数)

示例

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

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

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

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

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

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

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

给 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();
})

给 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 注册一个插件

向由该 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 编译生成的 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 定义一个索引（大多是复合索引）

示例

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

读/写 schema 的一个选项。

示例

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

读取 schema 的一个选项。

可用的索引类型

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

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

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

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

向 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);

内建的 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 constructor

For practical reasons, a Connection equals a Db.

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

A hash of the collections associated with this connection

The name of the database this connection points to.

Example

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

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"

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

The username specified in the URI

Example

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

The password specified in the URI

Example

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

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

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

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

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

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

Closes the connection

Retrieves a collection, creating it if not cached.

Not typically needed by applications. Just talk to your collection through your 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)

Returns an array of model names created on this connection.

The documents schema.

Boolean flag specifying if the document is new.

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

Hash containing current validation errors.

Initializes the document without setters or marking anything modified.

Called internally after a document is returned from mongodb.

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

Alias for set(), used internally to avoid conflicts

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

Returns the value of a path.

Example

// path
doc.get('age') // 47

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

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

Clears the modified state on the specified path.

Example:

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

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

Returns the list of paths that have been modified.

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

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

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

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

Checks if path was initialized.

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

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

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

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
}

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

Marks a path as valid, removing existing validation errors.

Saves this document.

Example:

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

The callback will receive three parameters

1. err if an error occurred
2. product which is the saved product
3. 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) {
   ...
});

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.

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.

Helper for console.log

Helper for console.log

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().

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.

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

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.

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'
})

If the path was not populated, this is a no-op.

Model constructor

Provides the interface to MongoDB collections as well as creates document instances.

Connection the model uses.

Collection the model uses.

The name of the model

Additional properties to attach to the query when calling save() and isNew is false.

If this is a discriminator model, baseModelName is the name of the base model.

Saves this document.

Example:

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

The callback will receive three parameters

1. err if an error occurred
2. product which is the saved product

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

Example:

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

Signal that we desire an increment of this documents version.

Example:

Model.findById(id, function (err, doc) {
  doc.increment();
  doc.save(function (err) { .. })
})

Removes this document from the db.

Example:

product.remove(function (err, product) {
  if (err) return handleError(err);
  Product.findById(product._id, function (err, product) {
    console.log(product) // null
  })
})

As an extra measure of flow control, remove will return a Promise (bound to fn if passed) so it could be chained, or hooked to recieve errors

Example:

product.remove().then(function (product) {
   ...
}).catch(function (err) {
   assert.ok(err)
})

Returns another Model instance.

Example:

var doc = new Tank;
doc.model('User').findById(id, callback);

Adds a discriminator type.

Example:

function BaseSchema() {
  Schema.apply(this, arguments);

  this.add({
    name: String,
    createdAt: Date
  });
}
util.inherits(BaseSchema, Schema);

var PersonSchema = new BaseSchema();
var BossSchema = new BaseSchema({ department: String });

var Person = mongoose.model('Person', PersonSchema);
var Boss = Person.discriminator('Boss', BossSchema);
new Boss().__t; // "Boss". `__t` is the default `discriminatorKey`

var employeeSchema = new Schema({ boss: ObjectId });
var Employee = Person.discriminator('Employee', employeeSchema, 'staff');
new Employee().__t; // "staff" because of 3rd argument above

Performs any async initialization of this model against MongoDB. Currently, this function is only responsible for building indexes, unless autoIndex is turned off.

This function is called automatically, so you don't need to call it. This function is also idempotent, so you may call it to get back a promise that will resolve when your indexes are finished building as an alternative to MyModel.on('index')

Example:

var 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.
var Event = mongoose.model('Event', eventSchema);

Event.init().then(function(Event) {
  // You can also use `Event.on('index')` if you prefer event emitters
  // over promises.
  console.log('Indexes are done building!');
});

Sends createIndex commands to mongo for each index declared in the schema. The createIndex commands are sent in series.

Example:

Event.ensureIndexes(function (err) {
  if (err) return handleError(err);
});

After completion, an index event is emitted on this Model passing an error if one occurred.

Example:

var eventSchema = new Schema({ thing: { type: 'string', unique: true }})
var Event = mongoose.model('Event', eventSchema);

Event.on('index', function (err) {
  if (err) console.error(err); // error occurred during index creation
})

NOTE: It is not recommended that you run this in production. Index creation may impact database performance depending on your load. Use with caution.

Similar to ensureIndexes(), except for it uses the createIndex function. The ensureIndex() function checks to see if an index with that name already exists, and, if not, does not attempt to create the index. createIndex() bypasses this check.

Schema the model uses.

Base Mongoose instance the model uses.

Registered discriminators for this model.

Translate any aliases fields/conditions so the final query or document object is pure

Example:

Character
  .find(Character.translateAliases({
    '名': 'Eddard Stark' // Alias for 'name'
  })
  .exec(function(err, characters) {})

Note:

Only translate arguments of object type anything else is returned raw

Removes all documents that match conditions from the collection. To remove just the first document that matches conditions, set the single option to true.

Example:

Character.remove({ name: 'Eddard Stark' }, function (err) {});

Note:

This method sends a remove command directly to MongoDB, no Mongoose documents are involved. Because no Mongoose documents are involved, no middleware (hooks) are executed.

Deletes the first document that matches conditions from the collection. Behaves like remove(), but deletes at most one document regardless of the single option.

Example:

Character.deleteOne({ name: 'Eddard Stark' }, function (err) {});

Note:

Like Model.remove(), this function does not trigger pre('remove') or post('remove') hooks.

Deletes all of the documents that match conditions from the collection. Behaves like remove(), but deletes all documents that match conditions regardless of the single option.

Example:

Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }, function (err) {});

Note:

Like Model.remove(), this function does not trigger pre('remove') or post('remove') hooks.

Finds documents

The conditions are cast to their respective SchemaTypes before the command is sent.

Examples:

// named john and at least 18
MyModel.find({ name: 'john', age: { $gte: 18 }});

// executes immediately, passing results to callback
MyModel.find({ name: 'john', age: { $gte: 18 }}, function (err, docs) {});

// name LIKE john and only selecting the "name" and "friends" fields, executing immediately
MyModel.find({ name: /john/i }, 'name friends', function (err, docs) { })

// passing options
MyModel.find({ name: /john/i }, null, { skip: 10 })

// passing options and executing immediately
MyModel.find({ name: /john/i }, null, { skip: 10 }, function (err, docs) {});

// executing a query explicitly
var query = MyModel.find({ name: /john/i }, null, { skip: 10 })
query.exec(function (err, docs) {});

// using the promise returned from executing a query
var query = MyModel.find({ name: /john/i }, null, { skip: 10 });
var promise = query.exec();
promise.addBack(function (err, docs) {});

Finds a single document by its _id field. findById(id) is almost* equivalent to findOne({ _id: id }). If you want to query by a document's _id, use findById() instead of findOne().

The id is cast based on the Schema before sending the command.

This function triggers the following middleware.

• findOne()

* Except for how it treats undefined. If you use findOne(), you'll see that findOne(undefined) and findOne({ _id: undefined }) are equivalent to findOne({}) and return arbitrary documents. However, mongoose translates findById(undefined) into findOne({ _id: null }).

Example:

// find adventure by id and execute immediately
Adventure.findById(id, function (err, adventure) {});

// same as above
Adventure.findById(id).exec(callback);

// select only the adventures name and length
Adventure.findById(id, 'name length', function (err, adventure) {});

// same as above
Adventure.findById(id, 'name length').exec(callback);

// include all properties except for `length`
Adventure.findById(id, '-length').exec(function (err, adventure) {});

// passing options (in this case return the raw js objects, not mongoose documents by passing `lean`
Adventure.findById(id, 'name', { lean: true }, function (err, doc) {});

// same as above
Adventure.findById(id, 'name').lean().exec(function (err, doc) {});

Finds one document.

The conditions are cast to their respective SchemaTypes before the command is sent.

Note: conditions is optional, and if conditions is null or undefined, mongoose will send an empty findOne command to MongoDB, which will return an arbitrary document. If you're querying by _id, use findById() instead.

Example:

// find one iphone adventures - iphone adventures??
Adventure.findOne({ type: 'iphone' }, function (err, adventure) {});

// same as above
Adventure.findOne({ type: 'iphone' }).exec(function (err, adventure) {});

// select only the adventures name
Adventure.findOne({ type: 'iphone' }, 'name', function (err, adventure) {});

// same as above
Adventure.findOne({ type: 'iphone' }, 'name').exec(function (err, adventure) {});

// specify options, in this case lean
Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }, callback);

// same as above
Adventure.findOne({ type: 'iphone' }, 'name', { lean: true }).exec(callback);

// chaining findOne queries (same as above)
Adventure.findOne({ type: 'iphone' }).select('name').lean().exec(callback);

Counts number of matching documents in a database collection.

Example:

Adventure.count({ type: 'jungle' }, function (err, count) {
  if (err) ..
  console.log('there are %d jungle adventures', count);
});

Creates a Query for a distinct operation.

Passing a callback immediately executes the query.

Example

Link.distinct('url', { clicks: {$gt: 100}}, function (err, result) {
  if (err) return handleError(err);

  assert(Array.isArray(result));
  console.log('unique urls with more than 100 clicks', result);
})

var query = Link.distinct('url');
query.exec(callback);

Creates a Query, applies the passed conditions, and returns the Query.

For example, instead of writing:

User.find({age: {$gte: 21, $lte: 65}}, callback);

we can instead write:

User.where('age').gte(21).lte(65).exec(callback);

Since the Query class also supports where you can continue chaining

User
.where('age').gte(21).lte(65)
.where('name', /^b/i)
... etc

Creates a Query and specifies a $where condition.

Sometimes you need to query for things in mongodb using a JavaScript expression. You can do so via find({ $where: javascript }), or you can use the mongoose shortcut method $where via a Query chain or from your mongoose Model.

Blog.$where('this.username.indexOf("val") !== -1').exec(function (err, docs) {});

Issues a mongodb findAndModify update command.

Finds a matching document, updates it according to the update arg, passing any options, and returns the found document (if any) to the callback. The query executes immediately if callback is passed else a Query object is returned.

Options:

• new: bool - if true, return the modified document rather than the original. defaults to false (changed in 4.0)
• upsert: bool - creates the object if it doesn't exist. defaults to false.
• fields: {Object|String} - Field selection. Equivalent to .select(fields).findOneAndUpdate()
• maxTimeMS: puts a time limit on the query - requires mongodb >= 2.6.0
• sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
• runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model's schema.
• setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model's schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB's $setOnInsert operator.
• rawResult: if true, returns the raw result from the MongoDB driver
• strict: overwrites the schema's strict mode option for this update

Examples:

A.findOneAndUpdate(conditions, update, options, callback) // executes
A.findOneAndUpdate(conditions, update, options)  // returns Query
A.findOneAndUpdate(conditions, update, callback) // executes
A.findOneAndUpdate(conditions, update)           // returns Query
A.findOneAndUpdate()                             // returns Query

Note:

All top level update keys which are not atomic operation names are treated as set operations:

Example:

var query = { name: 'borne' };
Model.findOneAndUpdate(query, { name: 'jason bourne' }, options, callback)

// is sent as
Model.findOneAndUpdate(query, { $set: { name: 'jason bourne' }}, options, callback)

This helps prevent accidentally overwriting your document with { name: 'jason bourne' }.

Note:

Values are cast to their appropriate types when using the findAndModify helpers. However, the below are not executed by default.

• defaults. Use the setDefaultsOnInsert option to override.

findAndModify helpers support limited validation. You can enable these by setting the runValidators options, respectively.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

Model.findById(id, function (err, doc) {
  if (err) ..
  doc.name = 'jason bourne';
  doc.save(callback);
});

Issues a mongodb findAndModify update command by a document's _id field. findByIdAndUpdate(id, ...) is equivalent to findOneAndUpdate({ _id: id }, ...).

Finds a matching document, updates it according to the update arg, passing any options, and returns the found document (if any) to the callback. The query executes immediately if callback is passed else a Query object is returned.

This function triggers the following middleware.

• findOneAndUpdate()

Options:

• new: bool - true to return the modified document rather than the original. defaults to false
• upsert: bool - creates the object if it doesn't exist. defaults to false.
• runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model's schema.
• setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model's schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB's $setOnInsert operator.
• sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
• select: sets the document fields to return
• rawResult: if true, returns the raw result from the MongoDB driver
• strict: overwrites the schema's strict mode option for this update

Examples:

A.findByIdAndUpdate(id, update, options, callback) // executes
A.findByIdAndUpdate(id, update, options)  // returns Query
A.findByIdAndUpdate(id, update, callback) // executes
A.findByIdAndUpdate(id, update)           // returns Query
A.findByIdAndUpdate()                     // returns Query

Note:

All top level update keys which are not atomic operation names are treated as set operations:

Example:

Model.findByIdAndUpdate(id, { name: 'jason bourne' }, options, callback)

// is sent as
Model.findByIdAndUpdate(id, { $set: { name: 'jason bourne' }}, options, callback)

This helps prevent accidentally overwriting your document with { name: 'jason bourne' }.

Note:

Values are cast to their appropriate types when using the findAndModify helpers. However, the below are not executed by default.

• defaults. Use the setDefaultsOnInsert option to override.

findAndModify helpers support limited validation. You can enable these by setting the runValidators options, respectively.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

Model.findById(id, function (err, doc) {
  if (err) ..
  doc.name = 'jason bourne';
  doc.save(callback);
});

Issue a mongodb findAndModify remove command.

Finds a matching document, removes it, passing the found document (if any) to the callback.

Executes immediately if callback is passed else a Query object is returned.

This function triggers the following middleware.

• findOneAndRemove()

Options:

• sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
• maxTimeMS: puts a time limit on the query - requires mongodb >= 2.6.0
• select: sets the document fields to return
• rawResult: if true, returns the raw result from the MongoDB driver
• strict: overwrites the schema's strict mode option for this update

Examples:

A.findOneAndRemove(conditions, options, callback) // executes
A.findOneAndRemove(conditions, options)  // return Query
A.findOneAndRemove(conditions, callback) // executes
A.findOneAndRemove(conditions) // returns Query
A.findOneAndRemove()           // returns Query

Values are cast to their appropriate types when using the findAndModify helpers. However, the below are not executed by default.

• defaults. Use the setDefaultsOnInsert option to override.

findAndModify helpers support limited validation. You can enable these by setting the runValidators options, respectively.

If you need full-fledged validation, use the traditional approach of first retrieving the document.

Model.findById(id, function (err, doc) {
  if (err) ..
  doc.name = 'jason bourne';
  doc.save(callback);
});

Issue a mongodb findAndModify remove command by a document's _id field. findByIdAndRemove(id, ...) is equivalent to findOneAndRemove({ _id: id }, ...).

Finds a matching document, removes it, passing the found document (if any) to the callback.

Executes immediately if callback is passed, else a Query object is returned.

This function triggers the following middleware.

• findOneAndRemove()

Options:

• sort: if multiple docs are found by the conditions, sets the sort order to choose which doc to update
• select: sets the document fields to return
• rawResult: if true, returns the raw result from the MongoDB driver
• strict: overwrites the schema's strict mode option for this update

Examples:

A.findByIdAndRemove(id, options, callback) // executes
A.findByIdAndRemove(id, options)  // return Query
A.findByIdAndRemove(id, callback) // executes
A.findByIdAndRemove(id) // returns Query
A.findByIdAndRemove()           // returns Query

Shortcut for saving one or more documents to the database. MyModel.create(docs) does new MyModel(doc).save() for every doc in docs.

This function triggers the following middleware.

• save()

Example:

// pass a spread of docs and a callback
Candy.create({ type: 'jelly bean' }, { type: 'snickers' }, function (err, jellybean, snickers) {
  if (err) // ...
});

// pass an array of docs
var array = [{ type: 'jelly bean' }, { type: 'snickers' }];
Candy.create(array, function (err, candies) {
  if (err) // ...

  var jellybean = candies[0];
  var snickers = candies[1];
  // ...
});

// callback is optional; use the returned promise if you like:
var promise = Candy.create({ type: 'jawbreaker' });
promise.then(function (jawbreaker) {
  // ...
})

Requires a replica set running MongoDB >= 3.6.0. Watches the underlying collection for changes using MongoDB change streams.

This function does not trigger any middleware. In particular, it does not trigger aggregate middleware.

Example:

const doc = await Person.create({ name: 'Ned Stark' });
Person.watch().on('change', change => console.log(change));
// Will print from the above `console.log()`:
// { _id: { _data: ... },
//   operationType: 'delete',
//   ns: { db: 'mydb', coll: 'Person' },
//   documentKey: { _id: 5a51b125c5500f5aa094c7bd } }
await doc.remove();

Shortcut for validating an array of documents and inserting them into MongoDB if they're all valid. This function is faster than .create() because it only sends one operation to the server, rather than one for each document.

Mongoose always validates each document before sending insertMany to MongoDB. So if one document has a validation error, no documents will be saved, unless you set the ordered option to false.

This function does not trigger save middleware.

This function triggers the following middleware.

• insertMany()

Example:

var arr = [{ name: 'Star Wars' }, { name: 'The Empire Strikes Back' }];
Movies.insertMany(arr, function(error, docs) {});

Sends multiple insertOne, updateOne, updateMany, replaceOne, deleteOne, and/or deleteMany operations to the MongoDB server in one command. This is faster than sending multiple independent operations (like) if you use create()) because with bulkWrite() there is only one round trip to MongoDB.

Mongoose will perform casting on all operations you provide.

This function does not trigger any middleware, not save() nor update(). If you need to trigger save() middleware for every document use create() instead.

Example:

Character.bulkWrite([
  {
    insertOne: {
      document: {
        name: 'Eddard Stark',
        title: 'Warden of the North'
      }
    }
  },
  {
    updateOne: {
      filter: { name: 'Eddard Stark' },
      // If you were using the MongoDB driver directly, you'd need to do
      // `update: { $set: { title: ... } }` but mongoose adds $set for
      // you.
      update: { title: 'Hand of the King' }
    }
  },
  {
    deleteOne: {
      {
        filter: { name: 'Eddard Stark' }
      }
    }
  }
]).then(handleResult);

Shortcut for creating a new Document from existing raw data, pre-saved in the DB. The document returned has no paths marked as modified initially.

Example:

// hydrate previous data into a Mongoose document
var mongooseCandy = Candy.hydrate({ _id: '54108337212ffb6d459f854c', type: 'jelly bean' });

Updates one document in the database without returning it.

This function triggers the following middleware.

• update()

Examples:

MyModel.update({ age: { $gt: 18 } }, { oldEnough: true }, fn);
MyModel.update({ name: 'Tobi' }, { ferret: true }, { multi: true }, function (err, raw) {
  if (err) return handleError(err);
  console.log('The raw response from Mongo was ', raw);
});

Valid options:

• safe (boolean) safe mode (defaults to value set in schema (true))
• upsert (boolean) whether to create the doc if it doesn't match (false)
• multi (boolean) whether multiple documents should be updated (false)
• runValidators: if true, runs update validators on this command. Update validators validate the update operation against the model's schema.
• setDefaultsOnInsert: if this and upsert are true, mongoose will apply the defaults specified in the model's schema if a new document is created. This option only works on MongoDB >= 2.4 because it relies on MongoDB's $setOnInsert operator.
• strict (boolean) overrides the strict option for this update
• overwrite (boolean) disables update-only mode, allowing you to overwrite the doc (false)

All update values are cast to their appropriate SchemaTypes before being sent.

The callback function receives (err, rawResponse).

• err is the error if any occurred
• rawResponse is the full response from Mongo

Note:

All top level keys which are not atomic operation names are treated as set operations:

Example:

var query = { name: 'borne' };
Model.update(query, { name: 'jason bourne' }, options, callback)

// is sent as
Model.update(query, { $set: { name: 'jason bourne' }}, options, callback)
// if overwrite option is false. If overwrite is true, sent without the $set wrapper.

This helps prevent accidentally overwriting all documents in your collection with { name: 'jason bourne' }.

Note:

Be careful to not use an existing model instance for the update clause (this won't work and can cause weird behavior like infinite loops). Also, ensure that the update clause does not have an _id property, which causes Mongo to return a "Mod on _id not allowed" error.

Note:

To update documents without waiting for a response from MongoDB, do not pass a callback, then call exec on the returned Query:

Comment.update({ _id: id }, { $set: { text: 'changed' }}).exec();

Note:

Although values are casted to their appropriate types when using update, the following are not applied:

• defaults
• setters
• validators
• middleware

If you need those features, use the traditional approach of first retrieving the document.

Model.findOne({ name: 'borne' }, function (err, doc) {
  if (err) ..
  doc.name = 'jason bourne';
  doc.save(callback);
})

Same as update(), except MongoDB will update all documents that match criteria (as opposed to just the first one) regardless of the value of the multi option.

Note updateMany will not fire update middleware. Use pre('updateMany') and post('updateMany') instead.

This function triggers the following middleware.

• updateMany()

Same as update(), except MongoDB will update only the first document that matches criteria regardless of the value of the multi option.

This function triggers the following middleware.

• updateOne()

Same as update(), except MongoDB replace the existing document with the given document (no atomic operators like $set).

This function triggers the following middleware.

• replaceOne()

Executes a mapReduce command.

o is an object specifying all mapReduce options as well as the map and reduce functions. All options are delegated to the driver implementation. See node-mongodb-native mapReduce() documentation for more detail about options.

This function does not trigger any middleware.

Example:

var o = {};
o.map = function () { emit(this.name, 1) }
o.reduce = function (k, vals) { return vals.length }
User.mapReduce(o, function (err, results) {
  console.log(results)
})

Other options:

• query {Object} query filter object.
• sort {Object} sort input objects using this key
• limit {Number} max number of documents
• keeptemp {Boolean, default:false} keep temporary data
• finalize {Function} finalize function
• scope {Object} scope variables exposed to map/reduce/finalize during execution
• jsMode {Boolean, default:false} it is possible to make the execution stay in JS. Provided in MongoDB > 2.0.X
• verbose {Boolean, default:false} provide statistics on job execution time.
• readPreference {String}
• out* {Object, default: {inline:1}} sets the output target for the map reduce job.

* out options:

• {inline:1} the results are returned in an array
• {replace: 'collectionName'} add the results to collectionName: the results replace the collection
• {reduce: 'collectionName'} add the results to collectionName: if dups are detected, uses the reducer / finalize functions
• {merge: 'collectionName'} add the results to collectionName: if dups exist the new docs overwrite the old

If options.out is set to replace, merge, or reduce, a Model instance is returned that can be used for further querying. Queries run against this model are all executed with the lean option; meaning only the js object is returned and no Mongoose magic is applied (getters, setters, etc).

Example:

var o = {};
o.map = function () { emit(this.name, 1) }
o.reduce = function (k, vals) { return vals.length }
o.out = { replace: 'createdCollectionNameForResults' }
o.verbose = true;

User.mapReduce(o, function (err, model, stats) {
  console.log('map reduce took %d ms', stats.processtime)
  model.find().where('value').gt(10).exec(function (err, docs) {
    console.log(docs);
  });
})

// `mapReduce()` returns a promise. However, ES6 promises can only
// resolve to exactly one value,
o.resolveToObject = true;
var promise = User.mapReduce(o);
promise.then(function (res) {
  var model = res.model;
  var stats = res.stats;
  console.log('map reduce took %d ms', stats.processtime)
  return model.find().where('value').gt(10).exec();
}).then(function (docs) {
   console.log(docs);
}).then(null, handleError).end()

Performs aggregations on the models collection.

If a callback is passed, the aggregate is executed and a Promise is returned. If a callback is not passed, the aggregate itself is returned.

This function does not trigger any middleware.

Example:

// Find the max balance of all accounts
Users.aggregate([
  { $group: { _id: null, maxBalance: { $max: '$balance' }}},
  { $project: { _id: 0, maxBalance: 1 }}
]).
then(function (res) {
  console.log(res); // [ { maxBalance: 98000 } ]
});

// Or use the aggregation pipeline builder.
Users.aggregate()
  .group({ _id: null, maxBalance: { $max: '$balance' } })
  .select('-id maxBalance')
  .exec(function (err, res) {
    if (err) return handleError(err);
    console.log(res); // [ { maxBalance: 98 } ]
  });

NOTE:

• Arguments are not cast to the model's schema because $project operators allow redefining the "shape" of the documents at any stage of the pipeline, which may leave documents in an incompatible format.
• The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
• Requires MongoDB >= 2.1

Implements $geoSearch functionality for Mongoose

This function does not trigger any middleware

Example:

var options = { near: [10, 10], maxDistance: 5 };
Locations.geoSearch({ type : "house" }, options, function(err, res) {
  console.log(res);
});

Options:

• near {Array} x,y point to search for
• maxDistance {Number} the maximum distance from the point near that a result can be
• limit {Number} The maximum number of results to return
• lean {Boolean} return the raw object instead of the Mongoose Model

Populates document references.

Available options:

• path: space delimited path(s) to populate
• select: optional fields to select
• match: optional query conditions to match
• model: optional name of the model to use for population
• options: optional query options like sort, limit, etc

Examples:

// populates a single object
User.findById(id, function (err, user) {
  var opts = [
      { path: 'company', match: { x: 1 }, select: 'name' }
    , { path: 'notes', options: { limit: 10 }, model: 'override' }
  ]

  User.populate(user, opts, function (err, user) {
    console.log(user);
  });
});

// populates an array of objects
User.find(match, function (err, users) {
  var opts = [{ path: 'company', match: { x: 1 }, select: 'name' }]

  var promise = User.populate(users, opts);
  promise.then(console.log).end();
})

// imagine a Weapon model exists with two saved documents:
//   { _id: 389, name: 'whip' }
//   { _id: 8921, name: 'boomerang' }
// and this schema:
// new Schema({
//   name: String,
//   weapon: { type: ObjectId, ref: 'Weapon' }
// });

var user = { name: 'Indiana Jones', weapon: 389 }
Weapon.populate(user, { path: 'weapon', model: 'Weapon' }, function (err, user) {
  console.log(user.weapon.name) // whip
})

// populate many plain objects
var users = [{ name: 'Indiana Jones', weapon: 389 }]
users.push({ name: 'Batman', weapon: 8921 })
Weapon.populate(users, { path: 'weapon' }, function (err, users) {
  users.forEach(function (user) {
    console.log('%s uses a %s', users.name, user.weapon.name)
    // Indiana Jones uses a whip
    // Batman uses a boomerang
  });
});
// Note that we didn't need to specify the Weapon model because
// it is in the schema's ref

Query 构造函数，用来构建查询器（query），不过并不需要直接实例化 Query 对象，而是用 Model 的 Model.find() 这些函数。

示例:

const query = MyModel.find(); // `query` 是 `Query` 的一个实例
query.setOptions({ lean : true });
query.collection(MyModel.collection);
query.where('age').gte(21).exec(callback);

// 你也可以实例化一个 query，不过没有必要这么做，除非你是个高级用户又有充分的理由。
const query = new mongoose.Query();

选择是否启用 $geoWithin 的标识。

mongoose.Query.use$geoWithin = false;

MongoDB 2.4 不再赞成使用 $within，而是用 $geoWithin 代替。Mongoose 默认使用 $geoWithin（对 $within 100%后向兼容）。 你如果运行较低版本的 MongoDB，把这个标识置为 false 就能使 within() 继续有效。

把当前 query 转换成自定义、可复用的而且保留当前所有参数（arguments）和选项（options）的构造函数。

示例

// 为 adventure movies 生成一个 query，并从复本集（replica-set）中的主节点读取数据，
// 如果主节点宕机，则从第二节点读取。
var query = Movie.find({ tags: 'adventure' }).read('primaryPreferred');

// 基于上面的设置创建一个自定义 Query 构造函数
var Adventure = query.toConstructor();

// Adventure 就成了 mongoose.Query 的子类，使用方式一致，并且已设置了默认的查询参数和选项。
Adventure().exec(callback)

// 在之前的设置基础上进一步缩小查询结果集
Adventure().where({ name: /^Life/ }).exec(callback);

// 由于 Adventure 是个独立的构造函数，我们也可以向其添加自定义的辅助方法（ helper methods ）
// 和 getter 函数，并且不会影响到全局查询。
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;
  }
})
Adventure().highlyRated.startsWith('Life').exec(callback)

从版本3.7.3开始的新功能

指定一个传给 MongoDB query 的函数或表达式。

示例

query.$where('this.comments.length === 10 || this.name.length === 5')

// or

query.$where(function () {
  return this.comments.length === 10 || this.name.length === 5;
})

注意：

只有当 MongoDB 其他操作符（如 $lt）不能表达你的查询条件时再使用 $where。 使用之前一定要阅读它的所有警告

在链式用法中指定一个 path。

示例

// find 写法：
User.find({age: {$gte: 21, $lte: 65}}, callback);

// where 替换写法：
User.where('age').gte(21).lte(65);

// 也可以传入 query condition
User.find().where({ name: 'vonderful' })

// 链式写法
User
.where('age').gte(21).lte(65)
.where('name', /^vonderful/i)
.where('friends').slice(10)
.exec(callback)

指定一个值，跟 where() 指定的路径做等值比较。

示例

User.where('age').equals(49);

// 等效于

User.where('age', 49);

为 $or 条件指定参数。

示例

query.or([{ color: 'red' }, { status: 'emergency' }])

为 $nor 条件指定参数。

示例

query.nor([{ color: 'green' }, { status: 'ok' }])

为 $and 条件指定参数。

示例

query.and([{ color: 'green' }, { status: 'ok' }])

指定一个 $gt 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

示例

Thing.find().where('age').gt(21)

// or
Thing.find().gt('age', 21)

指定一个 $gte 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $lt 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $lte 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $ne 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $in 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $nin 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $all 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $size 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

示例

MyModel.where('tags').size(0).exec(function (err, docs) {
  if (err) return handleError(err);

  assert(Array.isArray(docs));
  console.log('documents with 0 tags', docs);
})

指定一个 $regex 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $maxDistance 查询条件。

如果只传入一个参数，则对最后的 where() 路径生效。

指定一个 $mod 条件，对文档的过滤规则：属性 path 是个数值，且对 divisor 取模，余数等于 remainder

示例

// products 中 inventory 是奇数的
Product.find().mod('inventory', [2, 1]);
Product.find().where('inventory').mod([2, 1]);
// 这种语法有点儿奇怪，但也支持。
Product.find().where('inventory').mod(2, 1);

指定一个 $exists 查询条件。

示例

// { name: { $exists: true }}
Thing.where('name').exists()
Thing.where('name').exists(true)
Thing.find().exists('name')

// { name: { $exists: false }}
Thing.where('name').exists(false);
Thing.find().exists('name', false);

指定一个 $elemMatch 查询条件。

示例

query.elemMatch('comment', { author: 'autobot', votes: {$gte: 5}})

query.where('comment').elemMatch({ author: 'autobot', votes: {$gte: 5}})

query.elemMatch('comment', function (elem) {
  elem.where('author').equals('autobot');
  elem.where('votes').gte(5);
})

query.where('comment').elemMatch(function (elem) {
  elem.where({ author: 'autobot' });
  elem.where('votes').gte(5);
})

给地理空间（geo-spatial）查询 $within、$geoWithin 指定参数

示例

query.where(path).within().box()
query.where(path).within().circle()
query.where(path).within().geometry()

query.where('loc').within({ center: [50,50], radius: 10, unique: true, spherical: true });
query.where('loc').within({ box: [[40.73, -73.9], [40.7, -73.988]] });
query.where('loc').within({ polygon: [[],[],[],[]] });

query.where('loc').within([], [], []) // polygon
query.where('loc').within([], []) // box
query.where('loc').within({ type: 'LineString', coordinates: [...] }); // geometry

必须 跟 where() 一起使用。

注意:

从 Mongoose 3.7 开始，查询中默认使用 $geoWithin。想改变这种做法，查看 Query.use$geoWithin。

注意:

在 Mongoose 3.7 中，within 由 getter 改变成了 function。如果你需要旧语法，查看 这里。

对数组字段做切片映射（$slice projection）。

示例

query.slice('comments', 5)
query.slice('comments', -5)
query.slice('comments', [10, 5])
query.where('comments').slice(5)
query.where('comments').slice([-10, 5])

指定查询结果的最大条数。

示例

query.limit(20)

注意

不能和 distinct() 一起使用

指定跳过的文档条数。

示例

query.skip(100).limit(20)

注意

不能和 distinct() 一起使用

指定 maxScan 选项

示例

query.maxScan(100)

注意

不能和 distinct() 一起使用

指定 batchSize 选项

示例

query.batchSize(100)

注意

不能和 distinct() 一起使用

指定 comment 选项

示例

query.comment('login query')

注意

不能和 distinct() 一起使用

指定当前 query 是个 snapshot query

示例

query.snapshot() // true
query.snapshot(true)
query.snapshot(false)

注意

不能和 distinct() 一起使用

设置查询会使用的索引

示例

query.hint({ indexA: 1, indexB: -1})

注意

不能和 distinct() 一起使用

指定包含或排除哪些字段（也叫做查询映射 "projection" ）

使用字符串语法时，有 - 前缀的路径会被排除，没有 - 前缀的路径会被选择。 最后，如果路径有前缀 +，将被强制选择，这对于在 schema level 被排除的路径会有用。

映射 必须 只能是 包含 或 排除 二者其一。换句话说，只能要么列举包含的字段（将排除其他所有字段），要么列举排除的字段（将选择其他所有字段）。 _id 字段总会被选择因为 MongoDB 默认会这么做.

示例

// 选择 a 和 b 字段，排除其他的
query.select('a b');

// 排除 c 和 d 字段，选择其他的
query.select('-c -d');

// 如果存在已经有"-"前缀的字段，可以用对象标记法
query.select({ a: 1, b: 1 });
query.select({ c: 0, d: 0 });

// 强制包含已经在 schema level 排除的字段
query.select('+path')

已不赞成使用 设置 slaveOk 选项

Deprecated 从 MongoDB 2.2 版本之后使用 read preferences 代替

示例:

query.slaveOk() // true
query.slaveOk(true)
query.slaveOk(false)

指定读数据的 MongoDB 节点

首选项:

primary - (默认值)    只从主节点读取。如果主节点不可用则报错。不能跟 tags 选项组合使用。
secondary            只有当从节点可用时，从中读取，否则报错。
primaryPreferred     优先读取主节点，不可用时读取从节点。
secondaryPreferred   优先读取从节点，不可用时读取主节点。
nearest              所有操作都读最近的候选节点，不同于其他模式，该选项会随机选取所有主、从节点。

选项别名：

p   primary
pp  primaryPreferred
s   secondary
sp  secondaryPreferred
n   nearest

示例:

new Query().read('primary')
new Query().read('p')  // 等效于 primary

new Query().read('primaryPreferred')
new Query().read('pp') // 等效于 primaryPreferred

new Query().read('secondary')
new Query().read('s')  // 等效于 secondary

new Query().read('secondaryPreferred')
new Query().read('sp') // 等效于 secondaryPreferred

new Query().read('nearest')
new Query().read('n')  // 等效于 nearest

// 读取匹配 tags 的从节点
new Query().read('s', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }])

从 这里 和 这里 参阅更多 read 首选项的用法。

设置查询选项。某些选项只对特定操作生效。

选项：

以下选项只适用于 find(): - tailable - sort - limit - skip - maxscan - batchSize - comment - snapshot - readPreference - hint

以下选项只适用于 update(), updateOne(), updateMany(), replaceOne(), findOneAndUpdate() 和 findByIdAndUpdate(): - upsert - writeConcern

以下选项只适用于 find(), findOne(), findById(), findOneAndUpdate() 和 findByIdAndUpdate(): - lean

以下选项适用于所有操作 （除这些以外 update(), updateOne(), updateMany(), remove(), deleteOne() 和 deleteMany() ）: - maxTimeMS

以下选项适用于所有操作： - collation

以 JSON 对象格式返回当前的 query conditions。

示例:

var query = new Query();
query.find({ a: 1 }).where('b').gt(2);
query.getQuery(); // { a: 1, b: { $gt: 2 } }

以 JSON 对象格式返回当前的 update operations。

示例:

var query = new Query();
query.update({}, { $set: { a: 5 } });
query.getUpdate(); // { $set: { a: 5 } }

设置 lean 选项

那些激活 lean 选项的查询，返回的文档是普通 javascript 对象，而不是 Mongoose Documents。 这些对象没有 save 方法、getters/setters，也没有被赋予其他 Mongoose magic。

示例:

new Query().lean() // true
new Query().lean(true)
new Query().lean(false)

Model.find().lean().exec(function (err, docs) {
  docs[0] instanceof mongoose.Document // false
});

在高性能只读场景下这个选项就 厉害 了，特别是跟 stream 组合使用时。

读取/赋值 query 的 error 标识。如果标识不是 null 或 undefined，exec() promise 会直接执行 reject.

示例:

Query().error(); // 读当前 error 值
Query().error(null); // 空置当前 error
Query().error(new Error('test')); // `exec()` will reject with test
Schema.pre('find', function() {
  if (!this.getQuery().userId) {
    this.error(new Error('Not allowed to query without setting userId'));
  }
});

注意：query casting 在 hooks 之后 执行，所以 cast errors 会覆盖自定义 errors。

示例:

var TestSchema = new Schema({ num: Number });
var TestModel = db.model('Test', TestSchema);
TestModel.find({ num: 'not a number' }).error(new Error('woops')).exec(function(error) {
  // `error` will be a cast error because `num` failed to cast
});

Getter/setter around the current mongoose-specific options for this query (populate, lean, etc.)

查询文档

如果不传入 callback 查询不会被执行。实际执行时，查询结果是个文档数组。

示例

query.find({ name: 'Los Pollos Hermanos' }).find(callback)

把另一个 Query 或者 condition 对象合并到当前 query。

如果传入的是一个 Query，条件对象、字段选择和选项都会被合并。

3.7.0版本新功能

Adds a collation to this op (MongoDB 3.4 and up)

声明一个 findOne 查询。传给回调函数的查询结果是第一个查到的文档。

传入 callback 时启动查询。结果是单个文档。

• 注意： conditions 是可选的，如果 conditions 是 null 或 undefined， mongoose 会向 MongoDB 发送一个空的 findOne 指令，返回结果会是一个随机文档。 如果要按 _id 进行查询，可以用 Model.findById()。

这个函数触发以下中间件

• findOne()

示例

var query  = Kitten.where({ color: 'white' });
query.findOne(function (err, kitten) {
  if (err) return handleError(err);
  if (kitten) {
    // 如果没有匹配的文档 kitten 是 null
  }
});

声明一个 count 查询

传入 callback 时启动查询

这个函数触发以下中间件

• count()

示例:

var countQuery = model.where({ 'color': 'black' }).count();

query.count({ color: 'black' }).count(callback)

query.count({ color: 'black' }, callback)

query.where('color', 'black').count(function (err, count) {
  if (err) return handleError(err);
  console.log('there are %d kittens', count);
})

声明或执行 distict() 操作

传入 callback 启动查询

这个函数不触发中间件

示例

distinct(field, conditions, callback)
distinct(field, conditions)
distinct(field, callback)
distinct(field)
distinct(callback)
distinct()

设置排序

如果传入的参数是个对象，字段值可以是 asc, desc, ascending, descending, 1 和 -1。

如果传入参数是字符串，它得是以空格间隔的字段路径名列表。每个字段的排列顺序默认是正序，如果字段名有 - 前缀， 那么这个字段是倒序。

示例

// 按照 "field" 字段正序、"test" 字段倒序排列
query.sort({ field: 'asc', test: -1 });

// 等效于
query.sort('field -test');

注意

不能和 distinct() 一起使用

声明/执行删除操作

这个函数不触发中间件

示例

Model.remove({ artist: 'Anne Murray' }, callback)

注意

只有当传入 callback 时操作才会被执行。如果要强制不带 callback 就执行，你得先调用 remove() 然后调用 exec() 来让它执行。

// 不会执行
var query = Model.find().remove({ name: 'Anne Murray' })

// 会被执行
query.remove({ name: 'Anne Murray' }, callback)
query.remove({ name: 'Anne Murray' }).remove(callback)

// 没有 callback 就执行
query.exec()

// 总结
query.remove(conds, fn); // 执行
query.remove(conds)
query.remove(fn) // 执行
query.remove()

声明/执行 deleteOne() 操作。 功能类似 remove，不过会忽略 single 选项最多删除一条文档。

这个函数不触发中间件.

示例

Character.deleteOne({ name: 'Eddard Stark' }, callback)
Character.deleteOne({ name: 'Eddard Stark' }).then(next)

声明 / 执行一次 deleteMany() 操作。功能类似于 remove，不过会忽略 single 选项，删除集合中 每一条 匹配条件的文档。

这个函数不触发中间件

示例

Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }, callback)
Character.deleteMany({ name: /Stark/, age: { $gte: 18 } }).then(next)

向 mongodb 发起一条 findAndModify 更新指令。

查到一条匹配的文档，依据 doc 参数和 options 选项更新文档，向回调函数返回查询到的文档（如果有的话）。如果传入了 callback 则查询会立即执行。

这个函数触发以下中间件

• findOneAndUpdate()

支持的选项

• new: bool - 如果设置为 true，不再返回旧文档而是更新后的文档。默认值 false（从 4.0 版本开始）
• upsert: bool - 如果文档不存在则插入一条新数据。默认值 false
• fields: {Object|String} - 选择字段。等效于 .select(fields).findOneAndUpdate()
• sort: 如果查询条件匹配多条文档，可以设置排序条件以确定更新哪条文档（排序后的第一条）
• maxTimeMS: 对查询设置时间限制 - 需要 mongodb 2.6.0 及以上版本
• runValidators: 如果值为 true，更新操作执行时会做 update validators 。 Update validators 会依照 model 的 schema 对更新操作做校验。
• setDefaultsOnInsert: 如果该选项和 upsert 都是 true， mongoose 会在插入新文档时应用 schema 中指定的 默认值。该选项只会在 MongoDB 2.4 版本及以上生效，因为它依赖 MongoDB 的 $setOnInsert 操作符。
• rawResult: 如果值为 true，将返回 MongoDB 驱动的 原生结果（raw result）
• context: string - if set to 'query' and runValidators is on, this will refer to the query in custom validator functions that update validation runs. Does nothing if runValidators is false.

回调函数签名

function(error, doc) {
  // error: 发生错误时有值
  // doc: 如果 `new: false` 则为更新前的文档；如果 `new: true` 则为更新后的文档
}

示例

query.findOneAndUpdate(conditions, update, options, callback) // executes
query.findOneAndUpdate(conditions, update, options)  // returns Query
query.findOneAndUpdate(conditions, update, callback) // executes
query.findOneAndUpdate(conditions, update)           // returns Query
query.findOneAndUpdate(update, callback)             // returns Query
query.findOneAndUpdate(update)                       // returns Query
query.findOneAndUpdate(callback)                     // executes
query.findOneAndUpdate()                             // returns Query

发起一条 mongodb findAndModify 删除指令。

查询一条匹配的文档，把它删掉，并回传给回调函数。如果有 callback 参数，删除指令会立即执行。

这个函数触发以下中间件

• findOneAndRemove()

可选项

• sort: 设置排序，如果多条文档匹配查询条件，将影响到实际更新哪条文档（只会更新第一条）
• maxTimeMS: 对查询设置时间限制 - 需要 mongodb 2.6.0 及以上版本
• rawResult: 如果设置为 true，返回结果将是 MongoDB 驱动的原生结果

回调函数签名

function(error, doc) {
  // error: 可能爆出的错误
  // doc: 若 `new = false` 则是更新之前的文档，若 `new = true` 则是更新之后的文档
}

示例

A.where().findOneAndRemove(conditions, options, callback) // executes
A.where().findOneAndRemove(conditions, options)  // return Query
A.where().findOneAndRemove(conditions, callback) // executes
A.where().findOneAndRemove(conditions) // returns Query
A.where().findOneAndRemove(callback)   // executes
A.where().findOneAndRemove()           // returns Query

声明且（/或）执行当前查询为 update() 操作。

被传入的路径中非原子（$atomic）的操作，会以 $set 形式执行。

这个函数触发以下中间件

• update()

示例

Model.where({ _id: id }).update({ title: 'words' })

// becomes

Model.where({ _id: id }).update({ $set: { title: 'words' }})

可用选项:

• safe (boolean) 安全模式（默认值同 schema 中的定义（true））
• upsert (boolean) 没有匹配文档时是否创建新文档 (false)
• multi (boolean) 是否更新多条文档 (false)
• runValidators: 如果设为 true，这条命令将执行 update validators 。 Update validators 依据 schema 校验更新选项。
• setDefaultsOnInsert: 如果该选项跟 upsert 都为 true，创建新文档时 mongoose 会应用 schema 中指定的 默认值 。 该选项只能用于 MongoDB >= 2.4 ，因为依赖于 MongoDB's $setOnInsert 操作符。
• strict (boolean) 覆盖当前 update 的 strict 选项
• overwrite (boolean) 禁用 update-only 模式，允许你替换整个文档 (false)
• context (string) if set to 'query' and runValidators is on, this will refer to the query in custom validator functions that update validation runs. 如果 runValidators 是 false 则什么都不做。

注意

doc 参数被传入空对象 {} 会造成一次空操作，除非 overwrite 选项被激活。overwrite 选项没有激活的情况下，update 命令不会发送给 MongoDB 而被忽略，回调函数直接被调用，以防止数据集合的文档被意外覆盖。

注意

只有传入了回调函数，操作才会被执行。要想强制执行回调，你得先调用 update() 然后用 exec() 方法使其执行。

var q = Model.where({ _id: id });
q.update({ $set: { name: 'bob' }}).update(); // not executed

q.update({ $set: { name: 'bob' }}).exec(); // executed

// 非 $atomic ops 的键都会被转换成 $set。
// 本句执行跟上例一样的命令。
q.update({ name: 'bob' }).exec();

// 用空文档替换更新
var q = Model.where({ _id: id }).setOptions({ overwrite: true })
q.update({ }, callback); // executes

// 用空文档进行多条替换更新
var q = Model.where({ _id: id });
q.setOptions({ multi: true, overwrite: true })
q.update({ });
q.update(callback); // executed

// 多条更新
Model.where()
     .update({ name: /^match/ }, { $set: { arr: [] }}, { multi: true }, callback)

// 再多一例多条更新
Model.where()
     .setOptions({ multi: true })
     .update({ $set: { arr: [] }}, callback)

// 默认是单条更新
Model.where({ email: 'address@example.com' })
     .update({ $inc: { counter: 1 }}, callback)

API summary

update(criteria, doc, options, cb) // executes
update(criteria, doc, options)
update(criteria, doc, cb) // executes
update(criteria, doc)
update(doc, cb) // executes
update(doc)
update(cb) // executes
update(true) // executes
update()

声明且（/或）执行当前查询为 updateMany() 操作。不同于 update() 的是， MongoDB 会忽略 multi 选项，更新 所有 匹配 criteria 的文档（而非只是第一条）。

注意 updateMany 不会 触发 update 中间件。可以用 pre('updateMany') 和 post('updateMany') 代替。

这个函数触发以下中间件

• updateMany()

声明且（/或）执行当前查询为 updateMany() 操作。不同于 update() 的是，MongoDB 会忽略 multi 选项，只 更新第一条匹配 criteria 的文档。

注意 updateOne 不会 触发 update 中间件。可以用 pre('updateOne') 和 post('updateOne') 代替。

这个函数触发以下中间件

• updateOne()

声明且（/或）执行当前查询为 replaceOne() 操作。不同于 update() 的是，MongoDB 不接受原子操作符（$set等）直接替换存在的文档。

注意 replaceOne 不会 触发 update 中间件。可以用 pre('replaceOne') 和 post('replaceOne') 代替。

这个函数触发以下中间件

• replaceOne()

执行查询

示例:

var promise = query.exec();
var promise = query.exec('update');

query.exec(callback);
query.exec('find', callback);

执行返回 Promise 的查询，成功返回 doc(s)，失败返回 error

执行返回 Promise 的查询，成功返回 doc(s)，失败返回 error。 类似于 .then() 但是只接受失败句柄。

指定哪些字段需要关联查询（populated）其他文档。

示例:

Kitten.findOne().populate('owner').exec(function (err, kitten) {
  console.log(kitten.owner.name) // Max
})

Kitten.find().populate({
    path: 'owner'
  , select: 'name'
  , match: { color: 'black' }
  , options: { sort: { name: -1 }}
}).exec(function (err, kittens) {
  console.log(kittens[0].owner.name) // Zoopa
})

// alternatively
Kitten.find().populate('owner', 'name', null, {sort: { name: -1 }}).exec(function (err, kittens) {
  console.log(kittens[0].owner.name) // Zoopa
})

字段的表关联在查询结束并收到响应之后执行。每个指定表关联的路径都由一个独立的查询执行。收到所有查询的响应之后，查询结果被传递给回调函数。

Casts this query to the schema of model

注意

If obj is present, it is cast instead of this query.

返回对 mongodb driver cursor 的封装。 QueryCursor 暴露了一个 Streams3 接口，和一个 .next() 函数。

.cursor() 函数触发 find 的前置钩子，但不会触发后置钩子。

示例

// 有2种方式使用游标。第一种，流式:
  find({ name: /^hello/ }).
  cursor().
  on('data', function(doc) { console.log(doc); }).
  on('end', function() { console.log('Done!'); });

// 或者使用 `.next()` 手动获取流中的下一个文档。
// `.next()` 返回一个 promise，你可以用 promises 或者 callbacks.
var cursor = Thing.find({ name: /^hello/ }).cursor();
cursor.next(function(error, doc) {
  console.log(doc);
});

// 由于 `.next()` 返回一个 promise，你可以使用 co
// 很容易地遍历所有文档而不用把它们都加载到内存里
co(function*() {
  const cursor = Thing.find({ name: /^hello/ }).cursor();
  for (let doc = yield cursor.next(); doc != null; doc = yield cursor.next()) {
    console.log(doc);
  }
});

可选项

• transform: 可选 接收一个 mongoose document 参数的函数。函数的返回值会成为 data 事件的响应结果和 .next() 函数的返回值。

DEPRECATED Alias of maxScan

设置 tailable 选项 (capped collections 中会使用).

示例

query.tailable() // true
query.tailable(true)
query.tailable(false)

注意

不能和 distinct() 一起使用

Declares an intersects query for geometry().

示例

query.where('path').intersects().geometry({
    type: 'LineString'
  , coordinates: [[180.0, 11.0], [180, 9.0]]
})

query.where('path').intersects({
    type: 'LineString'
  , coordinates: [[180.0, 11.0], [180, 9.0]]
})

注意:

MUST be used after where().

注意:

In Mongoose 3.7, intersects changed from a getter to a function. If you need the old syntax, use this.

Specifies a $geometry condition

示例

var polyA = [[[ 10, 20 ], [ 10, 40 ], [ 30, 40 ], [ 30, 20 ]]]
query.where('loc').within().geometry({ type: 'Polygon', coordinates: polyA })

// or
var polyB = [[ 0, 0 ], [ 1, 1 ]]
query.where('loc').within().geometry({ type: 'LineString', coordinates: polyB })

// or
var polyC = [ 0, 0 ]
query.where('loc').within().geometry({ type: 'Point', coordinates: polyC })

// or
query.where('loc').intersects().geometry({ type: 'Point', coordinates: polyC })

The argument is assigned to the most recent path passed to where().

注意:

geometry() must come after either intersects() or within().

The object argument must contain type and coordinates properties. - type {String} - coordinates {Array}

Specifies a $near or $nearSphere condition

These operators return documents sorted by distance.

示例

query.where('loc').near({ center: [10, 10] });
query.where('loc').near({ center: [10, 10], maxDistance: 5 });
query.where('loc').near({ center: [10, 10], maxDistance: 5, spherical: true });
query.near('loc', { center: [10, 10], maxDistance: 5 });

DEPRECATED Specifies a $nearSphere condition

示例

query.where('loc').nearSphere({ center: [10, 10], maxDistance: 5 });

Deprecated. Use query.near() instead with the spherical option set to true.

示例

query.where('loc').near({ center: [10, 10], spherical: true });

Specifies a $polygon condition

示例

query.where('loc').within().polygon([10,20], [13, 25], [7,15])
query.polygon('loc', [10,20], [13, 25], [7,15])

Specifies a $box condition

示例

var lowerLeft = [40.73083, -73.99756]
var upperRight= [40.741404,  -73.988135]

query.where('loc').within().box(lowerLeft, upperRight)
query.box({ ll : lowerLeft, ur : upperRight })

Specifies a $center or $centerSphere condition.

示例

var area = { center: [50, 50], radius: 10, unique: true }
query.where('loc').within().circle(area)
// alternatively
query.circle('loc', area);

// spherical calculations
var area = { center: [50, 50], radius: 10, unique: true, spherical: true }
query.where('loc').within().circle(area)
// alternatively
query.circle('loc', area);

New in 3.7.0

DEPRECATED Alias for circle

Deprecated. Use circle instead.

DEPRECATED Specifies a $centerSphere condition

Deprecated. Use circle instead.

示例

var area = { center: [50, 50], radius: 10 };
query.where('loc').within().centerSphere(area);

Determines if field selection has been made.

Determines if inclusive field selection has been made.

query.selectedInclusively() // false
query.select('name')
query.selectedInclusively() // true

Determines if exclusive field selection has been made.

query.selectedExclusively() // false
query.select('-name')
query.selectedExclusively() // true
query.selectedInclusively() // false

Aggregate constructor used for building aggregation pipelines. Do not instantiate this class directly, use Model.aggregate() instead.

Example:

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

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

Note:

• The documents returned are plain javascript objects, not mongoose documents (since any shape of document can be returned).
• Mongoose does not cast pipeline stages. The below will not work unless _id is a string in the database

  new Aggregate([{ $match: { _id: '00000000000000000000000a' } }]);
  // Do this instead to cast to an ObjectId
  new Aggregate([{ $match: { _id: mongoose.Types.ObjectId('00000000000000000000000a') } }]);

Binds this aggregate to a model.

Appends new operators to this aggregate pipeline

Examples:

aggregate.append({ $project: { field: 1 }}, { $limit: 2 });

// or pass an array
var pipeline = [{ $match: { daw: 'Logic Audio X' }} ];
aggregate.append(pipeline);

Appends a new $addFields operator to this aggregate pipeline. Requires MongoDB v3.4+ to work

Examples:

// adding new fields based on existing fields
aggregate.addFields({
    newField: '$b.nested'
  , plusTen: { $add: ['$val', 10]}
  , sub: {
       name: '$a'
    }
})

// etc
aggregate.addFields({ salary_k: { $divide: [ "$salary", 1000 ] } });

Appends a new $project operator to this aggregate pipeline.

Mongoose query selection syntax is also supported.

Examples:

// include a, include b, exclude _id
aggregate.project("a b -_id");

// or you may use object notation, useful when
// you have keys already prefixed with a "-"
aggregate.project({a: 1, b: 1, _id: 0});

// reshaping documents
aggregate.project({
    newField: '$b.nested'
  , plusTen: { $add: ['$val', 10]}
  , sub: {
       name: '$a'
    }
})

// etc
aggregate.project({ salary_k: { $divide: [ "$salary", 1000 ] } });

Appends a new custom $group operator to this aggregate pipeline.

Examples:

aggregate.group({ _id: "$department" });

Appends a new custom $match operator to this aggregate pipeline.

Examples:

aggregate.match({ department: { $in: [ "sales", "engineering" ] } });

Appends a new $skip operator to this aggregate pipeline.

Examples:

aggregate.skip(10);

Appends a new $limit operator to this aggregate pipeline.

Examples:

aggregate.limit(10);

Appends a new $geoNear operator to this aggregate pipeline.

NOTE:

MUST be used as the first operator in the pipeline.

Examples:

aggregate.near({
  near: [40.724, -73.997],
  distanceField: "dist.calculated", // required
  maxDistance: 0.008,
  query: { type: "public" },
  includeLocs: "dist.location",
  uniqueDocs: true,
  num: 5
});

Appends new custom $unwind operator(s) to this aggregate pipeline.

Note that the $unwind operator requires the path name to start with '$'. Mongoose will prepend '$' if the specified field doesn't start '$'.

Examples:

aggregate.unwind("tags");
aggregate.unwind("a", "b", "c");

Appends a new $replaceRoot operator to this aggregate pipeline.

Note that the $replaceRoot operator requires the new root to start with '$'. Mongoose will prepend '$' if the specified field doesn't start '$'.

Examples:

aggregate.replaceRoot("user");

Appends a new $count operator to this aggregate pipeline.

Examples:

aggregate.count("userCount");

Appends a new $sortByCount operator to this aggregate pipeline. Accepts either a string field name or a pipeline object.

Note that the $sortByCount operator requires the new root to start with '$'. Mongoose will prepend '$' if the specified field name doesn't start with '$'.

Examples:

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

Appends new custom $lookup operator(s) to this aggregate pipeline.

Examples:

aggregate.lookup({ from: 'users', localField: 'userId', foreignField: '_id', as: 'users' });

Appends new custom $graphLookup operator(s) to this aggregate pipeline, performing a recursive search on a collection.

Note that graphLookup can only consume at most 100MB of memory, and does not allow disk use even if { allowDiskUse: true } is specified.

Examples:

// Suppose we have a collection of courses, where a document might look like `{ _id: 0, name: 'Calculus', prerequisite: 'Trigonometry'}` and `{ _id: 0, name: 'Trigonometry', prerequisite: 'Algebra' }`
 aggregate.graphLookup({ from: 'courses', startWith: '$prerequisite', connectFromField: 'prerequisite', connectToField: 'name', as: 'prerequisites', maxDepth: 3 }) // this will recursively search the 'courses' collection up to 3 prerequisites

Appends new custom $sample operator(s) to this aggregate pipeline.

Examples:

aggregate.sample(3); // Add a pipeline that picks 3 random documents

Appends a new $sort operator to this aggregate pipeline.

If an object is passed, values allowed are asc, desc, ascending, descending, 1, and -1.

If a string is passed, it must be a space delimited list of path names. The sort order of each path is ascending unless the path name is prefixed with - which will be treated as descending.

Examples:

// these are equivalent
aggregate.sort({ field: 'asc', test: -1 });
aggregate.sort('field -test');

Sets the readPreference option for the aggregation query.

Example:

Model.aggregate(..).read('primaryPreferred').exec(callback)

Execute the aggregation with explain

Example:

Model.aggregate(..).explain(callback)

Sets the allowDiskUse option for the aggregation query (ignored for < 2.6.0)

Example:

Model.aggregate(..).allowDiskUse(true).exec(callback)

Sets the hint option for the aggregation query (ignored for < 3.6.0)

Example:

Model.aggregate(..).hint({ qty: 1, category: 1 } }).exec(callback)

Lets you set arbitrary options, for middleware or plugins.

Example:

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

Sets the cursor option option for the aggregation query (ignored for < 2.6.0). Note the different syntax below: .exec() returns a cursor object, and no callback is necessary.

Example:

var cursor = Model.aggregate(..).cursor({ batchSize: 1000 }).exec();
cursor.each(function(error, doc) {
  // use doc
});

Adds a cursor flag

Example:

Model.aggregate(..).addCursorFlag('noCursorTimeout', true).exec();

Adds a collation

Example:

Model.aggregate(..).collation({ locale: 'en_US', strength: 1 }).exec();

Combines multiple aggregation pipelines.

Example:

Model.aggregate(...)
 .facet({
   books: [{ groupBy: '$author' }],
   price: [{ $bucketAuto: { groupBy: '$price', buckets: 2 } }]
 })
 .exec();

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

Returns the current pipeline

Example:

MyModel.aggregate().match({ test: 1 }).pipeline(); // [{ $match: { test: 1 } }]

Executes the aggregate pipeline on the currently bound Model.

Example:

aggregate.exec(callback);

// Because a promise is returned, the `callback` is optional.
var promise = aggregate.exec();
promise.then(..);

Provides promise for aggregate.

Example:

Model.aggregate(..).then(successCallback, errorCallback);

SchemaType constructor. Do not instantiate SchemaType directly. Mongoose converts your schema paths into SchemaTypes automatically.

Example:

const schema = new Schema({ name: String });
schema.path('name') instanceof SchemaType; // true

Sets a default value for this SchemaType.

Example:

var schema = new Schema({ n: { type: Number, default: 10 })
var M = db.model('M', schema)
var m = new M;
console.log(m.n) // 10

Defaults can be either functions which return the value to use as the default or the literal value itself. Either way, the value will be cast based on its schema type before being set during document creation.

Example:

// values are cast:
var schema = new Schema({ aNumber: { type: Number, default: 4.815162342 }})
var M = db.model('M', schema)
var m = new M;
console.log(m.aNumber) // 4.815162342

// default unique objects for Mixed types:
var schema = new Schema({ mixed: Schema.Types.Mixed });
schema.path('mixed').default(function () {
  return {};
});

// if we don't use a function to return object literals for Mixed defaults,
// each document will receive a reference to the same object literal creating
// a "shared" object instance:
var schema = new Schema({ mixed: Schema.Types.Mixed });
schema.path('mixed').default({});
var M = db.model('M', schema);
var m1 = new M;
m1.mixed.added = 1;
console.log(m1.mixed); // { added: 1 }
var m2 = new M;
console.log(m2.mixed); // { added: 1 }

Declares the index options for this schematype.

Example:

var s = new Schema({ name: { type: String, index: true })
var s = new Schema({ loc: { type: [Number], index: 'hashed' })
var s = new Schema({ loc: { type: [Number], index: '2d', sparse: true })
var s = new Schema({ loc: { type: [Number], index: { type: '2dsphere', sparse: true }})
var s = new Schema({ date: { type: Date, index: { unique: true, expires: '1d' }})
Schema.path('my.path').index(true);
Schema.path('my.date').index({ expires: 60 });
Schema.path('my.path').index({ unique: true, sparse: true });

NOTE:

Indexes are created in the background by default. Specify background: false to override.

Direction doesn't matter for single key indexes

Declares an unique index.

Example:

var s = new Schema({ name: { type: String, unique: true }});
Schema.path('name').index({ unique: true });

NOTE: violating the constraint returns an E11000 error from MongoDB when saving, not a Mongoose validation error.

Declares a full text index.

Example:

var s = new Schema({name : {type: String, text : true })
 Schema.path('name').index({text : true});

Declares a sparse index.

Example:

var s = new Schema({ name: { type: String, sparse: true })
Schema.path('name').index({ sparse: true });

Adds a setter to this schematype.

Example:

function capitalize (val) {
  if (typeof val !== 'string') val = '';
  return val.charAt(0).toUpperCase() + val.substring(1);
}

// defining within the schema
var s = new Schema({ name: { type: String, set: capitalize }});

// or with the SchemaType
var s = new Schema({ name: String })
s.path('name').set(capitalize);

Setters allow you to transform the data before it gets to the raw mongodb document or query.

Suppose you are implementing user registration for a website. Users provide an email and password, which gets saved to mongodb. The email is a string that you will want to normalize to lower case, in order to avoid one email having more than one account -- e.g., otherwise, avenue@q.com can be registered for 2 accounts via avenue@q.com and AvEnUe@Q.CoM.

You can set up email lower case normalization easily via a Mongoose setter.

function toLower(v) {
  return v.toLowerCase();
}

var UserSchema = new Schema({
  email: { type: String, set: toLower }
});

var User = db.model('User', UserSchema);

var user = new User({email: 'AVENUE@Q.COM'});
console.log(user.email); // 'avenue@q.com'

// or
var user = new User();
user.email = 'Avenue@Q.com';
console.log(user.email); // 'avenue@q.com'
User.updateOne({ _id: _id }, { $set: { email: 'AVENUE@Q.COM' } }); // update to 'avenue@q.com'

As you can see above, setters allow you to transform the data before it stored in MongoDB, or before executing a query.

NOTE: we could have also just used the built-in lowercase: true SchemaType option instead of defining our own function.

new Schema({ email: { type: String, lowercase: true }})

Setters are also passed a second argument, the schematype on which the setter was defined. This allows for tailored behavior based on options passed in the schema.

function inspector (val, schematype) {
  if (schematype.options.required) {
    return schematype.path + ' is required';
  } else {
    return val;
  }
}

var VirusSchema = new Schema({
  name: { type: String, required: true, set: inspector },
  taxonomy: { type: String, set: inspector }
})

var Virus = db.model('Virus', VirusSchema);
var v = new Virus({ name: 'Parvoviridae', taxonomy: 'Parvovirinae' });

console.log(v.name);     // name is required
console.log(v.taxonomy); // Parvovirinae

You can also use setters to modify other properties on the document. If you're setting a property name on a document, the setter will run with this as the document. Be careful, in mongoose 5 setters will also run when querying by name with this as the query.

const nameSchema = new Schema({ name: String, keywords: [String] });
nameSchema.path('name').set(function(v) {
  // Need to check if `this` is a document, because in mongoose 5
  // setters will also run on queries, in which case `this` will be a
  // mongoose query object.
  if (this instanceof Document && v != null) {
    this.keywords = v.split(' ');
  }
  return v;
});

Adds a getter to this schematype.

Example:

function dob (val) {
  if (!val) return val;
  return (val.getMonth() + 1) + "/" + val.getDate() + "/" + val.getFullYear();
}

// defining within the schema
var s = new Schema({ born: { type: Date, get: dob })

// or by retreiving its SchemaType
var s = new Schema({ born: Date })
s.path('born').get(dob)

Getters allow you to transform the representation of the data as it travels from the raw mongodb document to the value that you see.

Suppose you are storing credit card numbers and you want to hide everything except the last 4 digits to the mongoose user. You can do so by defining a getter in the following way:

function obfuscate (cc) {
  return '****-****-****-' + cc.slice(cc.length-4, cc.length);
}

var AccountSchema = new Schema({
  creditCardNumber: { type: String, get: obfuscate }
});

var Account = db.model('Account', AccountSchema);

Account.findById(id, function (err, found) {
  console.log(found.creditCardNumber); // '****-****-****-1234'
});

Getters are also passed a second argument, the schematype on which the getter was defined. This allows for tailored behavior based on options passed in the schema.

function inspector (val, schematype) {
  if (schematype.options.required) {
    return schematype.path + ' is required';
  } else {
    return schematype.path + ' is not';
  }
}

var VirusSchema = new Schema({
  name: { type: String, required: true, get: inspector },
  taxonomy: { type: String, get: inspector }
})

var Virus = db.model('Virus', VirusSchema);

Virus.findById(id, function (err, virus) {
  console.log(virus.name);     // name is required
  console.log(virus.taxonomy); // taxonomy is not
})

Adds validator(s) for this document path.

Validators always receive the value to validate as their first argument and must return Boolean. Returning false means validation failed.

The error message argument is optional. If not passed, the default generic error message template will be used.

Examples:

// make sure every value is equal to "something"
function validator (val) {
  return val == 'something';
}
new Schema({ name: { type: String, validate: validator }});

// with a custom error message

var custom = [validator, 'Uh oh, {PATH} does not equal "something".']
new Schema({ name: { type: String, validate: custom }});

// adding many validators at a time

var many = [
    { validator: validator, msg: 'uh oh' }
  , { validator: anotherValidator, msg: 'failed' }
]
new Schema({ name: { type: String, validate: many }});

// or utilizing SchemaType methods directly:

var schema = new Schema({ name: 'string' });
schema.path('name').validate(validator, 'validation of `{PATH}` failed with value `{VALUE}`');

Error message templates:

From the examples above, you may have noticed that error messages support basic templating. There are a few other template keywords besides {PATH} and {VALUE} too. To find out more, details are available here

Asynchronous validation:

Passing a validator function that receives two arguments tells mongoose that the validator is an asynchronous validator. The first argument passed to the validator function is the value being validated. The second argument is a callback function that must called when you finish validating the value and passed either true or false to communicate either success or failure respectively.

schema.path('name').validate({
  isAsync: true,
  validator: function (value, respond) {
    doStuff(value, function () {
      ...
      respond(false); // validation failed
    });
  },
  message: 'Custom error message!' // Optional
});

// Can also return a promise
schema.path('name').validate({
  validator: function (value) {
    return new Promise(function (resolve, reject) {
      resolve(false); // validation failed
    });
  }
});

You might use asynchronous validators to retreive other documents from the database to validate against or to meet other I/O bound validation needs.

Validation occurs pre('save') or whenever you manually execute document#validate.

If validation fails during pre('save') and no callback was passed to receive the error, an error event will be emitted on your Models associated db connection, passing the validation error object along.

var conn = mongoose.createConnection(..);
conn.on('error', handleError);

var Product = conn.model('Product', yourSchema);
var dvd = new Product(..);
dvd.save(); // emits error on the `conn` above

If you desire handling these errors at the Model level, attach an error listener to your Model and the event will instead be emitted there.

// registering an error listener on the Model lets us handle errors more locally
Product.on('error', handleError);

Adds a required validator to this SchemaType. The validator gets added to the front of this SchemaType's validators array using unshift().

Example:

var s = new Schema({ born: { type: Date, required: true })

// or with custom error message

var s = new Schema({ born: { type: Date, required: '{PATH} is required!' })

// or with a function

var s = new Schema({
  userId: ObjectId,
  username: {
    type: String,
    required: function() { return this.userId != null; }
  }
})

// or with a function and a custom message
var s = new Schema({
  userId: ObjectId,
  username: {
    type: String,
    required: [
      function() { return this.userId != null; },
      'username is required if id is specified'
    ]
  }
})

// or through the path API

Schema.path('name').required(true);

// with custom error messaging

Schema.path('name').required(true, 'grrr :( ');

// or make a path conditionally required based on a function
var isOver18 = function() { return this.age >= 18; };
Schema.path('voterRegistrationId').required(isOver18);

The required validator uses the SchemaType's checkRequired function to determine whether a given value satisfies the required validator. By default, a value satisfies the required validator if val != null (that is, if the value is not null nor undefined). However, most built-in mongoose schema types override the default checkRequired function:

Sets default select() behavior for this path.

Set to true if this path should always be included in the results, false if it should be excluded by default. This setting can be overridden at the query level.

Example:

T = db.model('T', new Schema({ x: { type: String, select: true }}));
T.find(..); // field x will always be selected ..
// .. unless overridden;
T.find().select('-x').exec(callback);

VirtualType constructor

This is what mongoose uses to define virtual attributes via Schema.prototype.virtual.

Example:

var fullname = schema.virtual('fullname');
fullname instanceof mongoose.VirtualType // true

Defines a getter.

Example:

var virtual = schema.virtual('fullname');
virtual.get(function () {
  return this.name.first + ' ' + this.name.last;
});

Defines a setter.

Example:

var virtual = schema.virtual('fullname');
virtual.set(function (v) {
  var parts = v.split(' ');
  this.name.first = parts[0];
  this.name.last = parts[1];
});

Applies getters to value using optional scope.

Applies setters to value using optional scope.

MongooseError constructor

The default built-in validator error messages.

An instance of this error class will be returned when save() fails because the underlying document was not found. The constructor takes one parameter, the conditions that mongoose passed to update() when trying to update the document.

An instance of this error class will be returned when mongoose failed to cast a value.

An instance of this error class will be returned when validation failed.