listCollections (database command)

Definition

listCollections

Retrieves information, including the names and creation options, for the collections and views in a database.

The listCollections command returns a document that contains an unsorted list of all collections and views in the database. You can use the returned document to create a cursor on the collection.

mongosh provides the db.getCollectionInfos() and the db.getCollectionNames() helper methods, as well as the show collections command.

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(
   {
     listCollections: 1,
     filter: <document>,
     nameOnly: <boolean>,
     authorizedCollections: <boolean>,
     comment: <any>
   }
)

Command Fields

The command can take the following optional fields:

Behavior

Required Access

The listCollections command and its wrapper db.getCollectionInfos() require the 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() against the test database:

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

The built-in role 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:

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

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

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:

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

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

Output

listCollections.cursor

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, 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, view for views, and timeseries for time series collection.
options	Document	Collection options. These options correspond directly to the options available in db.createCollection(). For the descriptions on the options, see db.createCollection().
info	Document	Lists the following fields related to the collection: readOnly boolean. If true the data store is read only. 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.
idIndex	Document	Provides information on the _id index for the collection.

listCollections.ok

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() or the db.getCollectionNames() helper methods.

Example

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

{
  cursor: {
    id: Long("0"),
    ns: 'music.$cmd.listCollections',
    firstBatch: [
      { name: 'motorhead', type: 'collection' },
      { name: 'taylorSwift', type: 'collection' },
      { name: 'ramones', type: 'collection' }
    ]
  },
  ok: 1
}

db.runCommand(
   {
      listCollections: 1.0
   }
)

{
  cursor: {
    id: Long("0"),
    ns: 'music.$cmd.listCollections',
    firstBatch: [
      {
        name: 'motorhead',
        type: 'collection',
        options: {},
        info: {
          readOnly: false,
          uuid: new UUID("09ef1858-2831-47d2-a3a7-9a29a9cfeb94")
        },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'taylorSwift',
        type: 'collection',
        options: {},
        info: {
          readOnly: false,
          uuid: new UUID("6c46c8b9-4999-4213-bcef-9a36b0cff228")
        },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      },
      {
        name: 'ramones',
        type: 'collection',
        options: {},
        info: {
          readOnly: false,
          uuid: new UUID("7e1925ba-f2f9-4e42-90e4-8cafd434a6c4")
        },
        idIndex: { v: 2, key: { _id: 1 }, name: '_id_' }
      }
    ]
  },
  ok: 1
}

Learn More

For collection options:

• db.createCollection()
• create

For collection information:

• db.getCollectionInfos()
• mongosh built-in commands