If arguments are passed, they are proxied to either
Connection#open or
Connection#openSet appropriately.

Options passed take precedence over options included in connection strings.

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

// connecting to multiple mongos
var uri = 'mongodb://hostA:27501,hostB:27501';
var opts = { mongos: true };
mongoose.connect(uri, opts);

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

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

Example:

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

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 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 = mongoose.model('Actor', schema, collectionName)

Note:

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

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

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

Example:

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

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

Example:

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

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

Example:

query.stream().pipe(writeStream [, options])

var stream = Model.find().stream();

stream.on('data', function (doc) {
  // do something with the mongoose document
}).on('error', function (err) {
  // handle the error
}).on('close', function () {
  // the stream is closed
});

The stream interface allows us to simply "plug-in" to other Node.js 0.8 style write streams.

Model.where('created').gte(twoWeeksAgo).stream().pipe(writeStream);

Valid options

• transform: optional function which accepts a mongoose document. The return value of the function will be emitted on data.

Example

// JSON.stringify all documents before emitting
var stream = Thing.find().stream({ transform: JSON.stringify });
stream.pipe(writeStream);

NOTE: plugging into an HTTP response will *not* work out of the box. Those streams expect only strings or buffers to be emitted, so first formatting our documents as strings/buffers is necessary.

NOTE: these streams are Node.js 0.8 style read streams which differ from Node.js 0.10 style. Node.js 0.10 streams are not well tested yet and are not guaranteed to work.

For practical reasons, a Connection equals a Db.

options is a hash with the following possible properties:

config  - passed to the connection config instance
db      - passed to the connection db instance
server  - passed to the connection server instance(s)
replset - passed to the connection ReplSet instance
user    - username for authentication
pass    - password for authentication
auth    - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate)

Notes:

Mongoose forces the db option forceServerObjectId false and cannot be overridden.
Mongoose defaults the server auto_reconnect options to true which can be overridden.
See the node-mongodb-native driver instance for options that it understands.

Options passed take precedence over options included in connection strings.

Example:

var db = mongoose.createConnection();
db.openSet("mongodb://user:pwd@localhost:27020,localhost:27021,localhost:27012/mydb");

The database name and/or auth need only be included in one URI.
The options is a hash which is passed to the internal driver connection object.

Valid options

db      - passed to the connection db instance
server  - passed to the connection server instance(s)
replset - passed to the connection ReplSetServer instance
user    - username for authentication
pass    - password for authentication
auth    - options for authentication (see http://mongodb.github.com/node-mongodb-native/api-generated/db.html#authenticate)
mongos  - Boolean - if true, enables High Availability support for mongos

Options passed take precedence over options included in connection strings.

Notes:

If connecting to multiple mongos servers, set the mongos option to true.

conn.open('mongodb://mongosA:27501,mongosB:27501', { mongos: true }, cb);

Mongoose forces the db option forceServerObjectId false and cannot be overridden.
Mongoose defaults the server auto_reconnect options to true which can be overridden.
See the node-mongodb-native driver instance for options that it understands.

Options passed take precedence over options included in connection strings.

Not typically needed by applications. Just talk to your collection through your 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 a new connection object, with the new db.

Example

// Map documents returned by `data` events
Thing.
  find({ name: /^hello/ }).
  cursor().
  map(function (doc) {
   doc.foo = "bar";
   return doc;
  })
  on('data', function(doc) { console.log(doc.foo); });

// Or map documents returned by `.next()`
var cursor = Thing.find({ name: /^hello/ }).
  cursor().
  map(function (doc) {
    doc.foo = "bar";
    return doc;
  });
cursor.next(function(error, doc) {
  console.log(doc.foo);
});

Unless you're an advanced user, do not instantiate this class directly.
Use Query#cursor() instead.

Example:

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

Example:

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

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

Example:

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

Example:

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

The callback is passed the pathname and schemaType as arguments on each iteration.

Example

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

Example

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

If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as methods.

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

// later
fizz.purr();
fizz.scratch();

Sets a path (if arity 2)
Gets a path (if arity 1)

Example

schema.path('name') // returns a SchemaType
schema.path('name', Number) // changes the schemaType of `name` to Number

Given a path, returns whether it is a real, virtual, nested, or ad-hoc/undefined path.

var schema = new Schema(..);
schema.post('save', function (doc) {
  console.log('this fired after a document was saved');
});

shema.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');
});

Example

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

Example:

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

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

Options:

• autoIndex: bool - defaults to null (which means use the connection's autoIndex option)
• bufferCommands: bool - defaults to true
• capped: bool - defaults to false
• collection: string - no default
• emitIndexErrors: bool - defaults to false.
• id: bool - defaults to true
• _id: bool - defaults to true
• minimize: bool - controls document#toObject behavior when called manually - defaults to true
• read: string
• safe: bool - defaults to true.
• shardKey: bool - defaults to null
• strict: bool - defaults to true
• toJSON - object - no default
• toObject - object - no default
• typeKey - string - defaults to 'type'
• useNestedStrict - boolean - defaults to false
• validateBeforeSave - bool - defaults to true
• versionKey: string - defaults to "__v"

Note:

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

Example

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

Example

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

If a hash of name/fn pairs is passed as the only argument, each name/fn pair will be added as statics.

Example:

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

Example

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

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.

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

Example:

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

// summary
doc.execPopulate().then(resolve, reject);

Example

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

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

Called internally after a document is returned from mongodb.

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

Example

doc.set('documents.0.title', 'changed');
doc.isDirectModified('documents.0.title') // true
doc.isDirectModified('documents') // 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

Example

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

Very helpful when using Mixed types.

Example:

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

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.

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.

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

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.

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)
• retainKeyOrder keep the order of object keys. If this is set to true, Object.keys(new Doc({ a: 1, b: 2}).toObject()) will always produce ['a', 'b'] (defaults to false)

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.

Example:

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

Example:

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

Valid options:

• same as in Model.update

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

Note:

This method is useful if you need synchronous validation.

Example:

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

NOTE:

Calling this mulitple times on an array before saving sends the same command as calling it once.
This update is implemented using the MongoDB $pop method which enforces this restriction.

doc.array = [1,2,3];

 var shifted = doc.array.$shift();
 console.log(shifted); // 1
 console.log(doc.array); // [2,3]

 // no affect
 shifted = doc.array.$shift();
 console.log(doc.array); // [2,3]

 doc.save(function (err) {
   if (err) return handleError(err);

   // we saved, now $shift works again
   shifted = doc.array.$shift();
   console.log(shifted ); // 2
   console.log(doc.array); // [3]
 })

Example

var id = new mongoose.Types.ObjectId;

Example

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

// or

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

NOTE:

Only use $where when you have a condition that cannot be met using other MongoDB operators like $lt.
Be sure to read about all of its caveats before using.

When called with one argument, the most recent path passed to where() is used.

Example

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

Example

query.batchSize(100)

Note

Cannot be used with distinct()

Example

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

Note

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

Deprecated. Use circle instead.

Deprecated. Use circle instead.

Example

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

Example

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

Example

query.comment('login query')

Note

Cannot be used with distinct()

Passing a callback executes the query.

Example:

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

Example

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

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

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

Valid options

• transform: optional function which accepts a mongoose document. The return value of the function will be emitted on data and returned by .next().

Example

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

Example

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

Passing a callback executes the query.

Example

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

Example

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

Example

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

// is the same as

User.where('age', 49);

Examples:

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

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

Example

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

When no callback is passed, the query is not executed. When the query is executed, the result will be an array of documents.

Example

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

Passing a callback executes the query. The result of the query is a single document.

• 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 Model.findById() instead.

Example

var query  = Kitten.where({ color: 'white' });
query.findOne(function (err, kitten) {
  if (err) return handleError(err);
  if (kitten) {
    // doc may be null if no document matched
  }
});

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

Available 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
• passRawResult: if true, passes the raw result from the MongoDB driver as the third callback parameter

Callback Signature

function(error, doc, result) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
  // result: [raw result from the MongoDB driver](http://mongodb.github.io/node-mongodb-native/2.0/api/Collection.html#findAndModify)
}

Examples

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

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.

Available 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()
• 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
• 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.
• passRawResult: if true, passes the raw result from the MongoDB driver as the third callback parameter
• 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.

Callback Signature

function(error, doc) {
  // error: any errors that occurred
  // doc: the document before updates are applied if `new: false`, or after updates if `new = true`
}

Examples

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

Example

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

NOTE:

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

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

Example:

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

Example:

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

When called with one argument, the most recent path passed to where() is used.

Example

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

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

When called with one argument, the most recent path passed to where() is used.

Example

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

Note

Cannot be used with distinct()

When called with one argument, the most recent path passed to where() is used.

Example

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

NOTE:

MUST be used after where().

NOTE:

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

Documents returned from queries with the lean option enabled are plain javascript objects, not MongooseDocuments. They have no save method, getters/setters or other Mongoose magic applied.

Example:

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

This is a great option in high-performance read-only scenarios, especially when combined with stream.

Example

query.limit(20)

Note

Cannot be used with distinct()

When called with one argument, the most recent path passed to where() is used.

When called with one argument, the most recent path passed to where() is used.

When called with one argument, the most recent path passed to where() is used.

Example

query.maxScan(100)

Note

Cannot be used with distinct()

When a Query is passed, conditions, field selection and options are merged.

When a Query is passed, conditions, field selection and options are merged.

New in 3.7.0

When called with one argument, the most recent path passed to where() is used.

These operators return documents sorted by distance.

Example

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

Example

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

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

Example

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

When called with one argument, the most recent path passed to where() is used.

Example

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

Example

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

Example

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

Example:

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

Paths are populated after the query executes and a response is received. A separate query is then executed for each path specified for population. After a response for each query has also been returned, the results are passed to the callback.

Preferences:

primary - (default) Read from primary only. Operations will produce an error if primary is unavailable. Cannot be combined with tags.
secondary            Read from secondary if available, otherwise error.
primaryPreferred     Read from primary if available, otherwise a secondary.
secondaryPreferred   Read from a secondary if available, otherwise read from the primary.
nearest              All operations read from among the nearest candidates, but unlike other modes, this option will include both the primary and all secondaries in the random selection.

Aliases

p   primary
pp  primaryPreferred
s   secondary
sp  secondaryPreferred
n   nearest

Example:

new Query().read('primary')
new Query().read('p')  // same as primary

new Query().read('primaryPreferred')
new Query().read('pp') // same as primaryPreferred

new Query().read('secondary')
new Query().read('s')  // same as secondary

new Query().read('secondaryPreferred')
new Query().read('sp') // same as secondaryPreferred

new Query().read('nearest')
new Query().read('n')  // same as nearest

// read from secondaries with matching tags
new Query().read('s', [{ dc:'sf', s: 1 },{ dc:'ma', s: 2 }])

Read more about how to use read preferrences here and here.

When called with one argument, the most recent path passed to where() is used.

Example

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

Note

The operation is only executed when a callback is passed. To force execution without a callback, you must first call remove() and then execute it by using the exec() method.

// not executed
var query = Model.find().remove({ name: 'Anne Murray' })

// executed
query.remove({ name: 'Anne Murray' }, callback)
query.remove({ name: 'Anne Murray' }).remove(callback)

// executed without a callback
query.exec()

// summary
query.remove(conds, fn); // executes
query.remove(conds)
query.remove(fn) // executes
query.remove()

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

When using string syntax, prefixing a path with - will flag that path as excluded. When a path does not have the - prefix, it is included. Lastly, if a path is prefixed with +, it forces inclusion of the path, which is useful for paths excluded at the schema level.

Example

// include a and b, exclude other fields
query.select('a b');

// exclude c and d, include other fields
query.select('-c -d');

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

// force inclusion of field excluded at schema level
query.select('+path')

NOTE:

Cannot be used with distinct().

v2 had slightly different syntax such as allowing arrays of field names. This support was removed in v3.

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

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

Options:

• tailable *
• sort *
• limit *
• skip *
• maxscan *
• batchSize *
• comment *
• snapshot *
• hint *
• readPreference **
• lean *
• safe

* denotes a query helper method is also available
** query helper method to set readPreference is read()

When called with one argument, the most recent path passed to where() is used.

Example

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

Example

query.skip(100).limit(20)

Note

Cannot be used with distinct()

Deprecated in MongoDB 2.2 in favor of read preferences.

Example:

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

Example

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

Example

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

Note

Cannot be used with distinct()

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.

Example

// sort by "field" ascending and "test" descending
query.sort({ field: 'asc', test: -1 });

// equivalent
query.sort('field -test');

Note

Cannot be used with distinct()

Example

// follows the nodejs 0.8 stream api
Thing.find({ name: /^hello/ }).stream().pipe(res)

// manual streaming
var stream = Thing.find({ name: /^hello/ }).stream();

stream.on('data', function (doc) {
  // do something with the mongoose document
}).on('error', function (err) {
  // handle the error
}).on('close', function () {
  // the stream is closed
});

Valid options

• transform: optional function which accepts a mongoose document. The return value of the function will be emitted on data.

Example

// JSON.stringify all documents before emitting
var stream = Thing.find().stream({ transform: JSON.stringify });
stream.pipe(writeStream);

Example

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

Note

Cannot be used with distinct()

Example

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

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

// Adventure is now a subclass of mongoose.Query and works the same way but with the
// default query parameters and options set.
Adventure().exec(callback)

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

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

New in 3.7.3

All paths passed that are not $atomic operations will become $set ops.

Example

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

// becomes

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

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

Note

Passing an empty object {} as the doc will result in a no-op unless the overwrite option is passed. Without the overwrite option set, the update operation will be ignored and the callback executed without sending the command to MongoDB so as to prevent accidently overwritting documents in the collection.

Note

The operation is only executed when a callback is passed. To force execution without a callback, we must first call update() and then execute it by using the exec() method.

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

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

// keys that are not $atomic ops become $set.
// this executes the same command as the previous example.
q.update({ name: 'bob' }).exec();

// overwriting with empty docs
var q = Model.where({ _id: id }).setOptions({ overwrite: true })
q.update({ }, callback); // executes

// multi update with overwrite to empty doc
var q = Model.where({ _id: id });
q.setOptions({ multi: true, overwrite: true })
q.update({ });
q.update(callback); // executed

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

// more multi updates
Model.where()
     .setOptions({ multi: true })
     .update({ $set: { arr: [] }}, callback)

// single update by default
Model.where({ email: '[email protected]' })
     .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()

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

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

Example

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

// we can instead write:
User.where('age').gte(21).lte(65);

// passing query conditions is permitted
User.find().where({ name: 'vonderful' })

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

Example

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

MUST be used after where().

NOTE:

As of Mongoose 3.7, $geoWithin is always used for queries. To change this behavior, see Query.use$geoWithin.

NOTE:

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

Example:

var states = ['opening', 'open', 'closing', 'closed']
var s = new Schema({ state: { type: String, enum: states }})
var M = db.model('M', s)
var m = new M({ state: 'invalid' })
m.save(function (err) {
  console.error(String(err)) // ValidationError: `invalid` is not a valid enum value for path `state`.
  m.state = 'open'
  m.save(callback) // success
})

// or with custom error messages
var enum = {
  values: ['opening', 'open', 'closing', 'closed'],
  message: 'enum validator failed for path `{PATH}` with value `{VALUE}`'
}
var s = new Schema({ state: { type: String, enum: enum })
var M = db.model('M', s)
var m = new M({ state: 'invalid' })
m.save(function (err) {
  console.error(String(err)) // ValidationError: enum validator failed for path `state` with value `invalid`
  m.state = 'open'
  m.save(callback) // success
})

Example:

var s = new Schema({ email: { type: String, lowercase: true }})
var M = db.model('M', s);
var m = new M({ email: '[email protected]' });
console.log(m.email) // [email protected]

Any value that does not pass regExp.test(val) will fail validation.

Example:

var s = new Schema({ name: { type: String, match: /^a/ }})
var M = db.model('M', s)
var m = new M({ name: 'I am invalid' })
m.validate(function (err) {
  console.error(String(err)) // "ValidationError: Path `name` is invalid (I am invalid)."
  m.name = 'apples'
  m.validate(function (err) {
    assert.ok(err) // success
  })
})

// using a custom error message
var match = [ /\.html$/, "That file doesn't end in .html ({VALUE})" ];
var s = new Schema({ file: { type: String, match: match }})
var M = db.model('M', s);
var m = new M({ file: 'invalid' });
m.validate(function (err) {
  console.log(String(err)) // "ValidationError: That file doesn't end in .html (invalid)"
})

Empty strings, undefined, and null values always pass the match validator. If you require these values, enable the required validator also.

var s = new Schema({ name: { type: String, match: /^a/, required: true }})

Example:

var schema = new Schema({ postalCode: { type: String, maxlength: 9 })
var Address = db.model('Address', schema)
var address = new Address({ postalCode: '9512512345' })
address.save(function (err) {
  console.error(err) // validator error
  address.postalCode = '95125';
  address.save() // success
})

// custom error messages
// We can also use the special {MAXLENGTH} token which will be replaced with the maximum allowed length
var maxlength = [9, 'The value of path `{PATH}` (`{VALUE}`) exceeds the maximum allowed length ({MAXLENGTH}).'];
var schema = new Schema({ postalCode: { type: String, maxlength: maxlength })
var Address = mongoose.model('Address', schema);
var address = new Address({ postalCode: '9512512345' });
address.validate(function (err) {
  console.log(String(err)) // ValidationError: The value of path `postalCode` (`9512512345`) exceeds the maximum allowed length (9).
})

Example:

var schema = new Schema({ postalCode: { type: String, minlength: 5 })
var Address = db.model('Address', schema)
var address = new Address({ postalCode: '9512' })
address.save(function (err) {
  console.error(err) // validator error
  address.postalCode = '95125';
  address.save() // success
})

// custom error messages
// We can also use the special {MINLENGTH} token which will be replaced with the minimum allowed length
var minlength = [5, 'The value of path `{PATH}` (`{VALUE}`) is shorter than the minimum allowed length ({MINLENGTH}).'];
var schema = new Schema({ postalCode: { type: String, minlength: minlength })
var Address = mongoose.model('Address', schema);
var address = new Address({ postalCode: '9512' });
address.validate(function (err) {
  console.log(String(err)) // ValidationError: The value of path `postalCode` (`9512`) is shorter than the minimum length (5).
})

The string value will be trimmed when set.

Example:

var s = new Schema({ name: { type: String, trim: true }})
var M = db.model('M', s)
var string = ' some name '
console.log(string.length) // 11
var m = new M({ name: string })
console.log(m.name.length) // 9

Example:

var s = new Schema({ caps: { type: String, uppercase: true }})
var M = db.model('M', s);
var m = new M({ caps: 'an example' });
console.log(m.caps) // AN EXAMPLE

Example:

var s = new Schema({ n: { type: Number, max: 10 })
var M = db.model('M', s)
var m = new M({ n: 11 })
m.save(function (err) {
  console.error(err) // validator error
  m.n = 10;
  m.save() // success
})

// custom error messages
// We can also use the special {MAX} token which will be replaced with the invalid value
var max = [10, 'The value of path `{PATH}` ({VALUE}) exceeds the limit ({MAX}).'];
var schema = new Schema({ n: { type: Number, max: max })
var M = mongoose.model('Measurement', schema);
var s= new M({ n: 4 });
s.validate(function (err) {
  console.log(String(err)) // ValidationError: The value of path `n` (4) exceeds the limit (10).
})

Example:

var s = new Schema({ n: { type: Number, min: 10 })
var M = db.model('M', s)
var m = new M({ n: 9 })
m.save(function (err) {
  console.error(err) // validator error
  m.n = 10;
  m.save() // success
})

// custom error messages
// We can also use the special {MIN} token which will be replaced with the invalid value
var min = [10, 'The value of path `{PATH}` ({VALUE}) is beneath the limit ({MIN}).'];
var schema = new Schema({ n: { type: Number, min: min })
var M = mongoose.model('Measurement', schema);
var s= new M({ n: 4 });
s.validate(function (err) {
  console.log(String(err)) // ValidationError: The value of path `n` (4) is beneath the limit (10).
})

This sets the expireAfterSeconds index option available in MongoDB >= 2.1.2.
This index type is only compatible with Date types.

Example:

// expire in 24 hours
new Schema({ createdAt: { type: Date, expires: 60*60*24 }});

expires utilizes the ms module from guille allowing us to use a friendlier syntax:

Example:

// expire in 24 hours
new Schema({ createdAt: { type: Date, expires: '24h' }});

// expire in 1.5 hours
new Schema({ createdAt: { type: Date, expires: '1.5h' }});

// expire in 7 days
var schema = new Schema({ createdAt: Date });
schema.path('createdAt').expires('7d');

Example:

var s = new Schema({ d: { type: Date, max: Date('2014-01-01') })
var M = db.model('M', s)
var m = new M({ d: Date('2014-12-08') })
m.save(function (err) {
  console.error(err) // validator error
  m.d = Date('2013-12-31');
  m.save() // success
})

// custom error messages
// We can also use the special {MAX} token which will be replaced with the invalid value
var max = [Date('2014-01-01'), 'The value of path `{PATH}` ({VALUE}) exceeds the limit ({MAX}).'];
var schema = new Schema({ d: { type: Date, max: max })
var M = mongoose.model('M', schema);
var s= new M({ d: Date('2014-12-08') });
s.validate(function (err) {
  console.log(String(err)) // ValidationError: The value of path `d` (2014-12-08) exceeds the limit (2014-01-01).
})

Example:

var s = new Schema({ d: { type: Date, min: Date('1970-01-01') })
var M = db.model('M', s)
var m = new M({ d: Date('1969-12-31') })
m.save(function (err) {
  console.error(err) // validator error
  m.d = Date('2014-12-08');
  m.save() // success
})

// custom error messages
// We can also use the special {MIN} token which will be replaced with the invalid value
var min = [Date('1970-01-01'), 'The value of path `{PATH}` ({VALUE}) is beneath the limit ({MIN}).'];
var schema = new Schema({ d: { type: Date, min: min })
var M = mongoose.model('M', schema);
var s= new M({ d: Date('1969-12-31') });
s.validate(function (err) {
  console.log(String(err)) // ValidationError: The value of path `d` (1969-12-31) is before the limit (1970-01-01).
})

Example:

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

Example:

new Aggregate();
new Aggregate({ $project: { a: 1, b: 1 } });
new Aggregate({ $project: { a: 1, b: 1 } }, { $skip: 5 });
new Aggregate([{ $project: { a: 1, b: 1 } }, { $skip: 5 }]);

Returned when calling Model.aggregate().

Example:

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).
• Requires MongoDB >= 2.1
• Mongoose does not cast pipeline stages. new Aggregate({ $match: { _id: '00000000000000000000000a' } }); will not work unless _id is a string in the database. Use new Aggregate({ $match: { _id: mongoose.Types.ObjectId('00000000000000000000000a') } }); instead.

Example:

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

Examples:

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

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

Example:

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

Example:

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

Example:

aggregate.exec(callback);

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

Example:

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

Example:

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

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

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

Examples:

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

Examples:

aggregate.limit(10);

Examples:

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

Examples:

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

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

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

Example:

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

Examples:

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

Examples:

aggregate.skip(10);

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

Example:

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

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

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 }

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

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

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 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:

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

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 by retreiving its 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 and is set as a value on an actual key.

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, [email protected] can be registered for 2 accounts via [email protected] and [email protected].

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: '[email protected]'})
console.log(user.email); // '[email protected]'

// or
var user = new User
user.email = '[email protected]'
console.log(user.email) // '[email protected]'

As you can see above, setters allow you to transform the data before it gets to the raw mongodb document and is set as a value on an actual key.

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