Docs Menu

Docs HomeMongoDB Manual

$shardedDataDistribution (aggregation)

On this page

  • Definition
  • Syntax
  • Output Fields
  • Examples
  • Return All Sharded Data Distibution Metrics
  • Return Metrics for a Specific Shard
  • Return Metrics for a Namespace
  • Confirm No Orphaned Documents Remain
$shardedDataDistribution

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.

This aggregation stage must be run on the admin database. The user must have the shardedDataDistribution privilege action.

The shardedDataDistribution stage has the following syntax:

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

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.
shards.numOwnedDocuments
integer
Number of documents owned by the shard.
shards.ownedSizeBytes
integer
Storage in bytes for documents owned by the shard.
shards.orphanedSizeBytes
integer
Storage in bytes for orphaned documents in the shard.

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

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

Example output:

[
{
"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
}
]
}
]

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

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

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

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

Starting in MongoDB 6.0.3, you can run an aggregation using the $shardedDataDistribution stage to confirm no orphaned documents remain:

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

$shardedDataDistribution has output similar to the following:

[
{
"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.

←  $setWindowFields (aggregation)$skip (aggregation) →