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

# $shardedDataDistribution (aggregation stage)

## Definition

**New in version 6.0.3**

Returns information on the distribution of data in sharded collections.

**Note:**

This aggregation stage is only available on [`mongos`.](https://www.mongodb.com/docs/manual/reference/program/mongos.md#std-program-mongos)

This aggregation stage must be run on the `admin` database.  The user must have the [`shardedDataDistribution`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-shardedDataDistribution) privilege action.

## Syntax

The `shardedDataDistribution` stage has the following syntax:

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

## Output Fields

The `$shardedDataDistribution` stage outputs an array of documents for each sharded collection in the database.  These documents contain the following fields:

| Field Name | Data Type | Description |
| --- | --- | --- |
| `ns` | string | Namespace of the sharded collection. |
| `shards` | array | Shards in the collection with the data distribution information for each shard. |
| `shards.numOrphanedDocs` | integer | Number of orphaned documents in the shard. For [time series collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), `numOrphanedDocs` contains the number of orphaned measurement buckets in the shard. |
| `shards.numOwnedDocuments` | integer | Number of documents owned by the shard. For [time series collections](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection), `numOwnedDocuments` contains the number of measurement buckets in the shard. |
| `shards.ownedSizeBytes` | integer | Size in bytes of documents owned by the shard when uncompressed. |
| `shards.orphanedSizeBytes` | integer | Size in bytes of orphaned documents in the shard when uncompressed. |

Starting in MongoDB 8.0, `$shardedDataDistribution` only returns output for a collection's [primary shard](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary-shard) if the primary shard has [chunks](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-chunk) or [orphaned documents.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-orphaned-document)

## Behavior

After an unclean shutdown of a [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) using the [Wired Tiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md) storage engine, size and count statistics reported by `$shardedDataDistribution` may be inaccurate.

The amount of drift depends on the number of insert, update, or delete operations performed between the last [checkpoint](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger-checkpoints) and the unclean shutdown. Checkpoints usually occur every 60 seconds. However, [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) instances running with non-default [`--syncdelay`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#std-option-mongod.--syncdelay) settings may have more or less frequent checkpoints.

Run [`validate`](https://www.mongodb.com/docs/manual/reference/command/validate.md#mongodb-dbcommand-dbcmd.validate) on each collection on the [`mongod`](https://www.mongodb.com/docs/manual/reference/program/mongod.md#mongodb-binary-bin.mongod) to restore statistics after an unclean shutdown.

After an unclean shutdown:

- [`validate`](https://www.mongodb.com/docs/manual/reference/command/validate.md#mongodb-dbcommand-dbcmd.validate) updates the [count statistic](https://www.mongodb.com/docs/manual/reference/operator/aggregation/collstats.md#std-label-collstat-count) in the [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) [output](https://www.mongodb.com/docs/manual/reference/command/collstats.md#std-label-collStats-output) with the latest value.

- Other statistics like the number of documents inserted or removed in the [`collStats`](https://www.mongodb.com/docs/manual/reference/command/collstats.md#mongodb-dbcommand-dbcmd.collStats) [output](https://www.mongodb.com/docs/manual/reference/command/collstats.md#std-label-collStats-output) are estimates.

## Examples

### MongoDB Shell

### Return All Sharded Data Distibution Metrics

To return all sharded data distribution metrics, run the following:

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

Example output:

```json
[
  {
    "ns": "test.names",
    "shards": [
      {
        "shardName": "shard-1",
        "numOrphanedDocs": 0,
        "numOwnedDocuments": 6,
        "ownedSizeBytes": 366,
        "orphanedSizeBytes": 0
      },
      {
        "shardName": "shard-2",
        "numOrphanedDocs": 0,
        "numOwnedDocuments": 6,
        "ownedSizeBytes": 366,
        "orphanedSizeBytes": 0
      }
    ]
  }
]
```

### Return Metrics for a Specific Shard

To return sharded data distribution metrics for a specific shard, run the following:

```javascript
db.aggregate([
   { $shardedDataDistribution: { } },
   { $match: {  "shards.shardName": "<name of the shard>" } }
])
```

### Return Metrics for a Namespace

To return sharded data distribution data for a namespace, run the following:

```javascript
db.aggregate([
   { $shardedDataDistribution: { } },
   { $match: {  "ns": "<database>.<collection>" } }
])
```

### Confirm No Orphaned Documents Remain

Starting in MongoDB 6.0.3, you can run an aggregation using the [`$shardedDataDistribution`](https://www.mongodb.com/docs/manual/reference/operator/aggregation/shardeddatadistribution.md#mongodb-pipeline-pipe.-shardedDataDistribution) stage to confirm no orphaned documents remain:

```javascript
db.aggregate([
   { $shardedDataDistribution: { } },
   { $match: { "ns": "<database>.<collection>" } }
])
```

`$shardedDataDistribution` has output similar to the following:

```json
[
  {
    "ns": "test.names",
    "shards": [
      {
        "shardName": "shard-1",
        "numOrphanedDocs": 0,
        "numOwnedDocuments": 6,
        "ownedSizeBytes": 366,
        "orphanedSizeBytes": 0
      },
      {
        "shardName": "shard-2",
        "numOrphanedDocs": 0,
        "numOwnedDocuments": 6,
        "ownedSizeBytes": 366,
        "orphanedSizeBytes": 0
      }
    ]
  }
]
```

Ensure that `"numOrphanedDocs"` is `0` for each shard in the cluster.