Population is the process of automatically replacing the specified paths in the document with document(s) from other collection(s). We may populate a single document, multiple documents, a plain object, multiple plain objects, or all objects returned from a query. Let’s look at some examples.

    So far we’ve created two . Our Person model has its stories field set to an array of ObjectIds. The ref option is what tells Mongoose which model to use during population, in our case the Story model. All _ids we store here must be document _ids from the Story model.

    Note: ObjectId, Number, String, and Buffer are valid for use as refs. However, you should use ObjectId unless you are an advanced user and have a good reason for doing so.

    Saving refs to other documents works the same way you normally save properties, just assign the _id value:

    1. const author = new Person({
    2.   _id: new mongoose.Types.ObjectId(),
    3.   name: 'Ian Fleming',
    4.   age: 50
    5. });
    7. author.save(function (err) {
    8.   if (err) return handleError(err);
    10.   const story1 = new Story({
    11.     title: 'Casino Royale',
    12.     author: author._id    // assign the _id from the person
    13.   });
    15.   story1.save(function (err) {
    16.     if (err) return handleError(err);
    17.     // that's it!
    18.   });
    19. });

    So far we haven’t done anything much different. We’ve merely created a Person and a Story. Now let’s take a look at populating our story’s author using the query builder:

    1. Story.
    2.   findOne({ title: 'Casino Royale' }).
    3.   populate('author').
    4.   exec(function (err, story) {
    5.     if (err) return handleError(err);
    6.     console.log('The author is %s', story.author.name);
    7.     // prints "The author is Ian Fleming"
    8.   });

    Populated paths are no longer set to their original _id , their value is replaced with the mongoose document returned from the database by performing a separate query before returning the results.

    Arrays of refs work the same way. Just call the populate method on the query and an array of documents will be returned in place of the original _ids.

    Setting Populated Fields

    You can manually populate a property by setting it to a document. The document must be an instance of the model your ref property refers to.

    1. Story.findOne({ title: 'Casino Royale' }, function(error, story) {
    2.   if (error) {
    3.     return handleError(error);
    4.   }
    5.   story.author = author;
    6.   console.log(story.author.name); // prints "Ian Fleming"
    7. });

    Checking Whether a Field is Populated

    You can call the populated() function to check whether a field is populated. If populated() returns a , you can assume the field is populated.

    1. story.populated('author'); // truthy
    3. story.depopulate('author'); // Make `author` not populated anymore
    4. story.populated('author'); // undefined

    A common reason for checking whether a path is populated is getting the author id. However, for your convenience, Mongoose adds a _id getter to ObjectId instances so you can use story.author._id regardless of whether author is populated.

    1. story.populated('author'); // truthy
    2. story.author._id; // ObjectId
    4. story.depopulate('author'); // Make `author` not populated anymore
    5. story.populated('author'); // undefined
    7. story.author instanceof ObjectId; // true
    8. story.author._id; // ObjectId, because Mongoose adds a special getter

    What If There’s No Foreign Document?

    Mongoose populate doesn’t behave like conventional . When there’s no document, story.author will be null. This is analogous to a left join in SQL.

    1. await Person.deleteMany({ name: 'Ian Fleming' });
    3. const story = await Story.findOne({ title: 'Casino Royale' }).populate('author');
    4. story.author; // `null`

    If you have an array of authors in your storySchema, populate() will give you an empty array instead.

    1. const storySchema = Schema({
    2.   authors: [{ type: Schema.Types.ObjectId, ref: 'Person' }],
    3.   title: String
    4. });
    6. // Later
    8. const story = await Story.findOne({ title: 'Casino Royale' }).populate('authors');
    9. story.authors; // `[]`

    Field Selection

    What if we only want a few specific fields returned for the populated documents? This can be accomplished by passing the usual as the second argument to the populate method:

    1. Story.
    2.   findOne({ title: /casino royale/i }).
    3.   populate('author', 'name'). // only return the Persons name
    4.   exec(function (err, story) {
    5.     if (err) return handleError(err);
    7.     console.log('The author is %s', story.author.name);
    8.     // prints "The author is Ian Fleming"
    10.     console.log('The authors age is %s', story.author.age);
    11.     // prints "The authors age is null"
    12.   });

    What if we wanted to populate multiple paths at the same time?

    1. Story.
    2.   find(...).
    3.   populate('fans').
    4.   populate('author').
    5.   exec();

    If you call populate() multiple times with the same path, only the last one will take effect.

    1. // The 2nd `populate()` call below overwrites the first because they
    2. // both populate 'fans'.
    3. Story.
    4.   find().
    5.   populate({ path: 'fans', select: 'name' }).
    6.   populate({ path: 'fans', select: 'email' });
    7. // The above is equivalent to:
    8. Story.find().populate({ path: 'fans', select: 'email' });

    What if we wanted to populate our fans array based on their age and select just their names?

    1. Story.
    2.   find().
    3.   populate({
    4.     path: 'fans',
    5.     match: { age: { $gte: 21 } },
    6.     // Explicitly exclude `_id`, see http://bit.ly/2aEfTdB
    7.     select: 'name -_id'
    8.   }).
    9.   exec();

    The match option doesn’t filter out Story documents. If there are no documents that satisfy match, you’ll get a Story document with an empty fans array.

    1. const story = await Story.
    2.   findOne({ title: 'Casino Royale' }).
    3.   populate({ path: 'author', name: { $ne: 'Ian Fleming' } }).
    4.   exec();

    In general, there is no way to make populate() filter stories based on properties of the story’s author. For example, the below query won’t return any results, even though author is populated.

    1. const story = await Story.
    2.   findOne({ 'author.name': 'Ian Fleming' }).
    3.   populate('author').
    4.   exec();
    5. story; // null

    If you want to filter stories by their author’s name, you should use denormalization.

    limit vs. perDocumentLimit

    Populate does support a limit option, however, it currently does not limit on a per-document basis for backwards compatibility. For example, suppose you have 2 stories:

    If you were to populate() using the limit option, you would find that the 2nd story has 0 fans:

    1. const stories = Story.find().populate({
    2.   path: 'fans',
    3.   options: { limit: 2 }
    4. });
    6. stories[0].name; // 'Casino Royale'
    7. stories[0].fans.length; // 2
    9. // 2nd story has 0 fans!
    11. stories[1].fans.length; // 0

    That’s because, in order to avoid executing a separate query for each document, Mongoose instead queries for fans using numDocuments * limit as the limit. If you need the correct limit, you should use the perDocumentLimit option (new in Mongoose 5.9.0). Just keep in mind that populate() will execute a separate query for each story, which may cause populate() to be slower.

    1. const stories = await Story.find().populate({
    2.   path: 'fans',
    3.   // Special option that tells Mongoose to execute a separate query
    4.   // for each `story` to make sure we get 2 fans for each story.
    5.   perDocumentLimit: 2
    6. });
    8. stories[0].name; // 'Casino Royale'
    9. stories[0].fans.length; // 2
    11. stories[1].name; // 'Live and Let Die'
    12. stories[1].fans.length; // 2

    Refs to children

    We may find however, if we use the author object, we are unable to get a list of the stories. This is because no story objects were ever ‘pushed’ onto author.stories.

    There are two perspectives here. First, you may want the author know which stories are theirs. Usually, your schema should resolve one-to-many relationships by having a parent pointer in the ‘many’ side. But, if you have a good reason to want an array of child pointers, you can push() documents onto the array as shown below.

    1. author.stories.push(story1);
    2. author.save(callback);

    This allows us to perform a find and populate combo:

    1. Person.
    2.   findOne({ name: 'Ian Fleming' }).
    3.   populate('stories'). // only works if we pushed refs to children
    4.   exec(function (err, person) {
    5.     if (err) return handleError(err);
    6.     console.log(person);
    7.   });

    It is debatable that we really want two sets of pointers as they may get out of sync. Instead we could skip populating and directly find() the stories we are interested in.

    1. Story.
    2.   find({ author: author._id }).
    3.   exec(function (err, stories) {
    4.     if (err) return handleError(err);
    5.     console.log('The stories are an array: ', stories);
    6.   });

    The documents returned from become fully functional, removeable, saveable documents unless the lean option is specified. Do not confuse them with . Take caution when calling its remove method because you’ll be removing it from the database, not just the array.

    If you have an existing mongoose document and want to populate some of its paths, you can use the Document#populate() method. Just make sure you call to execute the populate().

    1. const person = await Person.findOne({ name: 'Ian Fleming' });
    3. person.populated('stories'); // null
    5. // Call the `populate()` method on a document to populate a path.
    6. // Need to call `execPopulate()` to actually execute the `populate()`.
    7. await person.populate('stories').execPopulate();
    9. person.populated('stories'); // Array of ObjectIds
    10. person.stories[0].name; // 'Casino Royale'

    The Document#populate() method supports chaining, so you can chain multiple populate() calls together.

    1. await person.populate('stories').populate('fans').execPopulate();
    2. person.populated('fans'); // Array of ObjectIds

    If we have one or many mongoose documents or even plain objects (like mapReduce output), we may populate them using the method. This is what Document#populate() and Query#populate() use to populate documents.

    Say you have a user schema which keeps track of the user’s friends.

    1. const userSchema = new Schema({
    2.   name: String,
    3.   friends: [{ type: ObjectId, ref: 'User' }]
    4. });

    Populate lets you get a list of a user’s friends, but what if you also wanted a user’s friends of friends? Specify the populate option to tell mongoose to populate the friends array of all the user’s friends:

    1. User.
    2.   findOne({ name: 'Val' }).
    3.   populate({
    4.     path: 'friends',
    5.     // Get friends of friends - populate the 'friends' array for every friend
    6.     populate: { path: 'friends' }
    7.   });

    Let’s say you have a schema representing events, and a schema representing conversations. Each event has a corresponding conversation thread.

    1. const db1 = mongoose.createConnection('mongodb://localhost:27000/db1');
    2. const db2 = mongoose.createConnection('mongodb://localhost:27001/db2');
    4. const conversationSchema = new Schema({ numMessages: Number });
    5. const Conversation = db2.model('Conversation', conversationSchema);
    7. const eventSchema = new Schema({
    8.   name: String,
    9.   conversation: {
    10.     type: ObjectId,
    11.     ref: Conversation // `ref` is a **Model class**, not a string
    12.   }
    13. });
    14. const Event = db1.model('Event', eventSchema);

    In the above example, events and conversations are stored in separate MongoDB databases. String ref will not work in this situation, because Mongoose assumes a string ref refers to a model name on the same connection. In the above example, the conversation model is registered on db2, not db1.

    1. // Works
    2. const events = await Event.
    3.   find().
    4.   populate('conversation');

    If you don’t have access to the model instance when defining your eventSchema, you can also pass the model instance as an option to populate().

    1. const events = await Event.
    2.   find().
    3.   // The `model` option specifies the model to use for populating.
    4.   populate({ path: 'conversation', model: Conversation });

    Dynamic References via `refPath`

    Mongoose can also populate from multiple collections based on the value of a property in the document. Let’s say you’re building a schema for storing comments. A user may comment on either a blog post or a product.

    1. const commentSchema = new Schema({
    2.   body: { type: String, required: true },
    3.   on: {
    4.     type: Schema.Types.ObjectId,
    5.     required: true,
    6.     // Instead of a hardcoded model name in `ref`, `refPath` means Mongoose
    7.     // will look at the `onModel` property to find the right model.
    8.     refPath: 'onModel'
    9.   },
    10.   onModel: {
    11.     type: String,
    12.     required: true,
    13.     enum: ['BlogPost', 'Product']
    14.   }
    15. });
    17. const Product = mongoose.model('Product', new Schema({ name: String }));
    18. const BlogPost = mongoose.model('BlogPost', new Schema({ title: String }));
    19. const Comment = mongoose.model('Comment', commentSchema);

    The refPath option is a more sophisticated alternative to ref. If ref is just a string, Mongoose will always query the same model to find the populated subdocs. With refPath, you can configure what model Mongoose uses for each document.

    An alternative approach is to define separate blogPost and product properties on commentSchema, and then populate() on both properties.

    1. const commentSchema = new Schema({
    2.   body: { type: String, required: true },
    3.   product: {
    4.     type: Schema.Types.ObjectId,
    5.     required: true,
    6.     ref: 'Product'
    7.   },
    8.   blogPost: {
    9.     type: Schema.Types.ObjectId,
    10.     required: true,
    11.     ref: 'BlogPost'
    12.   }
    13. });
    15. // ...
    17. // The below `populate()` is equivalent to the `refPath` approach, you
    18. // just need to make sure you `populate()` both `product` and `blogPost`.
    19. const comments = await Comment.find().
    20.   populate('product').
    21.   populate('blogPost').
    22.   sort({ body: 1 });
    23. comments[0].product.name; // "The Count of Monte Cristo"
    24. comments[1].blogPost.title; // "Top 10 French Novels"

    Defining separate blogPost and product properties works for this simple example. But, if you decide to allow users to also comment on articles or other comments, you’ll need to add more properties to your schema. You’ll also need an extra populate() call for every property, unless you use . Using refPath means you only need 2 schema paths and one populate() call regardless of how many models your commentSchema can point to.

    So far you’ve only populated based on the _id field. However, that’s sometimes not the right choice. In particular, arrays that grow without bound are a MongoDB anti-pattern. Using mongoose virtuals, you can define more sophisticated relationships between documents.

    1. const PersonSchema = new Schema({
    3.   band: String
    4. });
    5. const BandSchema = new Schema({
    6.   name: String
    7. });
    8. BandSchema.virtual('members', {
    9.   ref: 'Person', // The model to use
    10.   localField: 'name', // Find people where `localField`
    11.   foreignField: 'band', // is equal to `foreignField`
    12.   // If `justOne` is true, 'members' will be a single doc as opposed to
    13.   // an array. `justOne` is false by default.
    14.   justOne: false,
    15.   options: { sort: { name: -1 }, limit: 5 } // Query options, see http://bit.ly/mongoose-query-options
    16. });
    18. const Person = mongoose.model('Person', PersonSchema);
    19. const Band = mongoose.model('Band', BandSchema);
    21. /**
    22.  * Suppose you have 2 bands: "Guns N' Roses" and "Motley Crue"
    23.  * And 4 people: "Axl Rose" and "Slash" with "Guns N' Roses", and
    24.  * "Vince Neil" and "Nikki Sixx" with "Motley Crue"
    25.  */
    26. Band.find({}).populate('members').exec(function(error, bands) {
    27.   /* `bands.members` is now an array of instances of `Person` */
    28. });

    You can also use to add an additional filter to the populate() query. This is useful if you need to split up populate() data:

    1. const PersonSchema = new Schema({
    2.   name: String,
    3.   band: String,
    4.   isActive: Boolean
    5. });
    7. const BandSchema = new Schema({
    8.   name: String
    9. });
    10. BandSchema.virtual('activeMembers', {
    11.   ref: 'Person',
    12.   localField: 'name',
    13.   foreignField: 'band',
    14.   justOne: false,
    15.   match: { isActive: true }
    16. });
    17. BandSchema.virtual('formerMembers', {
    18.   ref: 'Person',
    19.   localField: 'name',
    20.   foreignField: 'band',
    21.   justOne: false,
    22.   match: { isActive: false }
    23. });

    Keep in mind that virtuals are not included in toJSON() and toObject() output by default. If you want populate virtuals to show up when using functions that rely on JSON.stringify(), like Express’ res.json() function, set the virtuals: true option on your schema’s toJSON options.

    1. const BandSchema = new Schema({ name: String }, {
    2.   toJSON: { virtuals: true }, // So `res.json()` and other `JSON.stringify()` functions include virtuals
    3.   toObject: { virtuals: true } // So `toObject()` output includes virtuals
    4. });

    If you’re using populate projections, make sure foreignField is included in the projection.

    1. Band.
    2.   find({}).
    3.   populate({ path: 'members', select: 'name' }).
    4.   exec(function(error, bands) {
    5.     // Won't work, foreign field `band` is not selected in the projection
    6.   });
    8. Band.
    9.   find({}).
    10.   populate({ path: 'members', select: 'name band' }).
    11.   exec(function(error, bands) {
    12.     // Works, foreign field `band` is selected
    13.   });

    Populate Virtuals: The Count Option

    Populate virtuals also support counting the number of documents with matching foreignField as opposed to the documents themselves. Set the count option on your virtual:

    1. const PersonSchema = new Schema({
    2.   name: String,
    3.   band: String
    4. });
    6. const BandSchema = new Schema({
    7.   name: String
    8. });
    9. BandSchema.virtual('numMembers', {
    10.   ref: 'Person', // The model to use
    11.   localField: 'name', // Find people where `localField`
    12.   foreignField: 'band', // is equal to `foreignField`
    13.   count: true // And only get the number of docs
    14. });
    16. // Later
    17. const doc = await Band.findOne({ name: 'Motley Crue' }).
    18.   populate('numMembers');
    19. doc.numMembers; // 2

    Populating Maps

    are a type that represents an object with arbitrary string keys. For example, in the below schema, members is a map from strings to ObjectIds.

    1. const BandSchema = new Schema({
    2.   name: String,
    3.   members: {
    4.     type: Map,
    5.     of: {
    6.       type: 'ObjectId',
    7.       ref: 'Person'
    8.     }
    9.   }
    10. });
    11. const Band = mongoose.model('Band', bandSchema);

    This map has a ref, which means you can use populate() to populate all the ObjectIds in the map. Suppose you have the below band document:

    1. const person1 = new Person({ name: 'Vince Neil' });
    2. const person2 = new Person({ name: 'Mick Mars' });
    4. const band = new Band({
    5.   name: 'Motley Crue',
    6.   members: {
    7.     'singer': person1._id,
    8.     'guitarist': person2._id
    9.   }
    10. });

    You can populate() every element in the map by populating the special path members.$*. $* is a special syntax that tells Mongoose to look at every key in the map.

    1. const band = await Band.findOne({ name: 'Motley Crue' }).populate('members.$*');
    3. band.members.get('singer'); // { _id: ..., name: 'Vince Neil' }

    You can also populate paths in maps of subdocuments using $*. For example, suppose you have the below librarySchema:

    1. const librarySchema = new Schema({
    2.   name: String,
    3.   books: {
    4.     type: Map,
    5.     of: new Schema({
    6.       title: String,
    7.       author: {
    8.         type: 'ObjectId',
    9.         ref: 'Person'
    10.       }
    11.     })
    12.   }
    13. });
    14. const Library = mongoose.model('Library, librarySchema');

    You can populate() every book’s author by populating books.$*.author:

    1. const libraries = await Library.find().populate('books.$*.author');

    You can populate in either pre or post hooks. If you want to always populate a certain field, check out the .

    1. // Always attach `populate()` to `find()` calls
    2. MySchema.pre('find', function() {
    3.   this.populate('user');
    4. });
    1. // Always `populate()` after `find()` calls. Useful if you want to selectively populate
    2. // based on the docs found.
    3. MySchema.post('find', async function(docs) {
    4.   for (let doc of docs) {
    5.     if (doc.isPublic) {
    6.       await doc.populate('user').execPopulate();
    7.     }
    8.   }
    9. });

    Next Up

    Now that we’ve covered , let’s take a look at .