Embedded vs Referenced

# Embedding — related data lives inside the parent document

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")
db     = client["dataplexa"]

# Example: order with embedded line items (already our Dataplexa model)
# The items array is embedded — retrieved in the same query as the order
order = db.orders.find_one(
    {"_id": "o001"},
)
print("Order with embedded items — single query:")
print(f"  order id:  {order['_id']}")
print(f"  user:      {order['user_id']}")
print(f"  status:    {order['status']}")
print(f"  total:     ${order['total']:.2f}")
print(f"  items:")
for item in order["items"]:
    print(f"    product: {item['product_id']}  qty: {item['qty']}  price: ${item['price']:.2f}")

# Embedding is ideal here because:
# 1. Items are ALWAYS needed with the order — never queried independently
# 2. The item count per order is BOUNDED (realistic max ~100 items)
# 3. Writing the order and items is one ATOMIC operation — no partial writes
# 4. Zero network round trips — one query returns everything

print("\nBenefits of embedding for order items:")
benefits = [
    "One query returns order + all items — zero round trips",
    "Atomic write — order and items succeed or fail together",
    "No $lookup required — simpler query code",
    "Items are always consistent with their parent order",
]
for b in benefits:
    print(f"  ✓ {b}")

# Referencing — linked documents in separate collections

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")
db     = client["dataplexa"]

# Example: reviews referencing both user and product
# The review stores user_id and product_id as foreign-key-style references
review = db.reviews.find_one({"_id": "r001"})
print("Review document (references only — no embedded data):")
print(f"  review id:  {review['_id']}")
print(f"  product_id: {review['product_id']}  ← reference to products collection")
print(f"  user_id:    {review['user_id']}      ← reference to users collection")
print(f"  rating:     {review['rating']}")
print(f"  comment:    {review['comment']}")

# To display the full review with product name and user name
# requires two additional queries (or a $lookup aggregation)
product = db.products.find_one({"_id": review["product_id"]}, {"name": 1, "_id": 0})
user    = db.users.find_one({"_id": review["user_id"]},    {"name": 1, "_id": 0})

print(f"\nFull review (after two additional queries):")
print(f"  User:    {user['name']}")
print(f"  Product: {product['name']}")
print(f"  Rating:  {review['rating']} — \"{review['comment']}\"")

# Why reviews are referenced — not embedded in the product:
print("\nWhy reviews are referenced (not embedded in product):")
reasons = [
    "Unbounded growth — a popular product can have 100,000+ reviews",
    "Queried independently — 'all reviews by user u001' spans products",
    "Embedding would bloat product documents beyond useful size",
    "Reviews can be paginated, sorted, filtered as a standalone collection",
]
for r in reasons:
    print(f"  ✓ {r}")

# $lookup — joining referenced collections server-side

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")
db     = client["dataplexa"]

# Join reviews with their product and user in one aggregation pipeline
pipeline = [
    # Stage 1: filter to reviews for product p001
    {"$match": {"product_id": "p001"}},

    # Stage 2: join with products collection
    {"$lookup": {
        "from":         "products",     # foreign collection
        "localField":   "product_id",   # field in reviews
        "foreignField": "_id",          # field in products
        "as":           "product_info"  # output array field name
    }},

    # Stage 3: join with users collection
    {"$lookup": {
        "from":         "users",
        "localField":   "user_id",
        "foreignField": "_id",
        "as":           "user_info"
    }},

    # Stage 4: flatten the single-element lookup arrays
    {"$unwind": "$product_info"},
    {"$unwind": "$user_info"},

    # Stage 5: project only the fields we need
    {"$project": {
        "rating":       1,
        "comment":      1,
        "product_name": "$product_info.name",
        "reviewer":     "$user_info.name",
        "_id":          0
    }}
]

results = list(db.reviews.aggregate(pipeline))
print(f"Reviews for p001 with product and user names ($lookup):\n")
for r in results:
    print(f"  [{r['rating']}★] {r['reviewer']:15} — \"{r['comment']}\"")
    print(f"       Product: {r['product_name']}")

# Subset pattern — embed the hot data, reference the rest

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017/")
db     = client["dataplexa"]

# Scenario: product page needs the 3 most recent reviews inline
# Full review collection may have thousands per product — don't embed all of them
# Instead: embed the top 3 reviews as a "reviews_preview" subset on the product

# What the product document would look like with the subset pattern:
product_with_subset = {
    "_id":      "p001",
    "name":     "Wireless Mouse",
    "price":    29.99,
    "category": "Electronics",
    "rating":   4.5,
    # Hot data — embedded for instant page load without $lookup
    "reviews_preview": [
        {"user_id": "u001", "reviewer": "Alice Johnson", "rating": 5,
         "comment": "Fast and responsive, great for gaming.", "date": "2024-01-15"},
        {"user_id": "u004", "reviewer": "David Lee",     "rating": 4,
         "comment": "Good value for money, works well.",    "date": "2024-02-10"},
    ],
    "review_count": 42,   # computed — updated on each new review
}

# Fast product page load — no join needed for the preview
print("Product page — instant load with subset:")
print(f"  {product_with_subset['name']}  ${product_with_subset['price']}")
print(f"  Rating: {product_with_subset['rating']} ({product_with_subset['review_count']} reviews)")
print(f"  Recent reviews:")
for r in product_with_subset["reviews_preview"]:
    print(f"    [{r['rating']}★] {r['reviewer']} — \"{r['comment']}\"")

# Full reviews page — query the reviews collection with pagination
print("\nFull review page — query reviews collection:")
all_reviews = db.reviews.find(
    {"product_id": "p001"},
    {"user_id": 1, "rating": 1, "comment": 1, "_id": 0}
)
for r in all_reviews:
    print(f"  [{r['rating']}★] user: {r['user_id']} — \"{r['comment']}\"")

# Decision framework — embed or reference?

decision_tree = [
    {
        "question": "Can the child data grow without bound?",
        "if_yes":   "REFERENCE — unbounded arrays hit the 16 MB limit",
        "if_no":    "Continue to next question",
        "example":  "Orders per user → YES → reference",
    },
    {
        "question": "Is the child data queried independently of the parent?",
        "if_yes":   "REFERENCE — child needs its own collection for independent queries",
        "if_no":    "Continue to next question",
        "example":  "Reviews queried by user_id across all products → YES → reference",
    },
    {
        "question": "Is the child data always retrieved with the parent?",
        "if_yes":   "EMBED — co-retrieval means embedding eliminates round trips",
        "if_no":    "Continue to next question",
        "example":  "Order items always fetched with order → YES → embed",
    },
    {
        "question": "Is the data written atomically with the parent?",
        "if_yes":   "EMBED — single-document atomicity is free",
        "if_no":    "Continue to next question",
        "example":  "Order + items written in one operation → YES → embed",
    },
    {
        "question": "Does the child data change frequently and independently?",
        "if_yes":   "REFERENCE — frequent updates to embedded data cause document churn",
        "if_no":    "EMBED — stable data is safe to embed",
        "example":  "User profile fields updated independently → YES → reference each field separately",
    },
]

print("Embed vs Reference decision framework:\n")
for i, step in enumerate(decision_tree, 1):
    print(f"  Step {i}: {step['question']}")
    print(f"    YES → {step['if_yes']}")
    print(f"    NO  → {step['if_no']}")
    print(f"    e.g. {step['example']}")
    print()

# Embed vs Reference trade-off comparison

tradeoffs = {
    "Dimension": [
        "Read performance",
        "Write performance (single parent)",
        "Write performance (shared child data)",
        "Atomicity",
        "Data duplication",
        "Max data size",
        "Independent queries on child",
        "Schema flexibility",
        "Referential integrity",
    ],
    "Embed": [
        "Excellent — one document read",
        "Good — one document write",
        "Poor — must update every parent containing the copy",
        "Free — single-document atomic",
        "High if child shared across many parents",
        "Limited to 16 MB per document",
        "Only via array scan inside document",
        "Lower — parent shape changes with child",
        "Automatic — child is part of parent",
    ],
    "Reference": [
        "Moderate — requires $lookup or two queries",
        "Moderate — may need two writes",
        "Excellent — update child once",
        "Requires multi-doc transaction for atomicity",
        "None — single source of truth",
        "Unlimited — child is its own document",
        "Full — index and query child collection freely",
        "Higher — child schema evolves independently",
        "Manual — application must maintain consistency",
    ],
}

header = f"  {'Dimension':45} {'Embed':45} {'Reference'}"
print(header)
print("  " + "─" * 130)
for i, dim in enumerate(tradeoffs["Dimension"]):
    embed = tradeoffs["Embed"][i]
    ref   = tradeoffs["Reference"][i]
    print(f"  {dim:45} {embed:45} {ref}")