> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# listCollections (database command)

## Definition

Retrieves information, including the names and creation options, for the collections and [views](https://www.mongodb.com/docs/manual/core/views.md#std-label-views-landing-page) in a database.

The `listCollections` command returns an unsorted list of all collections and views in the database. Use the returned document to create a [cursor](https://www.mongodb.com/docs/manual/reference/method.md#std-label-doc-cursor-methods) on the collection.

[`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) provides the [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) and the [`db.getCollectionNames()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionNames.md#mongodb-method-db.getCollectionNames) helper methods, as well as the [show collections](https://www.mongodb.com/docs/mongodb-shell/reference/access-mdb-shell-help.md#std-label-mongosh-show-collections) command.

## Compatibility

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

- [MongoDB Atlas](https://www.mongodb.com/docs/atlas): The fully managed service for MongoDB deployments in the cloud

**Note:**

This command is supported in all MongoDB Atlas clusters. For information on Atlas support for all commands, see [Unsupported Commands.](https://www.mongodb.com/docs/atlas/unsupported-commands/)

- [MongoDB Enterprise](https://www.mongodb.com/docs/manual/administration/install-enterprise.md#std-label-install-mdb-enterprise): The subscription-based, self-managed version of MongoDB

- [MongoDB Community](https://www.mongodb.com/docs/manual/administration/install-community.md#std-label-install-mdb-community-edition): The source-available, free-to-use, and self-managed version of MongoDB

## Syntax

The command has the following syntax:

```javascript
db.runCommand(
   {
     listCollections: 1,
     filter: <document>,
     nameOnly: <boolean>,
     authorizedCollections: <boolean>,
     comment: <any>
   }
)
```

## Command Fields

The command can take the following optional fields:

| Field | Type | Description |
| --- | --- | --- |
| `filter` | document | Optional. A query predicate to filter the list of collections. You can specify a query predicate on any of the [fields returned](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#std-label-list-collection-output) by [`listCollections`.](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#mongodb-dbcommand-dbcmd.listCollections) |
| `nameOnly` | boolean | Optional. A flag to indicate whether the command returns just the name and type (`view`, `collection`, or `timeseries`) or returns both the name and other information. The default value is `false`. When `nameOnly` is `true`, your `filter` expression can only filter based on a collection's name and type. No other fields are available. |
| `authorizedCollections` | boolean | Optional. A flag that, when set to `true` and used with `nameOnly: true`, allows a user without the required privilege (that is, [`listCollections`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listCollections) action on the database) to run the command when access control is enforced. When both `authorizedCollections` and `nameOnly` options are set to true, the command returns only those collections for which the user has privileges. For example, if a user has [`find`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-find) action on specific collections, the command returns only those collections. If a user has [`find`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-find) or any other action on the database resource, the command lists all collections in the database. The default value is `false`. That is, the user must have [`listCollections`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listCollections) action on the database to run the command. For users who have [`listCollections`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listCollections) action on the database, this option has no effect. When used without `nameOnly: true`, this option has no effect. The user must have the required privileges to run the command when access control is enforced. Otherwise, the user is unauthorized to run the command. |
| `comment` | any | Optional. A user-provided comment to attach to this command. Once set, this comment appears alongside records of this command in the following locations: [mongod log messages](https://www.mongodb.com/docs/manual/reference/log-messages.md#std-label-log-messages-ref), in the `attr.command.cursor.comment` field.; [Database profiler](https://www.mongodb.com/docs/manual/reference/database-profiler.md#std-label-profiler) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/database-profiler.md#mongodb-data-system.profile.command) field.; [`currentOp`](https://www.mongodb.com/docs/manual/reference/command/currentOp.md#mongodb-dbcommand-dbcmd.currentOp) output, in the [`command.comment`](https://www.mongodb.com/docs/manual/reference/command/currentOp.md#mongodb-data-currentOp.command) field. A comment can be any valid [BSON type](https://www.mongodb.com/docs/manual/reference/bson-types.md#std-label-bson-types) (string, integer, object, array, etc). Any comment set on a `listCollections` command is inherited by any subsequent [`getMore`](https://www.mongodb.com/docs/manual/reference/command/getMore.md#mongodb-dbcommand-dbcmd.getMore) commands run on the `listCollections` cursor. |

## Behavior

### Filter

Use a filter to limit the results of `listCollections`. Specify a `filter` on any of the [fields returned](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#std-label-list-collection-output) in the `listCollections` result set.

### Locks

`listCollections` lock behavior:

- Earlier than MongoDB 5.0, `listCollections` takes an [intent shared lock](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-intent-lock) on each collection in the database when `listCollections` holds an intent shared lock on the database.

- Starting in MongoDB 5.0, `listCollections` doesn't take an intent shared lock on a collection or database. `listCollections` isn't blocked by operations holding an exclusive write lock on a collection.

To learn about locks, see [FAQ: Concurrency.](https://www.mongodb.com/docs/manual/faq/concurrency.md#std-label-faq-concurrency)

### Client Disconnection

If the client that issued [`listCollections`](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#mongodb-dbcommand-dbcmd.listCollections) disconnects before the operation completes, MongoDB marks [`listCollections`](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#mongodb-dbcommand-dbcmd.listCollections) for termination using [`killOp`.](https://www.mongodb.com/docs/manual/reference/command/killOp.md#mongodb-dbcommand-dbcmd.killOp)

### Replica Set Member State Restriction

To run on a replica set member, [`listCollections`](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#mongodb-dbcommand-dbcmd.listCollections) operations require the member to be in [`PRIMARY`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.PRIMARY) or [`SECONDARY`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.SECONDARY) state. If the member is in another state, such as [`STARTUP2`](https://www.mongodb.com/docs/manual/reference/replica-states.md#mongodb-replstate-replstate.STARTUP2), the operation errors.

## Required Access

The [`listCollections`](https://www.mongodb.com/docs/manual/reference/command/listCollections.md#mongodb-dbcommand-dbcmd.listCollections) command and its wrapper [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) require the [`listCollections`](https://www.mongodb.com/docs/manual/reference/privilege-actions.md#mongodb-authaction-listCollections) action when access control is enforced. Users must have privileges that grant the `listCollections` action on the database to run `listCollections`.

For example, the following command grants the privilege to run [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) against the `test` database:

```javascript
{ resource: { db: "test", collection: "" }, actions: [ "listCollections" ] }
```

The built-in role [`read`](https://www.mongodb.com/docs/manual/reference/built-in-roles.md#mongodb-authrole-read) provides the privilege to run `listCollections` for a specific database.

Users without the required `read` privilege can run `listCollections` when `authorizedCollections` and `nameOnly` are both set to `true`. In this case, the command returns the names and types for collection(s) where the user has privileges.

For example, consider a user with a role that grants the following `find` privilege:

```javascript
{ resource: { db: "sales", collection: "currentQuarter" }, actions: [ "find" ] }
```

The user can run `listCollections` if  `authorizedCollections` and `nameOnly` are both set to `true`.

```javascript
db.runCommand(
   {
       listCollections: 1.0,
       authorizedCollections: true,
       nameOnly: true
   }
)
```

The operation returns the name and type of the `currentQuarter` collection.

However, the following operations return an error if the user does not have the required access authorization:

```javascript
db.runCommand(
   {
       listCollections: 1.0,
       authorizedCollections: true
   }
)

db.runCommand(
   {
       listCollections: 1.0,
       nameOnly: true
   }
)
```

## Output

A document that contains information needed to create a cursor to documents that contain collection names and options. The cursor information includes the [cursor id](https://www.mongodb.com/docs/manual/core/cursors.md#std-label-cursor-id), the full namespace for the command, and the first batch of results. Each document in the batch output contains the following fields:

| Field | Type | Description |
| --- | --- | --- |
| name | String | Name of the collection. |
| type | String | 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) |
| options | Document | Collection options. These options correspond to the options available in [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection). For option descriptions, see [`db.createCollection()`.](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection) |
| info | Document | Lists the following fields related to the collection: readOnly`boolean`. If `true` the data store is read only.uuidUUID (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. |
| idIndex | Document | Provides information on the `_id` index for the collection. |

The return value for the command. A value of `1` indicates success.

If you don't require a raw command response, use the [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos) or the [`db.getCollectionNames()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionNames.md#mongodb-method-db.getCollectionNames) helper methods.

## Example

### List All Collections

The `sample_mflix` database contains collections such as `movies`, `theaters`, `users`, and others.

To get a list of collection names, run the `listCollections` command with the `nameOnly` option.

```javascript
db.runCommand(
   {
      listCollections: 1.0,
      nameOnly: true
   }
)

```

**Output:**

```javascript
{
  cursor: {
    id: Long('0'),
    ns: 'sample_mflix.$cmd.listCollections',
    firstBatch: [
      { name: 'movies', type: 'collection' },
      { name: 'theaters', type: 'collection' },
      { name: 'users', type: 'collection' },
      { name: 'embedded_movies', type: 'collection' },
      { name: 'sessions', type: 'collection' },
      { name: 'comments', type: 'collection' },
      { name: 'system.views', type: 'collection' }
    ]
  },
  ok: 1
}

```

To get more detailed information, remove the `nameOnly` option.

```javascript
db.runCommand(
   {
      listCollections: 1.0
   }
)

```

**Output:**

```javascript
{
  cursor: {
    id: Long('0'),
    ns: 'sample_mflix.$cmd.listCollections',
    firstBatch: [
      {
        name: 'movies',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'theaters',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'users',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'embedded_movies',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'sessions',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'comments',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'system.views',
        type: 'collection',
        options: {},
        info: { ... },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      }
    ]
  },
  ok: 1
}

```

## Learn More

For collection options:

- [`db.createCollection()`](https://www.mongodb.com/docs/manual/reference/method/db.createCollection.md#mongodb-method-db.createCollection)

- [`create`](https://www.mongodb.com/docs/manual/reference/command/create.md#mongodb-dbcommand-dbcmd.create)

For collection information:

- [`db.getCollectionInfos()`](https://www.mongodb.com/docs/manual/reference/method/db.getCollectionInfos.md#mongodb-method-db.getCollectionInfos)

- [mongosh built-in commands](https://www.mongodb.com/docs/mongodb-shell/reference/access-mdb-shell-help.md#std-label-mongosh-help)