$sample (aggregation)

Definition

$sample

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

$sample stage syntax:

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

N is the number of documents to randomly select. Set N to an integer greater than or equal to 1.

Behavior

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. Random sorts are subject to the sort memory restrictions.

  Note

  Views are the result of aggregation pipelines. When you use $sample on a view, MongoDB appends the stage to the end of the view's aggregation pipeline syntax. Therefore, the $sample stage on a view is never the first stage and always results in a collection scan.

If you use $sample in a sharded cluster, each shard performs the sample operation independently. mongos samples the merged result of each shard's sample operation and returns the requested number of documents.

Examples

db.users.insertMany( [
   { _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  }
] )

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

var pipeline = new EmptyPipelineDefinition<Movie>()
    .Sample(5);