The $lookup stage in MongoDB’s aggregation framework allows you to perform a left outer join to a collection in the same database. This stage is useful for combining documents from two collections based on a specified condition. The $lookup stage adds a new array field to each input document, containing the matching documents from the “joined” collection.

Basic Syntax

The basic syntax for the $lookup stage is as follows:

{
  $lookup: {
    from: "<joined_collection>",
    localField: "<field_from_input_documents>",
    foreignField: "<field_from_joined_documents>",
    as: "<output_array_field>"
  }
}

• from: The collection to join.
• localField: The field from the input documents.
• foreignField: The field from the documents in the from collection.
• as: The name of the new array field to add to the input documents.

Example Usage

Exaample 1

Here’s a simple example of using the $lookup stage in MongoDB’s aggregation framework:

Let’s say we have two collections: orders and customers. We want to join the customers collection with the orders collection based on the customer_id field.

Here is how you can use the $lookup stage to achieve this:

db.orders.aggregate([
  {
    $lookup: {
      from: "customers",
      localField: "customer_id",
      foreignField: "customer_id",
      as: "customer_info"
    }
  }
])

In this example:

• from: The collection to join, which is customers.
• localField: The field from the orders collection, which is customer_id.
• foreignField: The field from the customers collection, which is customer_id.
• as: The name of the new array field to add to the orders documents, which is customer_info.

This will add a new field customer_info to each document in the orders collection, containing the matching documents from the customers collection.

Example 2

Let’s consider an example where we have two collections: customers and accounts. We want to join the accounts collection with the customers collection based on the account_id field.

Here is how you can use the $lookup stage to achieve this:

db.customers.aggregate([
  {
    $lookup: {
      from: "accounts",
      localField: "accounts",
      foreignField: "account_id",
      as: "purchases",
      pipeline: [
        {
          $search: {
            index: "lookup-with-search-tutorial",
            compound: {
              must: [
                {
                  queryString: {
                    defaultPath: "products",
                    query: "products: (CurrencyService AND InvestmentStock)"
                  }
                }
              ],
              should: [
                {
                  range: {
                    path: "limit",
                    gte: 5000,
                    lte: 10000
                  }
                }
              ]
            }
          }
        },
        {
          $project: {
            _id: 0
          }
        }
      ]
    }
  },
  {
    $limit: 5
  },
  {
    $project: {
      _id: 0,
      address: 0,
      birthdate: 0,
      username: 0,
      tier_and_details: 0
    }
  }
])

In this example:

• We join the accounts collection with the customers collection.
• The localField is accounts from the customers collection.
• The foreignField is account_id from the accounts collection.
• The results are stored in the purchases array field.
• We use the $search stage within the $lookup pipeline to filter the results based on specific criteria.
• We project the results to exclude the _id field and limit the output to 5 documents.

Compatibility

The $lookup stage is compatible with the following MongoDB environments:

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud.
• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB.
• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB.

Starting in MongoDB 5.1, you can use $lookup with sharded collections.

Conclusion

The $lookup stage is a powerful tool in MongoDB’s aggregation framework that allows you to combine documents from different collections based on specified conditions. By using the $lookup stage, you can enrich your documents with related data from other collections, making your queries more powerful and flexible.

I hope this article helps you understand how to use the $lookup stage in MongoDB’s aggregation framework!