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

# $listClusterCatalog

## Definition

**New in version 8.0.10**

**Warning:**

The `$listClusterCatalog` aggregation stage is unsupported and is not guaranteed to be stable in a future release. Don't build functionality that relies on a specific output format of this stage, since the output may change in a future release.

The `$listClusterCatalog` aggregation stage outputs information for collections in a cluster, including names and creation options.

`$listClusterCatalog` must be the first stage in the pipeline.

You must call this stage against a database. When you run this stage against the [admin database](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-admin-database), it returns information about all collections in the cluster. When you run it against any other database, it returns information about all collections within that database.

## Syntax

The stage has the following syntax:

```javascript
{
  $listClusterCatalog: {
     shards: true,
     balancingConfiguration: true
  }
}
```

The `$listClusterCatalog` stage takes a document with the following optional fields:

| Field | Description |
| --- | --- |
| `shards` | Optional. You can specify `shards: true` when you call `$listClusterCatalog` so that the stage includes a list of shards in its return document. |
| `balancingConfiguration` | Optional. If you specify `balancingConfiguration: true` when you call `$listClusterCatalog`, the stage includes the `balancingEnabled`, `balancingEnabledReason`, `autoMergingEnabled`, and `chunkSize` fields in its return object. |

## Output

`$listClusterCatalog` returns a document per collection. Each document can contain the following fields:

```javascript
{
    "ns" : <string>,
    "db" : <string>,
    "type" : <string>,
    "idIndex" : <document>,
    "options" : <document>,
    "info" : <document>,
    "sharded" : <boolean>,
    "shardKey" : <document>,
    "shards" : [<string>],
    "balancingEnabled" : <boolean>,
    "balancingEnabledReason" : <document>,
    "autoMergingEnabled" : <boolean>,
    "chunkSize" : <int>
 }
```

The following table contains information about the fields that `$listClusterCatalog` returns:

| Field | Type | Returned with default query | Description |
| --- | --- | --- | --- |
| `ns` | string | true | The full namespace of the collection, in the format `"<dbName>.<collectionName>"`. |
| `db` | string | true | Name of the database where the collection is located. |
| `type` | string | true | Type of data store. Returns `collection` for [collections](https://www.mongodb.com/docs/manual/core/databases-and-collections/#collections), `view` for [views](https://www.mongodb.com/docs/manual/core/views/), and `timeseries` for [time series collection.](https://www.mongodb.com/docs/manual/core/timeseries-collections.md#std-label-manual-timeseries-collection) |
| `idIndex` | document | true | Provides information on the `_id` index for the collection. Identical to the returned `idIndex` field in [`listCollections`](https://www.mongodb.com/docs/manual/reference/command/listcollections.md#mongodb-dbcommand-dbcmd.listCollections). This field is not present for views or time series collections. |
| `options` | document | true | The returned document contains the following fields: `viewOn`: document. The name of the source collection or view from which to create a view. Only present on views.; `pipeline`: array of documents. Consists of the aggregation pipeline stages. Only present on views.; `validator`: document. Returns the validator rules or expressions.; `timeseries`: document. Returns timeseries options. Only present on timeseries buckets and timeseries views.; `clusteredIndex`: array of documents. Represents the clustered indexes. These options correspond directly to the options available in [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createcollection.md#mongodb-method-db.createCollection). For more information, see [Syntax.](https://www.mongodb.com/docs/manual/reference/method/db.createcollection.md#std-label-db-create-collection-syntax) |
| `info` | document | true | Lists the following fields related to the collection: `readOnly`: `boolean`. If `true` the data store is read only. Always `true` for views.; `uuid`: UUID (Universally unique identifier). Once established, the collection UUID does not change. The collection UUID remains the same across replica set members and shards in a sharded cluster. This field is not present for views or timeseries views. |
| `sharded` | boolean | true | Specifies whether the collection is sharded or unsharded. This field is also present on replica set servers. |
| `shardKey` | document | only present if collection is sharded | The [shard key](https://www.mongodb.com/docs/manual/core/sharding-shard-key.md#std-label-shard-key) of the collection. |
| `shards` | array of strings | false, must specify [shards](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listclustercatalog.md#std-label-list-cluster-catalog-shards) in input document | Shards per collection. |
| `balancingEnabled` | boolean | false, must specify [balancingConfiguration](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listclustercatalog.md#std-label-list-cluster-catalog-balance-config) in input document | Specifies if the [balancing](https://www.mongodb.com/docs/manual/core/sharding-balancer-administration.md#std-label-sharding-balancing) is enabled for that collection. This field is only present if the collection is sharded. |
| `balancingEnabledReason` | document | false, must specify [balancingConfiguration](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listclustercatalog.md#std-label-list-cluster-catalog-balance-config) in input document | Returns information on which command has been used to toggle balancing. This document has the following fields: `enableBalancing`: `true` if [`configureCollectionBalancing`](https://www.mongodb.com/docs/manual/reference/command/configurecollectionbalancing.md#mongodb-dbcommand-dbcmd.configureCollectionBalancing) was used to toggle balancing; `allowMigrations`: `true` if [`setAllowMigrations`](https://www.mongodb.com/docs/manual/reference/command/setallowmigrations.md#mongodb-dbcommand-dbcmd.setAllowMigrations) was used to toggle balancing This field is only present if the collection is sharded. |
| `autoMergingEnabled` | boolean | false, must specify [balancingConfiguration](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listclustercatalog.md#std-label-list-cluster-catalog-balance-config) in input document | Specifies if the [AutoMerger](https://www.mongodb.com/docs/manual/core/automerger-concept.md#std-label-automerger-concept) is enabled for the collection. This field is only present if the collection is sharded. |
| `chunkSize` | int | false, must specify [balancingConfiguration](https://www.mongodb.com/docs/manual/reference/operator/aggregation/listclustercatalog.md#std-label-list-cluster-catalog-balance-config) in input document | Returns the [chunk](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-chunk) size, in MiB (mebibytes), of the collection. This field is only present if the collection is sharded. |

## Restrictions

If you execute this command against the `admin` database, you need the [`listClusterCatalog`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listClusterCatalog) privilege action, which is included in the [`clusterMonitor`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-clusterMonitor) role.

To run this command against a specific database, you need the [`listCollections`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listCollections) privilege action, which is included in the [`read`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-read) role.

## Examples

### MongoDB Shell

### List Information from All Collections

The following example returns default information from all collections in the `sample_mflix` database:

```bash
use sample_mflix

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

When you run this example, it returns an array containing a document for each collection in the `sample_mflix` database. Each of these documents contains the default fields described in the preceding table:

```json
[
  {
    ns: "sample_mflix.movies",
    db: "sample_mflix",
    type: "collection",
    idIndex: { v: 2, key: { _id: 1 }, name: '_id' },
    options: { ... },
    sharded: false,
    info: {
        readOnly: false,
        uuid: new UUID("6c46c8b9-4999-4213-bcef-9a36b0cff228")
    }
  },
  {
    ns: "sample_mflix.comments",
    db: "sample_mflix",
    type: "collection",
    options: { ... },
    sharded: true,
    info: {
        readOnly: true,
        uuid: new UUID("6c448eb9-4090-4213-bbaf-9a36bb7fc98e")
    }
    shardKey: { _id: 1}
  },
  ...
]
```

### Balancing Configuration

You can return the default fields and information about the balancing configuration for all collections in a database with sharded collections.

The following example returns balancing configurations for the `sample_mflix` database:

```bash
use sample_mflix

db.aggregate([
  {
    $listClusterCatalog: {
      balancingConfiguration: true
    }
  }
])
```

The preceding example returns an array containing a document for each collection. Each of these documents contains the default fields along with the `balancingEnabled`, `balancingEnabledReason`, `autoMergingEnabled`, and `chunkSize` fields for sharded collections. The following code provides an example of this output:

```json
[
  {
    ns: "sample_mflix.movies",
    db: "sample_mflix",
    type: "collection",
    idIndex: { v: 2, key: { _id: 1 }, name: '_id' },
    options: { ... },
    sharded: false,
    ...
  },
  {
    ns: "sample_mflix.comments",
    db: "sample_mflix",
    type: "collection",
    sharded: true,
    shardKey: { _id: 1},
    balancingEnabled: true,
    balancingEnabledReason: {
      enableBalancing: true,
      allowMigrations: false
    },
    autoMergingEnabled: false,
    chunkSize: 256,
    ...
  },
  ...
]
```