MongoDB $where Operator

What You’ll Learn

The $where operator runs a JavaScript expression against each document in a find() query. It is a legacy query operator — useful to understand for reading old code, but modern MongoDB apps should prefer $expr and native operators instead.

Definition and Usage

In MongoDB, the $where operator is a query operator that evaluates a JavaScript expression for every document in a collection. If the expression returns true, the document is included in the result set. Inside the script, this refers to the current document, so you can write conditions like this.qty * this.price > 1000.

MongoDB deprecated $where in version 4.4 because it forces a collection scan, cannot use indexes effectively, and introduces security risks when user input is embedded in JavaScript strings. For new projects, use $expr with aggregation operators such as $multiply, $gt, and $eq.

📝 Syntax

$where accepts either a JavaScript string or a function:

String Form

{
  $where: "<JavaScript expression as string>"
}

// Example:
db.products.find({
  $where: "this.qty * this.price > 1000"
})

Function Form

{
  $where: function() {
    return <boolean expression>;
  }
}

// Example:
db.products.find({
  $where: function() {
    return this.qty * this.price > 1000;
  }
})

Modern Alternative with $expr

// Preferred in modern MongoDB:
db.products.find({
  $expr: {
    $gt: [
      { $multiply: ["$qty", "$price"] },
      1000
    ]
  }
})

Syntax Rules

• Query only — use in find() filters, not as an aggregation expression operator.
• this — refers to the document being evaluated (this.price, this.tags).
• Return value — must be truthy to include the document.
• Performance — evaluates JavaScript on every document; avoid on large collections.
• Security — never concatenate untrusted user input into the JavaScript string.
• Status — deprecated since MongoDB 4.4; may be removed in future releases.

Examples Gallery

Filter a products collection with $where, then see the recommended $expr equivalents for the same logic.

[
  { "_id": 1, "name": "Widget A", "qty": 50,  "price": 25.00 },
  { "_id": 2, "name": "Widget B", "qty": 10,  "price": 120.00 },
  { "_id": 3, "name": "Widget C", "qty": 100, "price": 8.50 },
  { "_id": 4, "name": "Widget D", "qty": 5,   "price": 250.00 }
]

db.products.find({
  $where: "this.qty * this.price > 1000"
})

// Matches:
// Widget A → 50 * 25   = 1250  ✓
// Widget B → 10 * 120  = 1200  ✓
// Widget D → 5 * 250   = 1250  ✓

{ "_id": 1, "name": "Widget A", "qty": 50,  "price": 25.00 }
{ "_id": 2, "name": "Widget B", "qty": 10,  "price": 120.00 }
{ "_id": 4, "name": "Widget D", "qty": 5,   "price": 250.00 }

db.products.find({
  $where: function() {
    return this.qty * this.price > 1000;
  }
})

db.events.find({
  $where: "this.endDate > this.startDate"
})

// $expr alternative (preferred):
db.events.find({
  $expr: {
    $gt: ["$endDate", "$startDate"]
  }
})

db.products.find({
  $where: "this.tags && this.tags.length > 2"
})

// $expr alternative (preferred):
db.products.find({
  $expr: {
    $gt: [{ $size: "$tags" }, 2]
  }
})

// Legacy $where:
db.products.find({
  $where: "this.qty * this.price > 1000"
})

// Modern $expr (same result, better performance):
db.products.find({
  $expr: {
    $gt: [
      { $multiply: ["$qty", "$price"] },
      1000
    ]
  }
})

// Also works in aggregation $match:
db.products.aggregate([
  {
    $match: {
      $expr: {
        $gt: [
          { $multiply: ["$qty", "$price"] },
          1000
        ]
      }
    }
  }
])

// DANGEROUS — do not do this:
var userInput = "1000; return true";  // malicious input
db.products.find({
  $where: "this.qty * this.price > " + userInput
})

// SAFE — use parameterized $expr instead:
var threshold = 1000;
db.products.find({
  $expr: {
    $gt: [
      { $multiply: ["$qty", "$price"] },
      threshold
    ]
  }
})

🚀 Use Cases

• Legacy codebases — understand and migrate old queries that still use $where.
• Field comparisons — filter when one field must be greater than another (prefer $expr today).
• Complex conditions — prototype logic quickly in tutorials (rewrite with native operators for production).
• One-off admin scripts — ad hoc filtering on small collections during data exploration.

💡 Best Practices