MongoDB Aggregation Framework: Mastering $lookup

What is $lookup?

$lookup is an aggregation pipeline stage that performs a left outer join to another collection in the same database.

It matches documents from the local collection with documents from the foreign collection based on specified fields.

• Combines documents from two collections.
• Returns all documents from the local collection.
• Adds matching documents from the foreign collection as an array.

Basic Syntax of $lookup

The basic syntax requires specifying the foreign collection, local and foreign fields to match, and the name of the new array field to add.

Here is the general structure:

• {
• $lookup: {
• from: '<foreign_collection>',
• localField: '<local_field>',
• foreignField: '<foreign_field>',
• as: '<output_array_field>'
• }
• }

Example: Joining Orders with Customers

Suppose you have two collections: 'orders' and 'customers'. Each order document has a 'customerId' field referencing a customer.

Using $lookup, you can join orders with their corresponding customer details.

Advanced $lookup Features

MongoDB 3.6+ supports more advanced $lookup features like pipeline-based joins and let variables for complex matching.

These features allow filtering and transforming joined documents within the $lookup stage.

• Using 'pipeline' instead of localField/foreignField for flexible matching.
• Defining variables with 'let' to pass values to the pipeline.
• Performing multiple stages inside the $lookup pipeline.

Performance Considerations

While $lookup is powerful, improper use can lead to performance issues.

Indexing the fields used for joining is critical for efficient queries.

• Create indexes on foreignField in the joined collection.
• Avoid joining very large collections without filters.
• Use pipeline $lookup for more selective joins.