Docs Menu

$sample (aggregation)

On this page

  • Definition
  • Behavior
  • Example
$sample

New in version 3.2.

Randomly selects the specified number of documents from the input documents.

The $sample stage has the following syntax:

{ $sample: { size: <positive integer N> } }

N is the number of documents to randomly select.

If all of the following conditions are true, $sample uses a pseudo-random cursor to select the N documents:

  • $sample is the first stage of the pipeline.
  • N is less than 5% of the total documents in the collection.
  • The collection contains more than 100 documents.

If any of the previous conditions are false, $sample:

  • Reads all documents that are output from a preceding aggregation stage or a collection scan.
  • Performs a random sort to select N documents.
Note

Random sorts are subject to the sort memory restrictions.

If you are using the:

  • MMAPv1 storage engine, $sample may return the same document more than once in the result set.
  • WiredTiger or in-memory storage engine, $sample does not return duplicate documents. WiredTiger is the default storage engine as of MongoDB 3.2.

Given a collection named users with the following documents:

{ "_id" : 1, "name" : "dave123", "q1" : true, "q2" : true }
{ "_id" : 2, "name" : "dave2", "q1" : false, "q2" : false }
{ "_id" : 3, "name" : "ahn", "q1" : true, "q2" : true }
{ "_id" : 4, "name" : "li", "q1" : true, "q2" : false }
{ "_id" : 5, "name" : "annT", "q1" : false, "q2" : true }
{ "_id" : 6, "name" : "li", "q1" : true, "q2" : true }
{ "_id" : 7, "name" : "ty", "q1" : false, "q2" : true }

The following aggregation operation randomly selects 3 documents from the collection:

db.users.aggregate(
[ { $sample: { size: 3 } } ]
)

The operation returns three random documents.

Tip
See also:
Give Feedback
MongoDB logo
© 2021 MongoDB, Inc.

About

  • Careers
  • Legal Notices
  • Privacy Notices
  • Security Information
  • Trust Center
© 2021 MongoDB, Inc.