MongoDB $sampleRate Operator

What Is $sampleRate?

$sampleRate is a MongoDB aggregation expression that randomly keeps documents at a given probability. Pass a rate from 0 to 1 (for example 0.33 ≈ one in three). Use it inside $match.

$sampleRate = keep ~rate × 100% of docs

{ $match: { $sampleRate: 0.33 } }

rate  → 0 … 1 (inclusive)
0     → keep none
1     → keep all
0.1   → keep ~10%

same idea as:
  $lt: [ { $rand: {} }, 0.33 ]

exact count → use $sample stage

How to Use $sampleRate in MongoDB

Pick a rate, put it in $match, then continue the pipeline on the kept docs.

1. Choose a rate between 0 and 1 (for example 0.2 for ~20%).
2. Add { $match: { $sampleRate: <rate> } } early in the pipeline.
3. Optionally $count or project the kept documents.
4. If you need an exact size instead, switch to the $sample stage.

Pseudocode

rate = 0.33   // keep about 1 in 3

for each document:
    // same idea as: random() < rate
    if coin_flip(probability = rate):
        keep document
    else:
        skip

// next run can keep a different set

Cheat Sheet

Keep these facts handy while sampling documents.

Live Preview

Simulate $sampleRate over a small set of documents. Click again — the kept count will change.

rate = 0.33 on 6 docs
expected ≈ 2 kept

(click Run for a new draw)

Worked Walkthrough — Keep ~33% of Events

Six event logs enter the pipeline. With rate 0.33, each event has about a one-in-three chance of surviving $match.

Documents: E1 … E6  (6 total)
rate = 0.33

For each event:
  keep with probability 0.33

Example run (yours will differ):
  E1 keep · E2 skip · E3 keep · E4 skip · E5 skip · E6 skip
  → 2 kept  (expected ≈ 6 × 0.33 ≈ 2)

Small sets vary a lot; large sets stay closer to the rate.

MongoDB Examples

We use six events. First insert them, then keep about one third with $sampleRate, then count how many survived. Run these in mongosh. Kept sets differ each run.

db.events.insertMany([
  { _id: 1, type: "login" },
  { _id: 2, type: "click" },
  { _id: 3, type: "purchase" },
  { _id: 4, type: "click" },
  { _id: 5, type: "logout" },
  { _id: 6, type: "click" }
]);

db.events.find()

[
  { _id: 1, type: "login" },
  { _id: 2, type: "click" },
  { _id: 3, type: "purchase" },
  { _id: 4, type: "click" },
  { _id: 5, type: "logout" },
  { _id: 6, type: "click" }
]

6 events enter the pipeline

  login · click · purchase · click · logout · click

$sampleRate: 0.33  →  keep ~2 of them
(exact ids change every run)

db.events.aggregate([
  {
    $match: {
      $sampleRate: 0.33
    }
  }
]);

[
  { _id: 1, type: "login" },
  { _id: 4, type: "click" }
]

// Sometimes 0–6 docs.
// Average keep rate ≈ 33%.

db.events.aggregate([
  { $match: { $sampleRate: 0.33 } },
  { $count: "numMatches" }
]);

{ "numMatches": 2 }

// Other runs might show 1, 3, or even 0.
// Over many runs, average ≈ 6 × 0.33 ≈ 2.

Performance Notes

A coin flip is cheap, but the stage still sees every input document. Prefer $sample when you only need a small fixed-size random subset from a huge collection.

Key Takeaways