$lookup with pipeline (advanced join) in MongoDB - Step-by-Step Execution

Concept Flow - $lookup with pipeline (advanced join)

Start with main collection

↓

$lookup stage with pipeline

↓

For each main doc, run pipeline on joined collection

↓

Match, filter, or transform joined docs

↓

Add joined docs as array field

↓

Output enriched documents

The $lookup with pipeline runs a custom query on the joined collection for each document in the main collection, then adds the results as a new array field.

Execution Sample

MongoDB

db.orders.aggregate([
  {
    $lookup: {
      from: "products",
      let: { order_item: "$item" },
      pipeline: [
        { $match: { $expr: { $eq: ["$name", "$$order_item"] } } },
        { $project: { name: 1, price: 1 } }
      ],
      as: "productDetails"
    }
  }
])

This query joins 'orders' with 'products' by matching 'item' in orders to 'name' in products, returning product details for each order.

Execution Table

Step	Main Doc _id	let Variables	Pipeline Match Condition	Matched Docs	Output Field 'productDetails'
1	order1	{ order_item: 'Pen' }	Match products where name == 'Pen'	[{_id: 'p1', name: 'Pen', price: 1.5}]	[{name: 'Pen', price: 1.5}]
2	order2	{ order_item: 'Notebook' }	Match products where name == 'Notebook'	[{_id: 'p2', name: 'Notebook', price: 3.0}]	[{name: 'Notebook', price: 3.0}]
3	order3	{ order_item: 'Pencil' }	Match products where name == 'Pencil'	[]	[]
4	END	-	-	-	Aggregation complete, all orders enriched

💡 All documents processed; pipeline matched products or returned empty arrays when no match.

Variable Tracker

Variable	Start	After 1	After 2	After 3	Final
order_item	undefined	'Pen'	'Notebook'	'Pencil'	N/A
Matched Docs	undefined	[{_id: 'p1', name: 'Pen', price: 1.5}]	[{_id: 'p2', name: 'Notebook', price: 3.0}]	[]	N/A
productDetails	undefined	[{name:'Pen',price:1.5}]	[{name:'Notebook',price:3.0}]	[]	N/A

Key Moments - 2 Insights

Why does the 'productDetails' field sometimes contain an empty array?

Because the pipeline match condition found no products matching the order's item (see execution_table row 3), so no documents were joined.

How does the 'let' variable 'order_item' get used inside the pipeline?

It is referenced inside the $match stage with $expr and $$ to compare product names to the current order's item (see execution_table rows 1-3).

Visual Quiz - 3 Questions

Look at the execution_table at Step 2. What is the value of 'productDetails' for order2?

A []

B [{name: 'Pen', price: 1.5}]

C [{name: 'Notebook', price: 3.0}]

D [{name: 'Pencil', price: 0.5}]

💡 Hint

Check the 'Output Field productDetails' column at Step 2 in execution_table.

At which step does the pipeline find no matching products?

A Step 1

B Step 3

C Step 2

D Step 4

💡 Hint

Look at the 'Matched Docs' column for empty arrays in execution_table.

If the 'let' variable was not used, how would the pipeline change?

A The pipeline could not dynamically match each order's item to products.

B The pipeline would match all products regardless of order item.

C The pipeline would fail with a syntax error.

D The pipeline would return only the first product.

💡 Hint

Refer to how 'order_item' is used in the $match with $expr in execution_table.

Concept Snapshot

$lookup with pipeline syntax:
{
  $lookup: {
    from: <collection>,
    let: { <vars> },
    pipeline: [ <stages using $$vars> ],
    as: <output array field>
  }
}

Behavior: For each main doc, runs pipeline on 'from' collection using 'let' vars.
Output: Adds matched docs as array field.
Key: Use $expr and $$var to reference 'let' vars inside pipeline.

Full Transcript

The $lookup with pipeline lets you join documents from another collection using a custom query pipeline for each document in the main collection. First, you define variables from the main document using 'let'. Then, inside the pipeline, you use $expr and $$ to compare fields dynamically. For example, matching product names to order items. The matched documents are added as an array field to each main document. If no matches are found, the array is empty. This allows advanced joins with filtering and transformations on the joined collection.

Practice

1. What is the main purpose of using $lookup with a pipeline in MongoDB?

easy

A. To create indexes on joined collections automatically

B. To update documents in the joined collection

C. To perform advanced joins with filtering and transformations on the joined data

D. To delete documents from multiple collections at once

Solution

1. Step 1: Understand $lookup basic function

   $lookup is used to join documents from another collection into the current one.

2. Step 2: Role of pipeline in $lookup

   Using a pipeline allows filtering and transforming the joined documents before adding them.

3. Final Answer:

   To perform advanced joins with filtering and transformations on the joined data -> Option C

4. Quick Check:

   $lookup with pipeline = advanced join [OK]

Hint: Remember: pipeline lets you filter joined data inside $lookup [OK]

Common Mistakes:

• Thinking $lookup with pipeline updates or deletes data
• Confusing $lookup with index creation
• Assuming $lookup merges collections permanently

2. Which of the following is the correct syntax to define variables for use inside the pipeline of a $lookup stage?

easy

A. "params: { var1: \"$field1\", var2: \"$field2\" }"

B. "vars: { var1: \"$field1\", var2: \"$field2\" }"

C. "variables: [ var1: \"$field1\", var2: \"$field2\" ]"

D. "let: { var1: \"$field1\", var2: \"$field2\" }"

Solution

1. Step 1: Recall $lookup variable syntax

   Variables for the pipeline are defined using the let keyword as an object.

2. Step 2: Match correct keyword and structure

   Only let with an object of key-value pairs is valid syntax.

3. Final Answer:

   "let: { var1: \"$field1\", var2: \"$field2\" }" -> Option D

4. Quick Check:

   Variables in $lookup pipeline = let [OK]

Hint: Use 'let' keyword with object to define variables in $lookup [OK]

Common Mistakes:

• Using 'vars' or 'variables' instead of 'let'
• Using array syntax instead of object for variables
• Omitting the $ sign before field names

3. Given collections orders and products, what will be the output of this aggregation on orders?

{
  $lookup: {
    from: "products",
    let: { prod_id: "$productId" },
    pipeline: [
      { $match: { $expr: { $eq: ["$_id", "$$prod_id"] } } },
      { $project: { name: 1, price: 1, _id: 0 } }
    ],
    as: "productDetails"
  }
}

medium

A. Each order document will have a 'productDetails' field with only product IDs

B. Each order document will have a new field 'productDetails' containing an array with matching product's name and price

C. The query will throw a syntax error due to incorrect variable reference

D. The 'productDetails' field will be a single object, not an array

Solution

1. Step 1: Understand $lookup with pipeline and let

   The let defines prod_id from orders.productId. The pipeline matches products._id to this variable.

2. Step 2: Analyze pipeline stages

   The pipeline filters products matching the order's productId and projects only name and price fields, excluding _id.

3. Final Answer:

   Each order document will have a new field 'productDetails' containing an array with matching product's name and price -> Option B

4. Quick Check:

   $lookup with pipeline returns array of matched docs [OK]

Hint: Remember $lookup with pipeline returns array in 'as' field [OK]

Common Mistakes:

• Expecting a single object instead of an array
• Using wrong variable reference syntax like '$prod_id' instead of '$$prod_id'
• Forgetting to project fields inside pipeline

4. Identify the error in this $lookup stage:

{
  $lookup: {
    from: "employees",
    let: { empId: "$employeeId" },
    pipeline: [
      { $match: { $expr: { $eq: ["$_id", "$$empId"] } } }
    ],
    as: "employeeInfo"
  }
}

medium

A. Variable reference inside $expr should be "$$empId" instead of "$empId"

B. The let keyword is not allowed inside $lookup

C. The from field must be an array, not a string

D. The as field cannot be named employeeInfo

Solution

1. Step 1: Check variable usage in $expr

   Variables defined in let must be referenced with double dollar signs $$ inside the pipeline.

2. Step 2: Identify incorrect variable reference

   The code uses "$empId" instead of "$$empId", causing a runtime error.

3. Final Answer:

   Variable reference inside $expr should be "$$empId" instead of "$empId" -> Option A

4. Quick Check:

   Use $$ to reference let variables inside pipeline [OK]

Hint: Use double $$ to reference let variables inside pipeline [OK]

Common Mistakes:

• Using single $ instead of double $$ for let variables
• Misplacing let outside $lookup
• Incorrect data type for 'from' field

5. You want to join orders with products but only include products priced above 100 in the joined array. Which $lookup pipeline correctly achieves this?

hard

A. { $lookup: { from: "products", let: { pid: "$productId" }, pipeline: [ { $match: { $expr: { $and: [ { $eq: ["$_id", "$$pid"] }, { $gt: ["$price", 100] } ] } } } ], as: "expensiveProduct" } }

B. { $lookup: { from: "products", localField: "productId", foreignField: "_id", as: "expensiveProduct", pipeline: [ { $match: { price: { $gt: 100 } } } ] } }

C. { $lookup: { from: "products", let: { pid: "$productId" }, pipeline: [ { $match: { _id: "$$pid", price: { $gt: 100 } } } ], as: "expensiveProduct" } }

D. { $lookup: { from: "products", let: { pid: "$productId" }, pipeline: [ { $match: { $expr: { $eq: ["$_id", "$$pid"] } } }, { $match: { price: { $gt: 100 } } } ], as: "expensiveProduct" } }

Solution

1. Step 1: Understand filtering with $expr and $and

   We must match documents where _id equals the variable and price is greater than 100 in a single $match using $expr and $and.

2. Step 2: Analyze each option's pipeline

   { $lookup: { from: "products", let: { pid: "$productId" }, pipeline: [ { $match: { $expr: { $and: [ { $eq: ["$_id", "$$pid"] }, { $gt: ["$price", 100] } ] } } } ], as: "expensiveProduct" } } correctly uses $expr with $and combining both conditions. { $lookup: { from: "products", localField: "productId", foreignField: "_id", as: "expensiveProduct", pipeline: [ { $match: { price: { $gt: 100 } } } ] } } wrongly uses pipeline with localField/foreignField which is invalid. { $lookup: { from: "products", let: { pid: "$productId" }, pipeline: [ { $match: { _id: "$$pid", price: { $gt: 100 } } } ], as: "expensiveProduct" } } uses invalid $match syntax inside pipeline. { $lookup: { from: "products", let: { pid: "$productId" }, pipeline: [ { $match: { $expr: { $eq: ["$_id", "$$pid"] } } }, { $match: { price: { $gt: 100 } } } ], as: "expensiveProduct" } } splits conditions into two $match stages, but second $match cannot use field without $expr inside pipeline.

3. Final Answer:

   Option A correctly filters joined products priced above 100 using $expr and $and -> Option A

4. Quick Check:

   Use $expr with $and for multiple conditions in $lookup pipeline [OK]

Hint: Combine conditions inside one $match using $expr and $and [OK]

Common Mistakes:

• Using localField/foreignField with pipeline together
• Splitting conditions into multiple $match without $expr
• Incorrect $match syntax inside pipeline