> 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, nodejs
-->

# $listSampledQueries (aggregation stage)

## Definition

Returns sampled queries for all collections or a specific collection. Sampled queries are used by the `analyzeShardKey` command to calculate metrics about the read and write distribution of a shard key.

## Syntax

`$listSampledQueries` has this syntax:

```javascript
{
   $listSampledQueries: { namespace: <namespace> }
}
```

## Behavior

- To list sampled queries for a single collection, specify the collection in the `namespace` argument.

- To list sampled queries for all collections, omit the `namespace` argument.

## Access Control

`$listSampledQueries` requires the [`clusterMonitor`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-clusterMonitor) role on the cluster.

## Limitations

- You cannot use `$listSampledQueries` on Atlas [multi-tenant](https://www.mongodb.com/docs/atlas/build-multi-tenant-arch/) configurations.

- You cannot use `$listSampledQueries` on standalone deployments.

- You cannot use `$listSampledQueries` directly against a [`--shardsvr`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--shardsvr) replica set. When running on a sharded cluster, `$listSampledQueries` must run against a `mongos`.

## Examples

### MongoDB Shell

### List Sampled Queries for All Collections

The following aggregation operation lists all sampled queries for all collections in the replica set:

```javascript
db.aggregate( [  { $listSampledQueries: {  } } ] )
```

### List Sampled Queries for A Specific Collection

The following aggregation operation lists all sampled queries for a `post` collection in the `social` database:

```javascript
db.aggregate( [  { $listSampledQueries: { namespace: "social.post" } } ] )
```

## Output

The output fields differ for read and write queries.

### Read Queries

```none
{
   _id: <uuid>,
   ns: "<database>.<collection>",
   collectionUuid: <collUUID>,
   cmdName: <find|aggregate|count|distinct>,
   cmd: {
     filter: <object>,
     collation: <object>,
     let: <object>
   },
   expireAt: <date>
}
```

| Field Name | Type | Description |
| --- | --- | --- |
| `_id` | UUID | Sample ID for the query. |
| `ns` | string | Namespace of the sampled collection. |
| `collectionUuid` | UUID | ID of the sampled collection. |
| `cmdName` | string | Name of the sampled command. Can be one of: `"find"`; `"aggregate"`; `"count"`; `"distinct"` |
| `cmd.filter` | object | Filter the command ran with, if applicable. |
| `cmd.collation` | object | Collation the command ran with, if applicable. |
| `cmd.let` | object | Custom variables the command ran with, if applicable. |
| `expireAt` | date | Date that the sample expires. |

### Write Queries

```none
{
   _id: <uuid>,
   ns: "<database>.<collection>",
   collectionUuid: <collUUID>,
   cmdName: <update|delete|findAndModify>,
   cmd: <object>,
   expireAt: <date>
}
```

| Field Name | Type | Description |
| --- | --- | --- |
| `_id` | UUID | Sample ID for the query. |
| `ns` | string | Namespace of the sampled collection. |
| `collectionUuid` | UUID | ID of the sampled collection. |
| `cmdName` | string | Name of the sampled command. Can be one of: `"update"`; `"delete"`; `"findAndModify"` |
| `cmd` | object | Command object |
| `expireAt` | date | Date that the sample expires. |