Ensure the argument resolves to a number (field, literal, or nested math).
Pass that expression to $ceil to get the ceiling integer.
Optionally combine with $divide for “boxes needed” style math.
Piece
Required?
Role
$ceil
Yes
Round up → integer
Expression
Yes
Number, field, or nested math
$divide (etc.)
No
Build a ratio before ceiling
Pseudocode
Pseudocode
for each document:
x = evaluate(expression)
if x is null or missing:
result = null
else if x is NaN:
result = NaN
else:
result = ceil(x) // smallest integer ≥ x
emit { ..., field: result }
Reference
Cheat Sheet
Keep these facts handy while writing ceiling expressions.
Topic
Detail
Type
Aggregation expression (not a find filter)
Syntax
{ $ceil: <number> }
Direction
Toward +∞ (up the number line)
Positive example
ceil(7.80) → 8
Negative example
ceil(-2.8) → -2
Integer input
Unchanged (ceil(1) → 1)
Boxes pattern
$ceil({ $divide: [items, perBox] })
Try it
Live Preview
Watch $ceil round a number up. Try a negative value to see rounding toward +∞.
Simulates $ceil (same idea as the mongosh examples below).
Ceiling always moves toward positive infinity. For negatives, that means moving closer to zero—not farther away.
Calculation
Number line (left is smaller):
… -6 -5.34 -5 … 4.32 5 …
ceil(4.32) → 5 (next integer up)
ceil(-5.34) → -5 (next integer up toward +∞)
Not the same as “away from zero”:
away from zero for -5.34 would be -6 ✗
$ceil gives -5 ✓
Check: -5 ≥ -5.34 and is the smallest such integer.
Code
MongoDB Examples
We store three sample numbers (including one negative), apply $ceil, then compute how many boxes an order needs. Run these in mongosh after inserting the sample data once.
Example 1 — Sample Data
Imagine a tiny samples collection with three numbers. One is negative so you can see ceiling toward +∞.
Keep all fields.$addFields adds boxesNeeded next to the originals.
Edge Cases & Pitfalls
Check these before using $ceil in production pipelines.
negatives
Toward +∞, not away from zero
ceil(-2.8) is -2. If you need magnitude-style rounding, combine with $abs carefully—or pick the operator that matches your rule.
null
Null and missing become null
Missing fields return null, not an error. Handle them before math if nulls are invalid in your data.
vs floor
Do not confuse with $floor
$floor rounds down. For 4.32, floor is 4 and ceil is 5.
divide
Avoid divide-by-zero
Box/unit patterns need a non-zero denominator. Guard with $cond or filter bad rows first.
Analysis
Performance Notes
Approach
Cost
Best for
$ceil alone
Per-document math
Rounding stored decimals
$divide + $ceil
Still O(docs)
Units, boxes, billing partials
vs client-side ceil
Same math, less data shipped
When you need the integer in the pipeline
Ceiling math is cheap compared with large sorts or joins. Filter early with $match when only some documents need rounding.
Remember
Key Takeaways
Role: smallest integer ≥ the input (round up).
Direction: toward +∞ (so -2.8 → -2).
Pattern:$ceil(items / perBox) for whole units.
Siblings:$floor down, $round nearest.
One line:$ceil answers “what is the next whole number up?”—toward positive infinity, for positives and negatives.
Frequently Asked Questions
$ceil returns the smallest integer greater than or equal to a number—rounding up toward positive infinity. Use it inside aggregation expression stages such as $project and $addFields.
$ceil always rounds toward positive infinity. For example, ceil(-5.34) returns -5, not -6. That moves the value up the number line, closer to zero for negatives.
$ceil rounds up, $floor rounds down, and $round rounds to the nearest value (with optional place). Use $ceil when partial units must always bill or pack as a full unit.
$ceil returns null when the input is null or the field is missing. If the argument is NaN, $ceil returns NaN.
Yes. An integer is already a whole number, so $ceil leaves it unchanged—ceil(1) is 1.
Yes for the math. Think of $ceil as MongoDB’s aggregation version of Math.ceil—run it in the pipeline, not as a standalone find() filter.
