Project Nested Fields in MongoDB

MongoDB documents can contain embedded documents, such as an address object inside a user record. A projection controls which fields a query returns. For example, selecting address.city returns that nested value while preserving its nested shape. Use find() projection for a straightforward query result, $project when shaping documents in an aggregation pipeline, and $unset when removing selected fields from pipeline results.

Understanding Nested Field Projection in MongoDB

Suppose a document has name and address fields, and address contains street, city, and country. A nested path uses dot notation, such as address.city. Projection changes the returned document; it does not change the stored source document. The examples below use this same shape. In find() projections, _id is included by default unless explicitly excluded.

Use Dot Notation with find() to Select Nested Fields

To return only the city from the nested address, include its dotted path. This MongoDB shell expression is a syntax illustration and is not executed by the configured runtime:

db.users.find({}, { "address.city": 1, "_id": 0 })

The returned shape is { "address": { "city": "New York" } }. Omit _id: 0 if the identifier should remain in each result. To exclude a nested path while keeping other fields, use 0, as in { "address.country": 0 }.

An inclusion projection generally cannot mix included and excluded fields. The special exception is _id: it may be excluded while other paths are included. Choose either an inclusion projection or an exclusion projection for the other fields.

Run this example:

document = {"name": "Ava", "address": {"city": "New York", "country": "USA"}}
result = {"address": {"city": document["address"]["city"]}}
print(result)

{'address': {'city': 'New York'}}

This small Python example illustrates the returned nested shape; it does not connect to MongoDB. The MongoDB query above uses the corresponding dotted path.

Use the $project Aggregation Stage to Shape Nested Fields

In an aggregation pipeline, $project can include nested paths and map source paths to output fields. For example, { $project: { _id: 0, city: "$address.city", name: 1 } } returns city at the top level, alongside name. A direct path inclusion such as { $project: { "address.city": 1, _id: 0 } } instead keeps the address.city nesting. This makes $project useful when the pipeline needs a specific output shape. Expressions can also compute output values; ensure each expression refers to a field present in the input documents.

Use the $unset Aggregation Stage to Exclude Nested Fields

Use the aggregation $unset stage to remove one or more paths while retaining the other fields: { $unset: ["address.country"] }. A dotted path removes that nested field from the pipeline result. $unset changes which fields continue through the pipeline; it does not filter out documents. To filter documents, use a query condition or a $match stage instead. This stage is an aggregation feature, distinct from the update operator that uses the same name.

Choose Between Query Projection and Aggregation

Use find() with dot notation when a query only needs to include or exclude fields in its returned documents. Choose $project when an aggregation must rename paths, compute values, or define a deliberate output shape. Choose $unset when the pipeline should retain most fields and remove a few. $addFields adds or replaces fields while retaining the rest of each document, so it is not a substitute for selecting a projection. In all three cases, projection or field shaping affects results, not the stored documents.