db.createCollection()

在此页面上

定义

兼容性
语法
访问控制
行为
示例

定义

db.createCollection(name, options)

创建一个新集合。对于视图，请参阅 db.createView()。

由于 MongoDB 在命令中首次引用集合时会隐式创建集合，因此此方法主要用于创建使用特定选项的新集合。例如，您使用db.createCollection()创建：

db.createCollection() 是数据库命令 create 的封装器。

兼容性

此方法可用于以下环境中托管的部署：

MongoDB Atlas：用于云中 MongoDB 部署的完全托管服务

注意

所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息，请参阅不支持的命令。

MongoDB Enterprise：基于订阅、自我管理的 MongoDB 版本
MongoDB Community：源代码可用、免费使用且可自行管理的 MongoDB 版本

语法

db.createCollection() 方法具有以下原型形式：

db.createCollection( <name>,
    {
      capped: <boolean>,
      timeseries: {                  // Added in MongoDB 5.0
         timeField: <string>,        // required for time series collections
         metaField: <string>,
         granularity: <string>,
         bucketMaxSpanSeconds: <number>,  // Added in MongoDB 6.3
         bucketRoundingSeconds: <number>  // Added in MongoDB 6.3
      },
      expireAfterSeconds: <number>,
      clusteredIndex: <document>,  // Added in MongoDB 5.3
      changeStreamPreAndPostImages: <document>,  // Added in MongoDB 6.0
      size: <number>,
      max: <number>,
      storageEngine: <document>,
      validator: <document>,
      validationLevel: <string>,
      validationAction: <string>,
      indexOptionDefaults: <document>,
      viewOn: <string>,
      pipeline: <pipeline>,
      collation: <document>,
      writeConcern: <document>
    }
  )

db.createCollection() 方法具有以下参数：

Parameter	类型	说明
`name`	字符串	要创建的集合名称。请参阅命名限制。
`options`	文档	可选。用于创建以下内容配置选项：固定大小集合集群化集合查看

options 文档包含以下字段：

字段

类型

说明

capped

布尔

可选。要创建固定大小集合，请将该字段设为 true。如果将该字段设为 true，则还须在 size 字段中设置最大大小。

timeseries.timeField

字符串

创建时间序列集合时需要。包含每个时间序列文档中日期的字段的名称。时间序列集合中的文档必须具有有效 BSON 日期，以作为 timeField 的值。

timeseries.metaField

字符串

可选。包含每个时间序列文档中元数据的字段的名称。指定字段中的元数据应用于标识一系列唯一文档的数据。元数据应该很少改变（如果有的话）。

指定字段的名称可能不是 _id 或与 timeseries.timeField 不同。该字段可为除数组之外的任意类型。

timeseries.granularity

字符串

可选，如果设置 bucketRoundingSeconds 和 bucketMaxSpanSeconds，请勿使用。可能的值为 seconds（默认值）、minutes 和 hours。

将 granularity 设置为与连续传入的时间戳之间的时间最匹配的值。通过优化 MongoDB 在集合中内部存储数据的方式，可以提高性能。

有关粒度和桶间隔的更多信息，请参阅设置时间序列数据的粒度。

timeseries.bucketMaxSpanSeconds

整型

可选，与 bucketRoundingSeconds 一起使用从而作为 granularity 的替代方案。设置同一数据桶中不同时间戳之间的最大间隔时间。可能的值为 1-31536000。如果设置 bucketMaxSpanSeconds，则须将 bucketRoundingSeconds 设为同一值。

要降级到 MongoDB 6.3 以下，必须修改集合以使用相应的 granularity 值，或者删除该集合。有关详细信息，请参阅 collMod。

timeseries.bucketRoundingSeconds

整型

可选，与bucketMaxSpanSeconds一起使用，作为granularity的替代。设置 MongoDB 设定新存储桶的最小时间戳时向下舍入的秒数。必须等于bucketMaxSpanSeconds。

例如，将两个参数设置为 1800 会将新的存储桶向下舍入到最近的 30 分钟。如果时间为 2023-03-27T18:24:35Z 的文档不适合现有存储桶，MongoDB 将创建一个新存储桶，其最小时间为 2023-03-27T18:00:00Z，最大时间为 2023-03-27T18:30:00Z。

expireAfterSeconds

数字

可选。指定时间序列集合或集群化集合中的文档过期的秒数。MongoDB 将自动删除过期文档。

对于集群化集合，会根据集群索引键 _id 自动删除文档，并且值必须是日期类型。请参阅 TTL 索引。

clusteredIndex

文档

从 MongoDB 5.3开始，您可以创建具有集群化索引的集合。集群化索引与集合存储在同一个 WiredTiger 文件中。得到的集合称为集群化集合。

clusteredIndex 字段采用以下语法：

clusteredIndex: {
   key: <object>,
   unique: <boolean>,
   name: <string>
}

key: 必需。集群索引键字段。必须设置为 { _id: 1 }。_id 字段的默认值是自动生成的唯一对象标识符，您也可以设置自己的集群索引键值。
unique: 必需。必须设置为 true。唯一索引表示集合不会接受集群索引键值与索引中现有值匹配的文档插入或更新。
name: 可选。唯一标识集群索引的名称。

5.3 版本中的新增功能。

changeStreamPreAndPostImages

文档

可选。

从 MongoDB 6.0 开始，可使用变更流事件来输出更改前后的文档版本（文档前映像和后映像）：

前映像是指被替换、更新或删除之前的文档。已插入的文档没有前映像。
后图像是插入、替换或更新后的文档。已删除的文档没有后图像。
使用 db.createCollection()、create 或 collMod 为集合启用 changeStreamPreAndPostImages。

changeStreamPreAndPostImages 通过以下语法实现：

changeStreamPreAndPostImages: {
   enabled: <boolean>
}

要启用集合的变更流前图像和后图像，请将 enabled 设定为 true。

有关变更流输出的完整示例，请参阅使用文档前像和后像的变更流。

db.createCollection()有关此页面上的示例，请参阅使用文档的变更流前像和后像创建集合。

6.0 版本中的新功能。

size

数字

可选。指定固定大小集合的最大大小（以字节为单位）。一旦固定大小集合达到其最大大小，MongoDB 就会删除旧文档，为新文档腾出空间。对于固定大小集合，size 字段为必需项，对于其他集合，则忽略该字段。

max

数字

可选。固定大小集合中允许的最大文档数。size限制优先于此限制。如果固定大小集合在达到最大文档数之前达到size限制，则 MongoDB 将删除旧文档。如果您希望使用max限制，请确保固定大小集合所需的size限制足以包含最大数量的文档。

storageEngine

文档

可选。仅适用于 WiredTiger 存储引擎。

允许用户在创建集合时针对每个集合指定存储引擎的配置。storageEngine 选项的值应采用以下形式：

{ <storage-engine-name>: <options> }

在复制过程中，对创建集合时指定的存储引擎配置进行验证并记录到 oplog 中，以支持节点使用不同存储引擎的副本集。

从 MongoDB 7.2（和 7.0.5）开始，在使用 db.createCollection() 创建集合时，不能指定 wiredTiger 存储引擎加密选项。要为 WiredTiger 存储引擎配置加密，请参阅静态加密。

有关详细信息，请参阅指定存储引擎选项。

validator

文档

可选。允许用户为集合指定验证规则或表达式。

validator 选项采用指定验证规则或表达式的文档。可以使用与该查询运算符相同的操作符来指定表达式，但 $near、$nearSphere、$text 和 $where 除外。

要了解如何使用模式验证创建集合，请参阅指定 JSON 模式验证。

validationLevel

字符串

可选。确定 MongoDB 在更新期间将验证规则应用于现有文档的严格程度。

"off": 不对插入或更新进行验证。
"strict": 默认将验证规则应用于所有插入和所有更新。
"moderate": 将验证规则应用于现有有效文档的插入和更新。请勿将规则应用于现有无效文档的更新。

要查看使用 validationLevel 的示例，请参阅为现有文档指定验证级别。

validationAction

字符串

可选。确定是对无效文档上的error，还是仅对违规行为的warn，但允许插入无效文档。

重要提示：文档验证仅适用于由 validationLevel 确定的文档。

要查看使用 validationAction 的示例，请参阅选择如何处理无效文档。

indexOptionDefaults

文档

可选。允许用户在创建集合时指定索引的默认配置。

indexOptionDefaults 选项接受 storageEngine 文档，该文档应采用以下形式：

{ <storage-engine-name>: <options> }

在复制过程中，对创建索引时指定的存储引擎配置进行验证并记录到 oplog 中，以支持其成员使用不同存储引擎的副本集。

viewOn

字符串

要从中创建视图的源集合或视图的名称。有关详细信息，请参阅db.createView() 。

pipeline

阵列

由聚合管道阶段组成的数组。db.createView()将指定的 pipeline 应用于 viewOn 集合或视图，从而创建视图。有关详细信息，请参阅db.createView()。

collation

文档

为集合指定默认排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

排序规则选项的语法如下：

collation: {
   locale: <string>,
   caseLevel: <boolean>,
   caseFirst: <string>,
   strength: <int>,
   numericOrdering: <boolean>,
   alternate: <string>,
   maxVariable: <string>,
   backwards: <boolean>
}

指定排序规则时，locale 字段为必填字段；所有其他排序规则字段均为可选字段。有关字段的说明，请参阅排序规则文档。

如果在集合级别指定排序规则：

除非索引创建操作显式指定其他排序规则，否则会用该排序规则创建此集合上的索引。
除非明确指定其他排序规则，否则对该集合的操作使用集合的默认排序规则。
您不能为一个操作指定多个排序规则。例如，您不能为每个字段指定不同的排序规则，或者如果执行带排序的查找，则不能使用一种排序规则进行查找而另一种排序规则进行排序。

如果没有为收集或操作指定排序规则，MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。

对于集合，只能在创建集合时指定排序规则。设置后，无法修改集合的默认排序规则。

有关示例，请参阅指定排序规则。

writeConcern

文档

可选。表达该操作的写关注的文档。省略以使用默认的写关注。

在分分片集群上发出时，会将mongos 命令及其帮助程序 create的写关注（write db.createCollection() concern）转换为"majority" 。

访问控制

如果部署强制执行身份验证/授权，则 db.createCollection() 需要以下权限：

任务	所需权限
创建固定大小集合	数据库上的`createCollection`，或 `insert` 集合
创建固定大小集合	`convertToCapped` 集合 `createCollection` （在数据库中）
创建视图	`createCollection` （在数据库中）。但是，如果用户在数据库上具有 `createCollection` 权限，并在要创建的视图上具有 `find` 权限，则则该用户还须具有以下额外权限： `find` 源集合或视图上。 `find`位于`pipeline`中引用的任何其他集合或视图（如有）。

在数据库中拥有 readWrite 内置角色的用户具有运行列表操作所需的特权。创建一个拥有所需角色的用户，或者将该角色授予现有用户。

行为

资源锁定

db.createCollection() 在操作期间获得指定集合或视图的独占锁。对集合的所有后续操作都必须等到 db.createCollection() 释放该锁为止。db.createCollection() 通常会短暂占用该锁。

创建视图需获得数据库中 system.views 集合的额外独占锁。此锁会阻止创建或修改数据库中的视图，直到命令完成。

事务

如果事务不是跨分片写事务，则可以在分布式事务中创建集合和索引。

要在事务中使用 db.createCollection()，该事务必须使用读关注 "local"。如果指定 "local" 以外的读关注级别，则该事务将失败。

提示

另请参阅：

在事务中创建集合和索引

示例

创建固定大小集合

固定大小集合具有最大大小或文档数，可以防止其增长超过最大阈值。所有固定大小集合都必须指定最大大小，也可以指定最大文档数。如果集合在达到最大文档计数之前达到最大大小限制，MongoDB 会删除较旧的文档。考虑以下示例：

db.createCollection("log", { capped : true, size : 5242880, max : 5000 } )

此命令创建名为 log 的集合，最大大小为 5 MB，最多包含 5000 份文档。

有关固定大小集合的更多信息，请参阅固定大小集合。

创建时间序列集合

要创建捕捉过去 24 小时天气数据的时间序列集合，请发出此命令：

db.createCollection(
    "weather24h",
    {
       timeseries: {
          timeField: "timestamp",
          metaField: "data",
          granularity: "hours"
       },
       expireAfterSeconds: 86400
    }
)

或者，要创建相同的集合，但将每个存储桶在同一小时内限制为时间戳值，请发出以下命令：

db.createCollection(
    "weather24h",
    {
       timeseries: {
          timeField: "timestamp",
          metaField: "data",
          bucketMaxSpanSeconds: "3600",
          bucketRoundingSeconds: "3600"
       },
       expireAfterSeconds: 86400
    }
)

创建集群化集合

下面的 db.createCollection() 示例添加了一个名为 stocks 的聚集文档：

db.createCollection(
   "stocks",
   { clusteredIndex: { "key": { _id: 1 }, "unique": true, "name": "stocks clustered key" } }
)

在此示例中，clusteredIndex 将指定：

"key": { _id: 1 }，用于按照 _id 字段设置集群索引键。
"unique": true，它表示聚集索引键值必须是唯一的。
"name": "stocks clustered key"，设置集群索引名称。

使用文档的变更流前像和后像创建集合

从 MongoDB 6.0 开始，可使用变更流事件来输出更改前后的文档版本（文档前映像和后映像）：

前映像是指被替换、更新或删除之前的文档。已插入的文档没有前映像。
后图像是插入、替换或更新后的文档。已删除的文档没有后图像。
为使用 db.createCollection()、create 或 collMod 的集合启用 changeStreamPreAndPostImages。

以下示例创建一个启用了 ChangeStreampreandPostImages 的集合：

db.createCollection(
   "temperatureSensor",
   { changeStreamPreAndPostImages: { enabled: true } }
);

如果图像属于以下情况，则前像和后像不可用于变更流事件：

在文档更新或删除操作时未对集合启用。
在 expireAfterSeconds 中设置的前像和后像保留时间后之后被删除。
- 以下示例将整个集群上的 expireAfterSeconds 设置为 100 秒：
  use admin db.runCommand( { setClusterParameter: { changeStreamOptions: { preAndPostImages: { expireAfterSeconds: 100 } } } } )
- 以下示例返回当前的 changeStreamOptions 设置，包括 expireAfterSeconds：
  db.adminCommand( { getClusterParameter: "changeStreamOptions" } )
- 将 expireAfterSeconds 设置为 off 可使用默认保留策略：将保留前像和后像，直到从 oplog 中删除对应的变更流事件。
- 如果变更流事件从 oplog 中删除，则无论 expireAfterSeconds 前映像和后映像保留时间如何，相应的前映像和后映像也会被删除。

其他考量：

启用前像和后像会占用存储空间并增加处理时间。仅在需要时启用前像和后像。
将变更流事件大小限制为小于 16 MB。要限制事件大小，您可以：
- 将文档大小限制为 8 MB。如果其他 change stream 事件字段（例如 updateDescription）不是很大，则可以在 change stream 输出中同时请求更新前的文档和更新后的文档。
- 如果其他变更流事件字段（例如 updateDescription）并不大，则仅请求变更流输出中最多 16 MB 的文档的后像。
- 在以下情况下，仅请求最大 16 MB 的文档的 change stream 输出中的预映像：
  - 文档更新仅影响文档结构或内容的一小部分，且
  - 不会引起 replace 变更事件。replace 事件始终包含后像。
要请求前图像，请在db.collection.watch()中将fullDocumentBeforeChange设置为required或whenAvailable。要请求后图像，您可以使用相同的方法设置fullDocument。
前像被写入 config.system.preimages 集合。
- config.system.preimages 集合可能会变大。要限制集合大小，可如前文所示为前映像设置 expireAfterSeconds 时间。
- 前像由后台进程异步删除。

重要

向后不兼容的功能

从 MongoDB 6.0 开始，如果您将文档前图像和后图像用于 change stream，则必须使用 collMod 命令为每个集合禁用 changeStreamPreAndPostImages，然后才能降级到早期 MongoDB 版本。

提示

另请参阅：

有关变更流事件和输出，请参阅变更事件。
要查看集合的变化，请参阅 db.collection.watch()。
有关变更流输出的完整示例，请参阅使用文档前像和后像的变更流。

指定排序规则。

排序规则允许用户为字符串比较指定特定于语言的规则，例如字母大小写和重音符号规则。

您可在集合或视图级别指定排序规则。例如，以下操作会创建一个集合，并为该集合指定排序规则（请参阅排序规则文档以查看排序规则字段的描述）：

db.createCollection( "myColl", { collation: { locale: "fr" } } );

支持排序规则的索引和操作将使用此排序规则，除非它们显式指定其他排序规则。例如，将以下文档插入到 myColl 中：

{ _id: 1, category: "café" }
{ _id: 2, category: "cafe" }
{ _id: 3, category: "cafE" }

以下操作使用集合的排序规则：

db.myColl.find().sort( { category: 1 } )

该操作按以下顺序返回文档：

{ "_id" : 2, "category" : "cafe" }
{ "_id" : 3, "category" : "cafE" }
{ "_id" : 1, "category" : "café" }

对使用简单二进制排序规则的集合执行相同的操作（即无特定排序规则集）按以下顺序返回文档：

{ "_id" : 3, "category" : "cafE" }
{ "_id" : 2, "category" : "cafe" }
{ "_id" : 1, "category" : "café" }

提示

另请参阅：

创建具有默认排序规则的视图

指定存储引擎选项

当使用db.createCollection()创建集合时，可以指定特定于集合的存储引擎配置选项。考虑以下操作：

db.createCollection(
   "users",
   { storageEngine: { wiredTiger: { configString: "<option>=<setting>" } } }
)

此操作创建一个名为 users 的新集合，其中包含 MongoDB 将传递到 wiredTiger 存储引擎的特定配置字符串。

例如，要为collection中的文件块指定zlib usersblock_compressor压缩器，请使用以下命令设置选项：

db.createCollection(
   "users",
   { storageEngine: { wiredTiger: { configString: "block_compressor=zlib" } } }
)

从 MongoDB 7.2（和 7.0.5）开始，当使用 db.createCollection() 创建集合时，无法指定 wiredTiger 存储引擎加密选项。要为 WiredTiger 存储引擎配置加密，请参阅静态加密。

后退

db.commandHelp

来年

db.createView