MongoDB $isNumber Operator

What You’ll Learn

The $isNumber operator checks whether a value is a numeric BSON type. It returns true or false — useful for data validation, safe math in pipelines, and filtering documents before applying operators like $add, $abs, or $round.

Definition and Usage

In MongoDB’s aggregation framework, the $isNumber operator evaluates an expression and returns true when the result is a numeric BSON type (int, long, double, or decimal), and false for strings, booleans, objects, arrays, null, and missing fields. This is especially helpful when imported data stores prices or quantities as strings like "19.99" instead of actual numbers.

Use $isNumber as a guard before math operators. For example, only run $add or $abs when a field is truly numeric, preventing pipeline errors on malformed documents.

📝 Syntax

The $isNumber operator takes a single expression to evaluate:

{ $isNumber: <expression> }

Common Patterns

// Check a document field
{ $isNumber: "$price" }

// Filter documents where price is numeric
{ $match: { $expr: { $isNumber: "$price" } } }

// Guard before math in $cond
{ $cond: [
    { $isNumber: "$quantity" },
  { $multiply: [ "$quantity", "$unitPrice" ] },
  0
] }

Syntax Rules

• <expression> — can be a field path ("$price"), a literal number, or another expression.
• Returns true for int, long, double, and decimal BSON types.
• Returns false for numeric-looking strings like "42" or "19.99".
• Returns false for null, missing fields, arrays, objects, and booleans.
• Use inside $project, $addFields, $cond, and $match (with $expr).

Examples Gallery

Walk through sample inventory data with mixed field types, validate numeric values with $project, and apply safe math only when types are correct.

[
  { "_id": ObjectId("609c26812e9274a86871bc6a"), "item": "Notebook", "price": 12.50, "quantity": 100 },
  { "_id": ObjectId("609c26812e9274a86871bc6b"), "item": "Pen Pack", "price": "8.99", "quantity": 50 },
  { "_id": ObjectId("609c26812e9274a86871bc6c"), "item": "Stapler", "price": 15.00, "quantity": "25" },
  { "_id": ObjectId("609c26812e9274a86871bc6d"), "item": "Eraser", "quantity": 200 }
]

db.inventory.aggregate([
  {
    $project: {
      item: 1,
      price: 1,
      quantity: 1,
      priceIsNumber: {
        $isNumber: "$price"
      },
      quantityIsNumber: {
        $isNumber: "$quantity"
      }
    }
  }
])

// Notebook  → priceIsNumber: true,  quantityIsNumber: true
// Pen Pack   → priceIsNumber: false, quantityIsNumber: true  (price is "8.99")
// Stapler    → priceIsNumber: true,  quantityIsNumber: false (quantity is "25")
// Eraser     → priceIsNumber: false, quantityIsNumber: true  (price missing)

db.inventory.aggregate([
  {
    $match: {
      $expr: {
        $and: [
          { $isNumber: "$price" },
          { $isNumber: "$quantity" }
        ]
      }
    }
  },
  {
    $project: {
      item: 1,
      price: 1,
      quantity: 1
    }
  }
])

// Notebook → included (price: 12.50, quantity: 100)
// Pen Pack  → excluded (price is string)
// Stapler   → excluded (quantity is string)
// Eraser    → excluded (price missing)

db.inventory.aggregate([
  {
    $project: {
      item: 1,
      totalValue: {
        $cond: [
          {
            $and: [
              { $isNumber: "$price" },
              { $isNumber: "$quantity" }
            ]
          },
          {
            $multiply: [ "$price", "$quantity" ]
          },
          0
        ]
      }
    }
  }
])

// Notebook → totalValue: 1250    (12.50 × 100)
// Pen Pack  → totalValue: 0      (price is string)
// Stapler   → totalValue: 0      (quantity is string)
// Eraser    → totalValue: 0      (price missing)

db.inventory.aggregate([
  {
    $project: {
      item: 1,
      price: 1,
      needsPriceFix: {
        $not: {
          $isNumber: "$price"
        }
      }
    }
  },
  {
    $match: {
      needsPriceFix: true
    }
  }
])

db.transactions.aggregate([
  {
    $project: {
      amount: 1,
      absoluteAmount: {
        $cond: [
          { $isNumber: "$amount" },
          { $abs: "$amount" },
          null
        ]
      }
    }
  }
])

🚀 Use Cases

• Schema validation — detect documents where numeric fields are stored as strings from imports or APIs.
• Safe math pipelines — guard $add, $multiply, $abs, and $round with an $isNumber check.
• Data cleanup — find and flag malformed records before ETL or reporting jobs.
• Conditional processing — branch logic in $cond based on whether values are numeric.

💡 Best Practices