The $ifNull operator supplies a default value when a field is null or missing. Use it to clean up reports, fill gaps in user profiles, and avoid null checks in application code.
Default when null/missing.
Two-element array form.
Treats absent keys as null.
Add safe computed fields.
Defaults, cleanup, reports.
Try multiple fallbacks.
In MongoDB’s aggregation framework, the $ifNull operator evaluates an expression and returns it when the value is present. If the expression is null or the field is missing, MongoDB returns a replacement default instead. For example, show "Guest" when a user has no displayName.
$ifNull only checks for null and missing fields. It does not treat 0, false, or "" as null — use $cond when you need those rules.
$ifNull takes exactly two expressions in an array. The second value is the fallback:
{ $ifNull: [ <expression>, <replacement-if-null> ] }Chained fallbacks (try field A, then B, then a literal default):
{ $ifNull: [ "$fieldA", { $ifNull: [ "$fieldB", "default" ] } ] }null.0, false, and empty strings are not replaced.$project, $addFields, $set, or $group.$ifNull for simple fallbacks; use $cond for comparisons like score >= 70| Question | Answer |
|---|---|
| Operator type | Aggregation expression operator (null coalescing) |
| Syntax | { $ifNull: [ expression, replacement ] } |
| Triggers fallback | null or missing field only |
| Does not replace | 0, false, "" |
| Common stages | $project, $addFields, $set, $group |
{
$ifNull: [
"$email",
"unknown@example.com"
]
}Fill missing email
{
$ifNull: [
"$discount",
0
]
}Null discount → 0
{
$ifNull: [
"$nickname",
{
$ifNull: [
"$name",
"Guest"
]
}
]
}Try nickname, then name
{
$ifNull: [
"$total",
{
$multiply: [
"$qty",
"$price"
]
}
]
}Computed fallback
Fill missing emails, default numeric fields, chain fallbacks across profile fields, and compute safe totals with $ifNull.
Use a users collection and replace missing email fields with a placeholder.
Suppose you have a users collection where some profiles omit email:
[
{ "_id": ObjectId("609c26812e9274a86871bc6a"), "name": "Alice", "email": "alice@example.com" },
{ "_id": ObjectId("609c26812e9274a86871bc6b"), "name": "Bob", "email": null },
{ "_id": ObjectId("609c26812e9274a86871bc6c"), "name": "Charlie" }
]Charlie’s document has no email key at all — MongoDB treats that as missing, same as null.
Return the email when present; otherwise use "unknown@example.com":
db.users.aggregate([
{
$project: {
name: 1,
safeEmail: {
$ifNull: ["$email", "unknown@example.com"]
}
}
}
])null triggers the fallback.Numeric defaults, display-name chains, and computed fallbacks in orders.
Orders without a discount should count as 0 in reports:
db.orders.aggregate([
{
$addFields: {
discountApplied: {
$ifNull: ["$discount", 0]
}
}
}
])
// discount: 10 → discountApplied: 10
// discount: null → discountApplied: 0
// (field missing) → discountApplied: 0$addFields keeps all existing fields and adds discountApplied. A real 0 discount would stay 0 — only null and missing values are replaced.
Prefer nickname, then name, then "Guest":
db.users.aggregate([
{
$project: {
displayName: {
$ifNull: [
"$nickname",
{ $ifNull: ["$name", "Guest"] }
]
}
}
}
])The inner $ifNull runs only when nickname is null or missing. This pattern is common for user-facing labels without storing a redundant field.
Use a calculated total when total was never stored on the document:
db.orders.aggregate([
{
$project: {
product: 1,
finalTotal: {
$ifNull: [
"$total",
{ $multiply: ["$qty", "$price"] }
]
}
}
}
])
// total: 120 → finalTotal: 120
// total: null → finalTotal: qty × price
// total missing → finalTotal: qty × priceThe second argument does not have to be a literal — it can be any expression. MongoDB evaluates the fallback only when the first value is null or missing.
$ifNull WorksIt reads a field reference or nested expression for the current document.
If the value exists and is not null, that value is returned immediately.
The second expression — literal, field, or nested operator — becomes the result.
Reports and APIs get consistent data without null-handling logic in your app.
The $ifNull operator is the simplest way to handle null and missing values inside MongoDB aggregation pipelines. It keeps reports readable and reduces defensive coding in your application layer.
Start with single-field defaults, then chain nested $ifNull calls when you need multiple fallbacks. For boolean conditions (not just null checks), use $cond instead.
$ifNull for null and missing fields — it is shorter than equivalent $cond$ifNull for nickname → name → default patternsnull, and real values$project or $addFields for clean output fields$ifNull to replace 0, false, or ""$cond when a simple null fallback is enough$ifNull call$let for reuse$ifNullUse these points when handling null or missing values in MongoDB.
Default when null/missing.
PurposeTwo-element array.
SyntaxAbsent fields count.
RuleMultiple fallbacks.
PatternUse $cond instead.
ImportantMove on to $in for membership tests, or review $hour for extracting time from dates.
5 people found this page helpful