MongoDB $out Stage

Example 1 — Sample Data

Four order lines with region and amount. We load them into a collection named orders for grouping and $out demos.

db.orders.drop()

db.orders.insertMany([
  { _id: 1, region: "east",  amount: 50 },
  { _id: 2, region: "east",  amount: 70 },
  { _id: 3, region: "north", amount: 40 },
  { _id: 4, region: "west",  amount: 25 }
])

How the Data Is Stored in MongoDB

After the insert, MongoDB keeps four documents in orders. Run find() to see them:

db.orders.find()

[
  { _id: 1, region: "east",  amount: 50 },
  { _id: 2, region: "east",  amount: 70 },
  { _id: 3, region: "north", amount: 40 },
  { _id: 4, region: "west",  amount: 25 }
]

Each order line uses these fields:

orders (raw lines):

  _id   region   amount
  ---   ------   ------
    1   east         50
    2   east         70   → east total 120
    3   north        40
    4   west         25

Examples 2–4 group these rows and $out the snapshot.

How It Works

1. Reset once. drop() clears old rows; insertMany loads four order lines.
2. Two fields matter. region is the group key; amount is summed.
3. find() confirms storage. You see the same rows the pipeline reads.
4. Reuse. Examples 2–4 assume this data is already in orders.

Example 2 — Basic $out

Goal: group sales by region from Example 1 and save the full result into sales_by_region.

db.orders.aggregate([
  {
    $group: {
      _id: "$region",
      total: { $sum: "$amount" }
    }
  },
  {
    $project: {
      _id: 0,
      region: "$_id",
      total: 1
    }
  },
  { $out: "sales_by_region" }
])

db.sales_by_region.find().sort({ region: 1 })

{ region: "east",  total: 120 }
{ region: "north", total: 40 }
{ region: "west",  total: 25 }
// aggregate() itself returns no cursor docs — read the target

How It Works

1. Example 1 orders. Four lines with east (50+70), north (40), west (25).
2. Group. Sum amount per region.
3. Project. Rename _id → region for a clean report shape.
4. $out last. Writes every result doc into sales_by_region; verify with find().

Example 3 — Re-run Replaces

Goal: run $out again on the same Example 1 orders data with a tighter filter—the whole target is replaced and old regions vanish.

// Filter to east + north only, then overwrite the snapshot
db.orders.aggregate([
  { $match: { region: { $in: ["east", "north"] } } },
  {
    $group: {
      _id: "$region",
      total: { $sum: "$amount" }
    }
  },
  {
    $project: {
      _id: 0,
      region: "$_id",
      total: 1
    }
  },
  { $out: "sales_by_region" }
])

db.sales_by_region.find().sort({ region: 1 })
// west is gone — full replace, not an upsert

{ region: "east",  total: 120 }
{ region: "north", total: 40 }
// previous west row removed by $out

How It Works

1. Same Example 1 rows. No re-insert; still four order documents.
2. $match first. Pipeline result has only east + north totals.
3. $out replaces. sales_by_region becomes exactly that result set.
4. west disappears. Unmatched old snapshot rows are not kept—use $merge to keep them.

Example 4 — Cross-Database

Goal: group the Example 1 orders and write the snapshot into another database (MongoDB 4.4+ syntax).

db.orders.aggregate([
  {
    $group: {
      _id: "$region",
      total: { $sum: "$amount" }
    }
  },
  {
    $project: {
      _id: 0,
      region: "$_id",
      total: 1
    }
  },
  {
    $out: {
      db: "analytics",
      coll: "sales_by_region"
    }
  }
])

db.getSiblingDB("analytics").sales_by_region.find()
// needs privileges on the analytics database

String form  → same database as the pipeline
{ db, coll } → another database (4.4+)
Still a full replace of the target collection
Still cannot out into the input collection

How It Works

1. Example 1 source. Reads the same four orders documents.
2. Same group/project. Region totals match Example 2’s pipeline shape.
3. Document form. db + coll pick the target database.
4. Inspect. getSiblingDB("analytics") then find() (needs write privileges).