MongoDB $project Stage

What Is $project?

$project is a MongoDB aggregation stage that reshapes each document. You can keep fields, drop fields, rename them, or compute new values—controlling the exact shape that flows to the next stage or the client.

$project = pick / drop / compute fields

{ $project: { <specs> } }

include  → field: 1
exclude  → field: 0   (or use $unset)
compute  → field: <expression>
_id      → included by default; set _id: 0 to hide

Do not mix 1 and 0 on regular fields
(only _id: 0 is allowed with inclusion)

vs $addFields → reshape vs add columns

How to Use $project in MongoDB

Decide inclusion or exclusion, list the specs, then place the stage where you need that shape.

1. Start (or continue) an aggregation pipeline with aggregate([...]).
2. Choose inclusion (field: 1) or exclusion (field: 0)—not both on regular fields.
3. Optional: add computed fields with expressions such as $multiply.
4. Optional: hide _id with _id: 0 in inclusion mode.

Pseudocode

for each document:
    if $project specs are empty:
        error
    if inclusion mode:
        out = { _id: document._id }   // unless _id: 0
        for each field marked 1 or expression:
            out[field] = value or evaluate(expression)
    else if exclusion mode:
        out = copy(document)
        remove listed fields
    emit out

Cheat Sheet

Keep these facts handy while reshaping pipeline documents.

Live Preview

Pick a projection style and see how one order document is reshaped.

$project: { name: 1, price: 1 }

output:
  { _id: 1, name: "Keyboard", price: 45 }

Worked Walkthrough — Slim Order Output

An order has extra notes. Goal: return only name and a computed total, without _id.

Document in:
  { _id: 1, name: "Keyboard", price: 45, qty: 2, notes: "promo" }

$project:
  _id: 0
  name: 1
  total: { $multiply: ["$price", "$qty"] }

45 * 2 = 90

Document out:
  { name: "Keyboard", total: 90 }

MongoDB Examples

Insert sample products, include selected fields, then compute a slim total. Run these in mongosh in order.

db.products.insertMany([
  {
    _id: 1,
    name: "Keyboard",
    price: 45,
    qty: 2,
    notes: "promo"
  },
  {
    _id: 2,
    name: "Mouse",
    price: 25,
    qty: 1,
    notes: "clearance"
  }
]);

db.products.find()

[
  {
    _id: 1,
    name: "Keyboard",
    price: 45,
    qty: 2,
    notes: "promo"
  },
  {
    _id: 2,
    name: "Mouse",
    price: 25,
    qty: 1,
    notes: "clearance"
  }
]

db.products.aggregate([
  {
    $project: {
      name: 1,
      price: 1,
      qty: 1
    }
  }
]);

[
  { _id: 1, name: "Keyboard", price: 45, qty: 2 },
  { _id: 2, name: "Mouse", price: 25, qty: 1 }
]

db.products.aggregate([
  {
    $project: {
      _id: 0,
      name: 1,
      total: { $multiply: ["$price", "$qty"] }
    }
  }
]);

[
  { name: "Keyboard", total: 90 },
  { name: "Mouse", total: 25 }
]

Performance Notes

Prefer $match early to cut document count. Use $project to control the final shape; do not assume early projection always speeds the pipeline.

Key Takeaways