Database Manual / Reference / Query Language / Aggregation Stages

$listClusterCatalog

Definition

$listClusterCatalog

New in version 8.1.

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

{
  $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:

{
    "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, `view` for views, and `timeseries` for time series collection.
`idIndex`	document	true	Provides information on the `_id` index for the collection. Identical to the returned `idIndex` field in `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()`. For more information, see 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. 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 of the collection.
`shards`	array of strings	false, must specify shards in input document	Shards per collection.
`balancingEnabled`	boolean	false, must specify balancingConfiguration in input document	Specifies if the balancing is enabled for that collection. This field is only present if the collection is sharded.
`balancingEnabledReason`	document	false, must specify balancingConfiguration in input document	Returns information on which command has been used to toggle balancing. This document has the following fields: `enableBalancing`: `true` if `configureCollectionBalancing` was used to toggle balancing `allowMigrations`: `true` if `setAllowMigrations` was used to toggle balancing This field is only present if the collection is sharded.
`autoMergingEnabled`	boolean	false, must specify balancingConfiguration in input document	Specifies if the AutoMerger is enabled for the collection. This field is only present if the collection is sharded.
`chunkSize`	int	false, must specify balancingConfiguration in input document	Returns the chunk size, in MiB, 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 privilege action, which is included in the clusterMonitor role.

To run this command against a specific database, you need the listCollections privilege action, which is included in the read role.

Examples

List Information from All Collections

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

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:

[
  {
    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:

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:

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

The Node.js examples on this page use the sample_mflix database from the Atlas sample datasets. To learn how to create a free MongoDB Atlas cluster and load the sample datasets, see Get Started in the MongoDB Node.js driver documentation.

To use the MongoDB Node.js driver to add a $listClusterCatalog stage to an aggregation pipeline, include the $listClusterCatalog operator in a pipeline object.

List Information from All Collections in a Database

The following example creates a pipeline stage that returns information for all collections in the sample_mflix database. The example then runs the pipeline:

const pipeline = [{ $listClusterCatalog: {} }];

const db = client.db("sample_mflix");

const cursor = db.aggregate(pipeline);
return cursor;

List Information from All Collections in a Cluster

The following example creates a pipeline stage that returns information for all collections in a cluster. The example then runs the pipeline:

const pipeline = [{ $listClusterCatalog: {} }];

const adminDB = client.db("admin");

const cursor = adminDB.aggregate(pipeline);
return cursor;

Balancing Configuration

The following example creates a pipeline that includes balancing information in the return documents for all collections in the sample_mflix database. The example then runs the pipeline:

const db = client.db("sample_mflix");

const pipeline = [{ $listClusterCatalog: {balancingConfiguration: true} }];

const cursor = db.aggregate(pipeline);
return cursor;

Back

$limit

$listLocalSessions