/ /

/ /

listShards (database command)

Definition

listShards: The listShards command returns a list of the configured shards in a sharded cluster. listShards is only available on mongos instances and must be issued against the admin database.

Compatibility

This command is available in deployments hosted in the following environments:

MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The command has the following syntax:

db.runCommand(
  {
    listShards: 1
  }
)

Command Fields

The command takes the following fields:

Field	Type	Description
`listShards`	integer	`1` requests a list of configured shards.
`filter`	document	Specifies a filter for the shards in return documents. New in version 8.3.
`filter.draining`	boolean	Filters return documents based on whether the shards are draining. When set to `true`, the command returns an array the shards being drained by the balancer. When set to `false`, the command returns an array of all shards not being drained by the balancer. When unset, the command returns all shards, regardless of their draining status. New in version 8.3.

Output Fields

listShards returns a document that includes:

A shards field which contains an array of documents, each describing one shard. Each document may contain the following fields:

Field	Description
`_id`	Name of the shard.
`host`	Hostname of the shard. If the shard is a replica set, `host` lists the hostname of each mongod instance in the replica set.
`draining`	If `true`, indicates that the `startShardDraining` or the `removeShard` commands have been called for this shard and it's in the process of being drained.
`tags`	List of zones to which the shard belongs.
`state`	Internal field used during the addShard (database command) sequence to ensure that all steps and configuration necessary to add the shard to the cluster are completed.

The ok status field, the operationTime field, and the $clusterTime field for the operation. For details on these fields, see Response.

Example

The following operation runs listShards against the mongos admin database:

db.adminCommand({ listShards: 1 })

The following document is an example of the output from a listShards command:

{
  "shards": [
    {
      "_id": "shard01",
      "host": "shard01/host1:27018,host2:27018,host3:27018",
      "state": 1
    },
    {
      "_id": "shard02",
      "host": "shard02/host4:27018,host5:27018,host6:27018",
      "tags": [ "NYC" ],
      "state": 1
    },
    {
      "_id": "shard03",
      "host": "shard03/host7:27018,host8:27018,host9:27018",
      "state": 1
    }
  ],
  "ok": 1,
  "$clusterTime" : {
     "clusterTime" : Timestamp(1510716515, 1),
     "signature" : {
        "hash" : BinData(0,"B2ViX7XLzFLS5Fl9XEuFXbwKIM4="),
        "keyId" : Long("6488045157173166092")
     }
  },
  "operationTime" : Timestamp(1510716515, 1)
}

Back

isdbgrid

mergeAllChunksOnShard