MongoDB $sampleRate Operator

What You’ll Learn

The $sampleRate operator randomly returns true or false for each document at a given probability. Use it in $match with $expr to keep a random percentage of records — ideal for testing, spot checks, and large-scale analytics on a subset.

Definition and Usage

In MongoDB’s aggregation framework, the $sampleRate operator evaluates to true with a probability equal to the given rate, and false otherwise. For example, { $sampleRate: 0.25 } includes each document roughly 25% of the time.

Unlike the $sample pipeline stage (which picks an exact number of documents), $sampleRate gives you percentage-based sampling. The final count varies slightly run to run, but the average matches your rate over large collections.

📝 Syntax

The $sampleRate operator takes a single numeric rate between 0 and 1:

{ $sampleRate: <rate> }

Typical Usage in $match

db.collection.aggregate([
  {
    $match: {
      $expr: {
        $sampleRate: 0.1
      }
    }
  }
])

Syntax Rules

• rate — a number from 0.0 to 1.0 (inclusive).
• 0.0 — no documents return true.
• 1.0 — every document returns true.
• Returns a boolean per document — use inside $expr in $match.
• Also usable in $project or $addFields to add a random inclusion flag.
• Available in MongoDB 4.4+ aggregation expressions.

Examples Gallery

Sample event logs, combine sampling with filters, add inclusion flags, and compare rates with $sampleRate.

[
  { "_id": 1, "userId": "u1", "action": "click", "status": "ok" },
  { "_id": 2, "userId": "u2", "action": "view", "status": "ok" },
  { "_id": 3, "userId": "u3", "action": "click", "status": "error" },
  { "_id": 4, "userId": "u4", "action": "purchase", "status": "ok" },
  { "_id": 5, "userId": "u5", "action": "click", "status": "ok" }
  // ... thousands more documents
]

db.events.aggregate([
  {
    $match: {
      $expr: {
        $sampleRate: 0.1
      }
    }
  },
  {
    $project: {
      userId: 1,
      action: 1,
      status: 1
    }
  }
])

// On 5 docs, you might get 0–2 results (random each run).
// On 10,000 docs, expect roughly ~1,000 documents.
// Exact count varies; average ≈ rate × total.

db.events.aggregate([
  {
    $match: {
      status: "error",
      $expr: {
        $sampleRate: 0.2
      }
    }
  }
])

// Only "error" documents are considered;
// ~20% of those pass the random filter.

db.events.aggregate([
  {
    $addFields: {
      inExperiment: {
        $sampleRate: 0.5
      }
    }
  },
  {
    $match: {
      inExperiment: true
    }
  }
])

// ~50% of documents get inExperiment: true

db.orders.aggregate([
  {
    $match: {
      $expr: {
        $sampleRate: 0.01
      }
    }
  },
  {
    $limit: 50
  },
  {
    $project: {
      orderId: 1,
      total: 1,
      createdAt: 1
    }
  }
])

// ~1% sample, capped at 50 docs for review

// Using $sampleRate (simpler)
{ $match: { $expr: { $sampleRate: 0.25 } } }

// Using $rand (more flexible)
{
  $match: {
    $expr: {
      $lt: [ { $rand: {} }, 0.25 ]
    }
  }
}

// Both keep roughly 25% of documents

🚀 Use Cases

• Development and QA — inspect a random slice of production-like data without full exports.
• Performance testing — run expensive pipelines on a fraction of documents.
• A/B experiments — randomly assign documents to treatment groups at a set rate.
• Approximate analytics — estimate metrics on large collections when exact counts are unnecessary.

💡 Best Practices