Database Manual / Reference / Query Language / Aggregation Stages

$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.N是随机选择的文档数量。将N设置为大于或等于1的整数。

Behavior行为

If all of the following conditions are true, $sample uses a pseudo-random cursor to select the N documents:如果以下所有条件都为真，$sample将使用伪随机游标选择N个文档：

  • $sample is the first stage of the pipeline.这是管道的第一阶段。

  • N is less than 5% of the total documents in the collection.N小于集合中文档总数的5%。

    Note

    You can't configure the threshold that $sample uses to determine when to scan the entire collection. 您无法配置$sample用于确定何时扫描整个集合的阈值。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. 阈值为5%。如果大小大于集合中文档总数的5%，$sample将根据生成的随机值执行top-k排序。The top-k sort could spill to disk if the sample documents are larger than 100MB.如果示例文档大于100MB，则top-k排序可能会溢出到磁盘。

  • The collection contains more than 100 documents.该集合包含100多份文件。

If any of the previous conditions are false, $sample:如果前面的任何条件为假，则$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.执行随机排序以选择N个文档。随机排序受排序内存限制。

    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. 视图是聚合管道的结果。当您在视图上使用$sample时，MongoDB会将阶段附加到视图聚合管道语法的末尾。Therefore, the $sample stage on a view is never the first stage and always results in a collection scan.因此，视图上的$sample阶段从来不是第一阶段，并且总是导致集合扫描。

If you use $sample in a sharded cluster, each shard performs the sample operation independently. 如果在分片集群中使用$sample，则每个分片都独立执行示例操作。mongos samples the merged result of each shard's sample operation and returns the requested number of documents.mongos对每个分片示例操作的合并结果进行采样，并返回所请求的文档数量。

Examples示例

MongoDB Shell

This section shows an aggregation pipeline example that uses the following users collection:本节显示了一个使用以下users集合的聚合管道示例：

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:以下聚合操作从集合中随机选择3个文档：

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

The operation returns three random documents.该操作返回三个随机文档。

Tip

$rand (aggregation)

C#

To use the MongoDB .NET/C# driver to add a $sample stage to an aggregation pipeline, call the Sample() method on a PipelineDefinition object.要使用MongoDB .NET/C#驱动程序向聚合管道添加$sample阶段，请在PipelineDefinition对象上调用Sample()方法。

The following example creates a pipeline stage that returns five random documents from the input collection:以下示例创建了一个管道阶段，该阶段从输入集合中返回五个随机文档：

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

To use the MongoDB Node.js driver to add a $sample stage to an aggregation pipeline, use the $sample operator in a pipeline object.要使用MongoDB Node.js驱动程序向聚合管道添加$sample阶段，请在管道对象中使用$sample运算符。

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;