Null, Missing Fields, and Undefined Values

One of the most important MongoDB distinctions is the difference between a field that contains null and a field that does not exist.

Consider the following documents:

{ name: "Arun", phone: null }
{ name: "Meera" }
{ name: "Ravi", phone: "9876543210" }

These represent three different situations:

The phone field exists and its value is null.
The phone field is absent.
The phone field contains a string.

The distinction affects query results, aggregation, validation, and application logic.

Querying with null

db.users.find({ phone: null });

This query matches documents where phone is explicitly null and documents where phone is missing.

This behavior is useful to know, but it may be too broad when the application needs only one of those states.

Finding explicit null values

db.users.find({
 phone: { $type: "null" }
});

This identifies documents where phone contains the BSON null type.

Finding missing fields

db.users.find({
 phone: { $exists: false }
});

This identifies documents that do not contain the phone field.

Finding fields that exist and are not null

db.users.find({
 phone: {
 $exists: true,
 $ne: null
 }
});

This commonly selects documents where phone exists and is not null. It does not guarantee that the value is a valid phone number; type and format validation may still be needed.

Why missing fields occur

Missing fields can result from optional attributes, legacy document versions, incomplete migrations, conditional application writes, or inconsistent data contracts.

For example, an older user record may not contain emailVerified because the application did not introduce that field until a later version.

Null is not a universal substitute for missing

Use null when the field exists but has no known or applicable value, according to your data contract. Omit a field when its absence has a meaningful interpretation or when it is optional.

The correct choice depends on your application's semantics. Do not use null and missing interchangeably without considering how queries and validation interpret them.

Undefined values

JavaScript has an undefined value, but BSON's supported value model is not the same as JavaScript's. Do not design a MongoDB schema around storing undefined as though it were a normal, portable BSON value.

Modern MongoDB applications should use explicit values, null where appropriate, or omitted fields according to their data model. Legacy data may contain historical representations that need separate inspection and migration.

Compare null and missing fields

db.nullExamples.insertMany([
 { name: "Arun", phone: null },
 { name: "Meera" },
 { name: "Ravi", phone: "9876543210" }
]);

// Null or missing.
db.nullExamples.find({ phone: null });

// Explicit BSON null.
db.nullExamples.find({ phone: { $type: "null" } });

// Missing field.
db.nullExamples.find({ phone: { $exists: false } });

// Existing and non-null.
db.nullExamples.find({
 phone: { $exists: true, $ne: null }
});

💡 The first filter matches both explicit null and missing fields. The $type: "null" filter isolates explicit null values, while $exists: false identifies missing fields. The final query selects documents where the field exists and is not null, though it does not validate the phone number's format.

Key Takeaways

Null and missing fields represent different data states.
A query using { field: null } matches explicit null and missing fields.
$type: "null" identifies explicit BSON null values.
$exists: false identifies missing fields.
Schema design should define when to use null and when to omit a field.

Knowledge Check

Which query matches documents where `phone` is explicitly stored as BSON null rather than being absent?