$sample (aggregation)

Definition

  • $sample

New in version 3.2.

Randomly selects the specified number of documents from its input.

The $sample stage has the following syntax:

  1. { $sample: { size: <positive integer> } }

Behavior

$sample uses one of two methods to obtain N randomdocuments, depending on the size of the collection, the size of N,and $sample’s position in the pipeline.

If all the following conditions are met, $sample uses apseudo-random cursor to select 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 above conditions are NOT met, $sample performs acollection scan followed by a random sort to select N documents. Inthis case, the $sample stage is subject to thesort memory restrictions.

Warning

$sample may output the same document more than once inits result set. For more information, see Cursor Isolation.

Example

Given a collection named users with the following documents:

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

The following aggregation operation randomly selects 3 documents from thecollection:

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

The operation returns three random documents.