• Reference >
• Database Commands >
• Administration Commands >
• listCollections

listCollections

Definition

listCollections

Retrieve information, i.e. the name and options, about the collections and views in a database. Specifically, the command returns a document that contains information with which to create a cursor to the collection information. The mongo shell provides the db.getCollectionInfos() and the db.getCollectionNames() helper methods.

The command has the following form:

copy

{ listCollections: 1, filter: <document>, nameOnly: <boolean>, authorizedCollections: <boolean>, comment: <any> }

The listCollections command can take the following optional field:

Field	Type	Description
filter	document	Optional. A query expression to filter the list of collections. You can specify a query expression on any of the fields returned by listCollections.
nameOnly	boolean	Optional. A flag to indicate whether the command should return just the collection/view names and type or return both the name and other information. Returning just the name and type (view or collection) does not take collection-level locks whereas returning full collection information locks each collection in the database. The default value is false. Note When nameOnly is true, your filter expression can only filter based on a collection’s name and type. No other fields are available. New in version 4.0.
authorizedCollections	boolean	Optional. A flag, when set to true and used with nameOnly: true, that allows a user without the required privilege (i.e. 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 action on specific collections, the command returns only those collections; or, if a user has 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 action on the database to run the command. For a user who has listCollections action on the database, this option has no effect since the user has privileges to list the collections in the database. When used without nameOnly: true, this option has no effect. That is, 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. New in version 4.0.
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, in the attr.command.cursor.comment field. Database profiler output, in the command.comment field. currentOp output, in the command.comment field. A comment can be any valid BSON type (string, integer, object, array, etc). New in version 4.4.

Behavior

Filter

Use a filter to limit the results of listCollections. You can specify a filter on any of the fields returned in the listCollections result set.

Locks

Changed in version 4.0.

The listCollection command takes Intent Shared lock on the database. In previous versions, the command takes Shared lock on the database.

Unless the nameOnly option is specified, the command also takes an Intent Shared lock on each of the collections in turn while holding the Intent Shared lock on the database.

Client Disconnection

Starting in MongoDB 4.2, if the client that issued the listCollections disconnects before the operation completes, MongoDB marks the listCollections for termination (i.e. killOp on the operation).

Replica Set Member State Restriction

Starting in MongoDB 4.4, to run on a replica set member, listCollections operations require the member to be in PRIMARY or SECONDARY state. If the member is in another state, such as STARTUP2, the operation errors.

In previous versions, the operations can also be run when the member is in STARTUP2. However, the operations wait until the member transitions to RECOVERING.

Required Access

To run listCollections when access control is enforced, users must, in general, have privileges that grant listCollections action on the database. For example, the following privilege grants users to run db.getCollectionInfos() against the test database:

copy

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

The built-in role read provides the privilege to run listCollection for a specific database.

Starting in version 4.0, however, user without the required privilege can run the command with both authorizedCollections and nameOnly options set to true. In this case, the command returns just the name and type of the collection(s) to which the user has privileges.

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

copy

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

The user can run the command if the command includes both authorizedCollections and nameOnly options set to true (with or without the filter option):

copy

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

The operation returns the name and type of the foo collection.

However, the following operations (with or without the filter option) error for the user without the required access:

copy

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

show collections

Starting in version 4.0 of the mongo shell, show collections is equivalent to:

copy

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

• For users with the required access, show collections lists the non-system collections for the database.
• For users without the required access, show collections lists only the collections for which the users has privileges.

Earlier MongoDB Versions

When a version 4.0 mongo shell is connected to an earlier version MongoDB deployment that does not support authorizedCollections and nameOnly options,

• A user must have the required access to run listCollection.
• If a user does not have required access and runs show collections, MongoDB uses the authenticatedUserPrivileges field returned by connectionStatus to return an approximate list of collections for the user.

Output

listCollections.cursor

A document that contains information with which 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, as well as 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 and view for views.
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. New in version 3.6.
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.

Example

List All Collections

The following example uses the db.getCollectionInfos() helper to return information for all collections in the records database:

copy

use records
db.getCollectionInfos();

See also

db.getCollectionInfos()

←   killOp listDatabases  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.