Model.populate()

Parameters

• docs «Document|Array» Either a single document or array of documents to populate.

• options «Object|String» Either the paths to populate or an object specifying all parameters

• [options.path=null] «string» The path to populate.

• [options.retainNullValues=false] «boolean» By default, Mongoose removes null and undefined values from populated arrays. Use this option to make populate() retain null and undefined array entries.

• [options.getters=false] «boolean» If true, Mongoose will call any getters defined on the localField. By default, Mongoose gets the raw value of localField. For example, you would need to set this option to true if you wanted to add a lowercase getter to your localField.

• [options.clone=false] «boolean» When you do BlogPost.find().populate('author'), blog posts with the same author will share 1 copy of an author doc. Enable this option to make Mongoose clone populated docs before assigning them.

• [options.match=null] «Object|Function» Add an additional filter to the populate query. Can be a filter object containing MongoDB query syntax, or a function that returns a filter object.

• [options.skipInvalidIds=false] «Boolean» By default, Mongoose throws a cast error if localField and foreignField schemas don’t line up. If you enable this option, Mongoose will instead filter out any localField properties that cannot be casted to foreignField‘s schema type.

• [options.perDocumentLimit=null] «Number» For legacy reasons, limit with populate() may give incorrect results because it only executes a single query for every document being populated. If you set perDocumentLimit, Mongoose will ensure correct limit per document by executing a separate query for each document to populate(). For example, .find().populate({ path: 'test', perDocumentLimit: 2 }) will execute 2 additional queries if .find() returns 2 documents.

• [options.options=null] «Object» Additional options like limit and lean.

• [callback(err,doc)] «Function» Optional callback, executed upon completion. Receives err and the doc(s).

Returns:

• «Promise»

Populates document references.

Available top-level 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
• justOne: optional boolean, if true Mongoose will always set path to an array. Inferred from schema by default.

Examples:

// populates a single object
User.findById(id, function (err, user) {
  const 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) {
  const opts = [{ path: 'company', match: { x: 1 }, select: 'name' }];
  const 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' }
// });
const 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
const 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