> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: shell, csharp, nodejs
-->

# $sample (aggregation stage)

## Definition

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

[`$sample`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-sample) stage syntax:

```javascript
{ $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

### Pseudo-Random Cursor Behavior

If all of the following conditions are true, [`$sample`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-sample) uses a pseudo-random cursor to select the `N` documents:

- [`$sample`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-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`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-sample) uses to determine when to scan the entire collection. The threshold is 5%. If the size is greater than 5% of the total number of documents in the collection, [`$sample`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-sample) performs a [top-k](https://www.mongodb.com/docs/manual/reference/method/cursor.sort.md#std-label-sort-limit-results) 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.

The pseudo-random cursor doesn't guarantee a uniform random sample. It selects documents by descending the collection's internal B-tree structure at random, so the results can skew toward some parts of the collection. Skew is more likely when:

- The documents in the collection aren't uniformly distributed, which leads to an unbalanced tree structure.

- The collection has a high number of deleted documents.

- A high number of documents aren't visible to the cursor's transaction.

If your use case requires a uniform sample, avoid the pseudo-random cursor. To do so, run [`$sample`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-sample) after another stage, or set `N` to more than 5% of the documents in the collection.

### Random Sort Behavior

If any of the previous conditions are false, [`$sample`:](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sample.md#mongodb-pipeline-pipe.-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.](https://www.mongodb.com/docs/manual/reference/operator/aggregation/sort.md#std-label-sort-memory-limit)

  **Note:**

  [Views](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) 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.

### Sharded Clusters

If you use `$sample` in a [sharded cluster](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-sharded-cluster), each shard performs the sample operation independently. [`mongos`](https://www.mongodb.com/docs/manual/reference/program/mongos.md#mongodb-binary-bin.mongos) samples the merged result of each shard's sample operation and returns the requested number of documents.

## Examples

### MongoDB Shell

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

```javascript
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:

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

The operation returns three random documents.

**See also:**

[`$rand (aggregation)`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/rand.md#mongodb-expression-exp.-rand)