“文档” 菜单
文档首页
/
MongoDB Manual
/
参考
/
数据库命令
/
管理命令

listCollections

在此页面上

  • 定义
  • 语法
  • 命令字段
  • 行为
  • 必需的访问权限
  • 输出
  • 例子
  • 了解详情

定义

listCollections

检索数据库中集合和视图的信息，包括名称和创建选项。

listCollections 命令返回一个文档，其中包含可用于在集合上创建游标的信息。

mongosh 提供 db.getCollectionInfos() 和 db.getCollectionNames() 辅助方法。

语法

该命令具有以下语法：

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

命令字段

该命令可以采用以下可选字段：

字段
类型
说明
filter
文档

可选。用于筛选集合列表的查询表达式。

您可以对 listCollections 返回的任何字段指定查询表达式。

nameOnly
布尔

可选。指示命令是应仅返回名称和类型还是同时返回名称和其他信息的标志。

仅返回名称和类型（ view 、 collection或timeseries ）不会采用集合级锁，而返回完整的集合信息则会锁定数据库中的每个集合。

默认值为 false。

注意

当 nameOnly 为 true 时，filter 表达式只能根据集合的名称和类型进行筛选。没有其他可用字段。

authorizedCollections
布尔

可选。一个标记，当设置为 true 并与 nameOnly: true 一起使用时，允许没有所要求的特权（即数据库上的listCollections 操作）的用户在强制执行访问控制期间运行命令。

当 authorizedCollections 和 nameOnly 选项均设置为 true 时，该命令仅返回用户对其拥有特权的集合。例如，如果用户有权对特定集合执行 find 操作，则该命令仅返回这些集合；或者，如果用户有权对数据库资源执行 find 或任何其他操作，则该命令将列出数据库中的所有集合。

默认值为 false。也就是说，用户必须有权对数据库执行 listCollections 操作才能运行命令。

对于有权对数据库执行 listCollections 操作的用户，此选项无效，因为该用户有权列出数据库中的集合。

不与 nameOnly: true 一起使用时，此选项无效。也就是说，在实施访问控制期间，用户必须具有运行命令所需的特权。否则，用户无权运行命令。

comment
任何

可选。用户提供的待附加到该命令的注释。设置后，该注释将与该命令的记录一起出现在以下位置：

注释可以是任何有效的 BSON 类型（字符串、整型、对象、数组等）。

注意

在 listCollections 命令上设置的任何注释都将由在 listCollections 游标上运行的任何后续 getMore 命令继承。

行为

Filter

使用过滤器限制 listCollections 的结果。您可以在 listCollections 的结果集中返回的任一字段上指定 filter。

锁

listCollections 锁行为：

  • MongoDB 5.0 以前的版本，当 listCollections 持有数据库上的意向共享锁时，listCollections 会在数据库中的每个集合上获取意向共享锁。

  • 从 MongoDB 5.0 开始，listCollections 不再对集合或数据库采用意图共享锁。listCollections 不会被对集合持有独占写锁的操作阻止。

要了解锁，请参阅MongoDB 使用什么类型的锁？。

客户端断开连接

从 MongoDB 4.2 开始，如果在操作完成之前，发出 listCollections 的客户端断开连接，MongoDB 将使用killOp 将 listCollections 标记为终止。

副本集节点状态限制

若要在副本集节点上运行，listCollections 操作要求该节点处于 PRIMARY 或 SECONDARY 状态。如果该节点处于其他状态，如 STARTUP2，则操作错误。

必需的访问权限

当强制执行访问控制时，listCollections 命令需要执行 listCollections 操作。用户必须具有授予对数据库执行 listCollections 操作的特权才能运行 listCollections。

例如，以下命令授予对 test 数据库运行 db.getCollectionInfos() 的特权：

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

内置角色 read 提供为特定数据库运行 listCollections 的特权。

当 authorizedCollections 和 nameOnly 都设置为 true 时，没有所需的 read 特权的用户可以运行 listCollections。在这种情况下，该命令将返回用户对其拥有特权的集合的名称和类型。

例如，假设某个用户具有授予以下 find 特权的角色：

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

如果 authorizedCollections 和 nameOnly 都设置为 true，则用户可以运行listCollections。

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

该操作将返回 currentQuarter 集合的名称和类型。

但是，如果用户没有所需访问授权，以下操作会返回错误：

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

show collections

mongosh 方法 show collections 类似于：

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

  • 对于具有所需访问权限的用户，show collections 将列出数据库的非系统集合。

  • 对于不具有所需访问权限的用户，show collections 仅列出用户对其拥有特权的集合。

输出

listCollections.cursor

一个文档，其中包含创建具有集合名称和选项的文档游标所使用的信息。游标信息包括游标 ID、命令的完整命名空间以及第一批结果。批处理输出中的每个文档都包含以下字段：

字段
类型
说明
名称
字符串
集合的名称。
类型
字符串
数据存储的类型。为集合返回 collection，为视图返回 view，并为时间序列集合返回 timeseries。
选项
文档

集合选项。

这些选项与 db.createCollection() 中的选项直接对应。有关选项的说明，请参阅 db.createCollection()。

信息
文档

列出与集合相关的以下字段：

只读
boolean。如果为 true，则数据存储为只读。
uuid
UUID 。建立后，集合 UUID 就不会更改。集合 UUID 在分片集群的副本集成员和分片中保持不变。
idIndex
文档
提供有关集合的 _id 索引信息。
listCollections.ok

命令的返回值。值为 1 表示成功。

例子

列出所有集合

music 数据库包含三个集合：motorhead、taylorSwift 和 ramones。

要列出数据库中的集合，可以使用内置的 mongosh 命令：show collections。

show collections

输出见下：

motorhead
ramones
taylorSwift

要使用 listCollections 集合命令获取类似列表，则使用 nameOnly 选项。

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
}

要获取更多详细信息，请删除 nameOnly 选项。

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
}

了解详情

对于集合选项：

有关集合信息：

← killOp
listDatabases →

在此页面上