Capstok — learn by doing

Why this matters

MongoDB is often described as schema-less and join-less, but $lookup brings left outer join semantics into the aggregation pipeline. This matters because real applications inevitably need to correlate data across collections — orders with users, posts with authors, products with inventory. Doing this in application code with N+1 queries is a common scaling pitfall that$ lookup eliminates by executing the join server-side. Understanding $lookup's performance characteristics — it triggers a separate collection scan per pipeline document unless you index the foreign key — prevents it from becoming a new performance problem.

Demo

Join an orders collection with a users collection to embed user details on each order.

Try it yourself

Run the $lookup pipeline without an index on users._id. Then create an index and re-run. Use explain('executionStats') to compare totalDocsExamined in the lookup stage.
Change the $unwind stage to `{ path: '$ user', preserveNullAndEmptyArrays: true }. Insert an order with no matching userId. Confirm the order still appears with user: null`.
Replace the simple $lookup with a pipeline-form$ lookup that filters the joined documents: only embed users whose active field is true. Verify inactive users produce empty arrays.

Prompt your AI

Use these three in order. Each builds on the one before.

1. Basics & terminology

Explain MongoDB's $lookup stage. What SQL operation does it approximate, and what are the required fields in the $lookup document?

2. Why it works (the mechanism)

How does MongoDB physically execute a $lookup — does it load the entire foreign collection into memory, or does it use an index? What index should exist on the foreign collection for best performance?

3. Advanced — application & what's next

I need to join three collections in sequence: orders → line_items → products. Design the pipeline. At what point does it become worth denormalizing instead of chaining $lookup stages?

References

package main

import (
	"context"; "fmt"
	"go.mongodb.org/mongo-driver/bson"
	"go.mongodb.org/mongo-driver/mongo"
	"go.mongodb.org/mongo-driver/mongo/options"
)

func main() {
	client, _ := mongo.Connect(context.TODO(), options.Client().ApplyURI("mongodb://localhost:27017"))
	orders := client.Database("demo").Collection("orders")

	pipeline := bson.A{
		bson.D{{"$lookup", bson.D{
			{"from", "users"},
			{"localField", "userId"},
			{"foreignField", "_id"},
			{"as", "user"},
		}}},
		bson.D{{"$unwind", "$user"}},
		bson.D{{"$project", bson.D{
			{"orderId", "$_id"},
			{"amount", 1},
			{"userName", "$user.name"},
			{"_id", 0},
		}}},
	}

	cursor, _ := orders.Aggregate(context.TODO(), pipeline)
	var results []bson.M
	cursor.All(context.TODO(), &results)
	for _, r := range results { fmt.Println(r) }
}

Run: go run main.go

$lookup — joining collections