listCollections

New in version 3.0.0.

Definition

  • listCollections
  • Retrieve information, i.e. the name and options, about thecollections and views in a database. Specifically, the command returns adocument that contains information with which to create acursor to the collection information. The mongo shellprovides the db.getCollectionInfos() and thedb.getCollectionNames() helper methods.

The command has the following form:

  1. { listCollections: 1, filter: <document>, nameOnly: <boolean> }

The listCollections command can take the followingoptional field:

FieldTypeDescriptionfilterdocumentOptional. A query expression to filter the list of collections.

You can specify a query expression on any of the fieldsreturned by listCollections.nameOnlybooleanOptional. A flag to indicate whether the command should return just thecollection/view names and type or return both the name and other information.

Returning just the name and type (view or collection) doesnot take collection-level locks whereas returning full collectioninformation locks each collection in the database.

The default value is false.

Note

When nameOnly is true, your filter expression can onlyfilter based on a collection’s name and type. No other fields areavailable.

New in version 4.0.

authorizedCollectionsbooleanOptional. A flag, when set to true and used with nameOnly: true, thatallows a user without the required privilege (i.e.listCollections action on the database) to run thecommand when access control is enforced.

When both authorizedCollections and nameOnly options are setto true, the command returns only those collections for which the userhas privileges. For example, if a user has find actionon specific collections, the command returns only those collections; or,if a user has find or any other action, on thedatabase resource, the command lists all collections in the database.

The default value is false. That is, the user must havelistCollections action on the database to run thecommand.

For a user who has listCollections action on thedatabase, this option has no effect since the user has privileges tolist 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 thecommand when access control is enforced. Otherwise, the user isunauthorized to run the command.

New in version 4.0.

Behavior

Filter

Use a filter to limit the results of listCollections. Youcan specify a filter on any of the fields returned in the listCollections resultset.

Locks

Changed in version 4.0.

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

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

Client Disconnection

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

Required Access

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

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

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

Starting in version 4.0, however, user without the required privilegecan run the command with both authorizedCollections andnameOnly options set to true. In this case, the command returnsjust the name and type of the collection(s) to which the user hasprivileges.

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

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

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

  1. 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 filteroption) error for the user without the required access:

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

show collections

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

  1. db.runCommand( { listCollections: 1.0, authorizedCollections: true, nameOnly: true } )
  • For users with the required access, show collections lists thenon-system collections for the database.
  • For users without the required access, show collections listsonly the collections for which the users has privileges.

Earlier MongoDB Versions

When a version 4.0 mongo shell is connected to anearlier version MongoDB deployment that does not supportauthorizedCollections and nameOnly options,

  • A user must have the required access to runlistCollection.
  • If a user does not have required access and runs showcollections, MongoDB uses theauthenticatedUserPrivileges fieldreturned by connectionStatus to return an approximatelist of collections for the user.

Output

  • listCollections.cursor
  • A document that contains information with which to create a cursorto documents that contain collection names and options. The cursorinformation includes the cursor id, the full namespace for thecommand, as well as the first batch of results. Each document in thebatch output contains the following fields:

FieldTypeDescriptionnameStringName of the collection.typeStringType of data store. Returns collection forcollectionsand view for views.optionsDocumentCollection options.

These options correspond directly to the options available indb.createCollection(). For the descriptions on theoptions, see db.createCollection().infoDocumentLists the following fields related to the collection:

  • readOnly
  • boolean. If true the data store is read only.
  • uuid
  • UUID. Onceestablished, the collection UUID does not change. Thecollection UUID remains the same across replica setmembers and shards in a sharded cluster.

New in version 3.6.

idIndexDocumentProvides information on the _id index for thecollection.

  • listCollections.ok
  • The return value for the command. A value of 1 indicatessuccess.

Example

List All Collections

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

  1. use records
  2. db.getCollectionInfos();

See also

db.getCollectionInfos()