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, 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 model has it’s 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. We also declared the Story _creator property as a Number, the same type as the _id used in the personSchema. It is important to match the type of _id to the type of ref.

    Note: ObjectId, Number, String, and Buffer are valid for use as refs.

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

    1. var aaron = new Person({ _id: 0, name: 'Aaron', age: 100 });
    3. aaron.save(function (err) {
    4.   if (err) return handleError(err);
    6.   var story1 = new Story({
    7.     title: "Once upon a timex.",
    8.     _creator: aaron._id    // assign the _id from the person
    9.   });
    11.   story1.save(function (err) {
    12.     if (err) return handleError(err);
    13.     // thats it!
    14.   });
    15. })

    Population

    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 _creator using the query builder:

    1. Story
    2. .findOne({ title: 'Once upon a timex.' })
    3. .populate('_creator')
    4. .exec(function (err, story) {
    6.   // prints "The creator is Aaron"
    7. })

    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.

    Note: mongoose >= 3.6 exposes the original _ids used during population through the method.

    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: /timex/i })
    3. .populate('_creator', 'name') // only return the Persons name
    4. .exec(function (err, story) {
    5.   if (err) return handleError(err);
    7.   console.log('The creator is %s', story._creator.name);
    8.   // prints "The creator is Aaron"
    10.   console.log('The creators age is %s', story._creator.age);
    11.   // prints "The creators age is null'
    12. })

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

    In mongoose >= 3.6, we can pass a space delimited string of path names to populate. Before 3.6 you must execute the populate() method multiple times.

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

    Query conditions and other options

    What if we wanted to populate our fans array based on their age, select just their names, and return at most, any 5 of them?

    1. Story
    2. .find(...)
    3. .populate({
    4.   path: 'fans',
    5.   match: { age: { $gte: 21 }},
    6.   select: 'name -_id',
    7.   options: { limit: 5 }
    8. })
    9. .exec()

    Refs to children

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

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

    This allows us to perform a find and combo:

    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. .exec(function (err, stories) {
    3.   if (err) return handleError(err);
    4.   console.log('The stories are an array: ', stories);
    5. })

    Now that we have a story we realized that the _creator was incorrect. We can update refs the same as any other property through Mongoose’s internal casting:

    1. var guille = new Person({ name: 'Guillermo' });
    2. guille.save(function (err) {
    3.   if (err) return handleError(err);
    5.   story._creator = guille;
    6.   console.log(story._creator.name);
    7.   // prints "Guillermo" in mongoose >= 3.6
    8.   // see https://github.com/LearnBoost/mongoose/wiki/3.6-release-notes
    10.   story.save(function (err) {
    11.     if (err) return handleError(err);
    13.     Story
    14.     .findOne({ title: /timex/i })
    15.     .populate({ path: '_creator', select: 'name' })
    16.     .exec(function (err, story) {
    17.       if (err) return handleError(err);
    19.       console.log('The creator is %s', story._creator.name)
    20.       // prints "The creator is Guillermo"
    21.     })
    22.   })
    23. })

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

    Populating an existing document

    If we have an existing mongoose document and want to populate some of its paths, mongoose >= 3.6 supports the document#populate() method.

    Populating multiple existing documents

    If we have one or many mongoose documents or even plain objects (like mapReduce output), we may populate them using the method available in mongoose >= 3.6. This is what document#populate() and query#populate() use to populate documents.

    1. // this works in v3
    2. Story.findOne(..).populate('_creator', 'name age').exec(..);
    4. // this doesn't

    Next Up

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