/ /

/ /

$sample (aggregation stage)

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.
Note
You can't configure the threshold that $sample uses to determine when to scan the entire collection. The thresholds is 5%. If the size is greater than 5% of the total number of documents in the collection, $sample performs a top-k sort by a generated random value. The top-k sort could spill to disk if the sample documents are larger than 100MB.
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

This section shows an aggregation pipeline example that uses the following users collection:

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  }
] )

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

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

The operation returns three random documents.

Tip

$rand (aggregation)

To use the MongoDB .NET/C# driver to add a $sample stage to an aggregation pipeline, call the Sample() method on a PipelineDefinition object.

The following example creates a pipeline stage that returns five random documents from the input collection:

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

To use the MongoDB Node.js driver to add a $sample stage to an aggregation pipeline, use the $sample operator in a pipeline object.

The following example creates a pipeline stage that returns five random documents from the input collection. The example then runs the aggregation pipeline:

const pipeline = [{ $sample: { size: 5 } }];
const cursor = collection.aggregate(pipeline);
return cursor;

Back

$replaceWith

$score

Definition

Behavior

Note

Note

Examples

Tip