Node.js – MongoDB Join – Use $lookup to Join Collections with Node.js

Introduction – How MongoDB Joins Work in Node.js?

MongoDB is a NoSQL database, which traditionally doesn’t support joins like SQL. However, with the $lookup aggregation stage, MongoDB enables joining multiple collections based on related fields. This is incredibly powerful when using Node.js to combine user data, order details, categories, and more.

In this guide, you’ll learn:

• How to perform joins in MongoDB using $lookup
• Join two collections with a common key
• Use as, localField, and foreignField
• Filter joined data in aggregation pipelines

Setup – Sample Collections

users Collection

[
  { "_id": 1, "name": "Alice", "country_id": "IN" },
  { "_id": 2, "name": "Bob", "country_id": "US" }
]

countries Collection

[
  { "_id": "IN", "country": "India" },
  { "_id": "US", "country": "United States" }
]

Perform Join with $lookup

const getDB = require('./db');

async function joinUsersWithCountry() {
  const db = await getDB();
  const result = await db.collection('users').aggregate([
    {
      $lookup: {
        from: 'countries',         // Collection to join
        localField: 'country_id',  // Field in users
        foreignField: '_id',       // Field in countries
        as: 'countryInfo'          // Output array field
      }
    }
  ]).toArray();

  console.log(' Joined Data:', result);
}

joinUsersWithCountry();

Output:

[
  {
    "_id": 1,
    "name": "Alice",
    "country_id": "IN",
    "countryInfo": [{ "_id": "IN", "country": "India" }]
  }
]

Flatten Joined Results Using $unwind

{
  $unwind: "$countryInfo"
}

Converts the countryInfo array into a single object for easier access.

Example with Filters After Join

const result = await db.collection('users').aggregate([
  {
    $lookup: {
      from: 'countries',
      localField: 'country_id',
      foreignField: '_id',
      as: 'countryInfo'
    }
  },
  { $unwind: "$countryInfo" },
  { $match: { "countryInfo.country": "India" } }
]).toArray();

Only returns users whose country is India.

Best Practices for MongoDB Joins with $lookup

Summary – Recap & Next Steps

Using MongoDB’s $lookup in Node.js lets you join data across collections efficiently. This is vital for apps that model related data like orders, users, products, categories, and more.

Key Takeaways:

• Use $lookup in an aggregation pipeline to perform joins
• localField and foreignField define the match condition
• Use $unwind to flatten array results
• Combine with $match to filter joined data

Real-world relevance:
Used in e-commerce apps, CMS systems, reporting dashboards, and RESTful APIs with related datasets.

FAQs – MongoDB Join with Node.js Using $lookup

Can I join more than two collections?
Yes. You can chain multiple $lookup stages in the aggregation pipeline.

Is $lookup slow for large datasets?
It can be. Use indexes on the foreignField and limit result size for performance.

How do I handle empty countryInfo arrays?
Use $unwind with preserveNullAndEmptyArrays: true:

{ $unwind: { path: "$countryInfo", preserveNullAndEmptyArrays: true } }

Can I join on nested fields?
Yes. Use dot notation like localField: 'profile.country_id'.

Does $lookup work on sharded clusters?
Yes, but there are restrictions—check MongoDB version and sharding rules.