MongoDB $isNumber Operator

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview
MongoDB $isNumber tutorial — check whether a value is numeric
Definition

What Is $isNumber?

$isNumber is a MongoDB aggregation expression that returns true when its argument is a numeric BSON type (int, long, double, or decimal), and false otherwise. Use it to guard math when mixed types exist.

Remember
$isNumber ≈ “is this a real BSON number?”

{ $isNumber: <expression> }

int / long / double / decimal → true
string "42" / null / missing / array → false
not a find() filter by itself
UsePrefer
Is this value numeric?$isNumber
What BSON type is it?$type
Is this value an array?$isArray
Approach

How to Use $isNumber in MongoDB

Pass one expression. Branch or filter on the boolean result.

  1. Choose an expression stage ($addFields, $project, or $cond).
  2. Pass the field or expression: { $isNumber: "$price" }.
  3. Use the boolean with $cond, or filter via $expr inside $match.
  4. Only then run math ($multiply, $add, …) on that field.
PieceRequired?Role
ExpressionYesValue to test (field path, literal, or nested expression)
Result—true if numeric BSON type, else false
Common partnerNo$cond before math / $convert

Pseudocode

Pseudocode
for each document:
    value = evaluate(expression)
    if value is int or long or double or decimal:
        result = true
    else:
        result = false   // string, null, missing, array, …
    emit { ..., field: result }
Reference

Cheat Sheet

Keep these facts handy while writing numeric type guards.

TopicDetail
TypeAggregation expression (boolean)
Syntax{ $isNumber: <expression> }
True forint, long, double, decimal
False forstring (even "42"), null, missing, array, object
Filter docs$match + $expr: { $isNumber: "$field" }
Guard pattern$cond: [ { $isNumber: "$x" }, { $multiply: ["$x", 1.1] }, null ]
Try it

Live Preview

Pick a sample value and watch $isNumber return true or false.

Simulates $isNumber for common BSON shapes (same idea as the mongosh examples).

Result
value = 12
$isNumber → true

{ is_number: true }
Trace

Worked Walkthrough — Mixed price

Some products store price as a number; others store a string or omit the field. $isNumber sorts that out before math.

Calculation
price = 12      → $isNumber → true
price = 2.5     → $isNumber → true
price = "9.99"  → $isNumber → false  (string!)
price missing   → $isNumber → false

Safe tax:
  if $isNumber(price):
      with_tax = price * 1.1
  else:
      with_tax = null

Tip: "9.99" looks numeric to humans — MongoDB still treats it as a string.
Code

MongoDB Examples

We use a small products collection with a mixed-type price field. First we flag numbers, then we safely apply a 10% increase. Insert the sample data once in mongosh.

Example 1 — Sample Data

Imagine four products. Some have a numeric price, one has a string price, and one has no price field.

mongosh
db.products.insertMany([
  { _id: 1, name: "Mug", price: 12 },
  { _id: 2, name: "Notebook", price: "9.99" },
  { _id: 3, name: "Pen", price: 2.5 },
  { _id: 4, name: "Gift" }
]);

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps four documents in products. Run find() to see them:

mongosh
db.products.find()

Read those documents like this:

Field in MongoDBExamplePlain English
_id1Product id for this lesson
name"Mug"Product name
price12 or "9.99"Sometimes a number, sometimes a string
Picture
Mug       price: 12      → number? yes
Notebook  price: "9.99"  → number? no (string)
Pen       price: 2.5     → number? yes
Gift      (no price)     → number? no

How It Works

  1. Insert once. insertMany adds four product documents.
  2. MongoDB keeps the types you wrote. Numbers stay numbers; quoted values stay strings.
  3. find() shows the same shape. What you inserted is what you get back—ready for $isNumber next.

Example 2 — Flag Numbers

Goal: add price_is_number so you can see which documents store price as a numeric type.

mongosh
db.products.aggregate([
  {
    $addFields: {
      price_is_number: { $isNumber: "$price" }
    }
  }
]);

How It Works

  1. Read each price value. "$price" may be a number, a string, or missing.
  2. Test the type. $isNumber returns a boolean only—it does not convert the value.
  3. String trap. Notebook’s "9.99" looks numeric but is still a string → false.
  4. Missing → false. Gift has no price field, so the result is false.

Example 3 — Safe Math With $cond

Goal: add 10% only when price is a number. Otherwise store null instead of erroring.

mongosh
db.products.aggregate([
  {
    $addFields: {
      price_plus_10: {
        $cond: [
          { $isNumber: "$price" },
          { $multiply: ["$price", 1.1] },
          null
        ]
      }
    }
  }
]);

How It Works

  1. Same stored documents. Still using the four products from Example 1.
  2. Guard first. $isNumber: "$price" decides which branch $cond takes.
  3. Number path. Mug → 12 * 1.1; Pen → 2.5 * 1.1.
  4. Non-number path. Notebook and Gift skip multiply and get null—no pipeline error.

Edge Cases & Pitfalls

Check these before using $isNumber in production pipelines.

string

Numeric-looking strings are false

"42" and "9.99" are strings. Convert with $toDouble or $convert when needed.

query

Not a find filter

{ price: { $isNumber: true } } does not work. Filter with $match + $expr.

null

Null and missing → false

Neither is a number. That is useful for guards, but remember it is not the same as “zero.”

math

Guard before arithmetic

Multiplying a string can error or coerce unexpectedly. Wrap math with $isNumber + $cond first.

Analysis

Performance Notes

ApproachCostBest for
$isNumberPer-document type checkMixed-type numeric fields
+ $cond / mathStill O(docs)Safe calculations on dirty data
$match + $exprScan (expression filter)Keep only numeric rows

Type checks are cheap. Prefer storing prices as real numbers when possible—then you can skip guards and use simpler filters in earlier $match stages.

Remember

Key Takeaways

  • Role: boolean test for numeric BSON types.
  • Strings: "42" is still false.
  • Guard: use before $multiply / $add.
  • Filter: $match + $expr, not a plain find query.

One line: $isNumber answers “is this a real BSON number?”—true or false, before you do math.

Frequently Asked Questions

$isNumber returns true when the evaluated expression is a numeric BSON type—Integer, Long, Double, or Decimal—and false otherwise. Use it inside aggregation expression stages such as $project, $addFields, and $cond.
Use { $isNumber: <expression> }. The expression can be a field path like "$price" or any other aggregation expression.
No. $isNumber checks BSON type, not text content. The string "42" returns false. Convert with $toDouble / $convert if you need a number.
Use $match with $expr: { $match: { $expr: { $isNumber: "$price" } } }. Plain query syntax like { price: { $isNumber: true } } does not work.
$isNumber returns only true or false for numeric types. $type returns the BSON type name or number and can identify any type.
Both return false. $isNumber does not error on missing fields—it simply reports that the value is not a number.

Next: $isoDayOfWeek

Return the ISO-8601 day of the week for a date.

$isoDayOfWeek tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

9 people found this page helpful

MongoDB $isArray Operator MongoDB $isoDayOfWeek Operator