$project (Projection)
Last updated: 2026-10-09
$project (Projection)
$project is the projection stage: it selects or excludes fields, or computes new ones, mapping each document to a new shape. Unlike $addFields, it outputs only _id and explicitly listed fields by default: 1 includes, 0 excludes, and an expression creates a new field. Use it to shrink documents, rename fields, or flatten embedded objects. Inclusion and exclusion cannot be mixed (except _id).
| Category | Core Stages |
|---|---|
| MongoDB Version | 1.0+ |
| Example Language | mongosh (Shell) |
📝 Syntax
{ $project: { <field>: <1 or 0 or expression>, ... } }⚙️ Parameters
| field projection | Field names mapped to 1 (include), 0 (exclude), or an aggregation expression (computed field). |
|---|
Returns：Projected document stream
▶ Example
Run the commands below in your local mongosh (requires a running mongod):
// $project: keep name, compute total
db.orders.aggregate([
{ $project: { _id: 0, name: 1, total: { $multiply: ['$price', '$qty'] } } }
])Output：
// Each doc now has only name and total
{ "name": "Pen", "total": 150 }
{ "name": "Book", "total": 30 }📌 Notes
- $project is a whitelist: unlisted fields are dropped
- Inclusion and exclusion cannot be mixed (except _id)
- Dotted paths like 'detail.price' rename or flatten embedded fields
🏷️ Related Tags
💡 Related Cases
Advanced Aggregation Pipelines: Complex Expressions and Transformations
Introduction to Aggregate Pipelines: The `aggregate` Method and the Basic Stage
Hands-On: CRUD for a Blog Comment System
Change Streams: Real-Time Change Monitoring
$facet + $bucket + Text/Geospatial Search
$lookup and Associations with Multiple Sets
📚 Related Tutorials
❓ FAQ
QWhat is the difference between $project and $addFields?
A$addFields keeps all original fields and adds new ones; $project drops unlisted fields by default, used to trim or rebuild the document shape.
QCan $project exclude multiple fields at once?
AYes, set them all to 0, e.g. { $project: { secret: 0, log: 0 } }, which keeps every other field.
QDoes $project change field order?
AOutput fields follow the order written in the projection, regardless of the original document order.
