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() 方法具有以下参数

参数	类型	描述
`name`	string	要创建的集合的名称。请参阅命名限制。
`options`	document	可选。创建集合的配置选项固定集合分片集合视图

options 文档包含以下字段

字段

类型

描述

capped

boolean

可选。要创建一个 capped collection，指定 true。如果您指定 true，您还必须在 size 字段中设置最大大小。

timeseries.timeField

string

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

timeseries.metaField

string

可选。包含每个时间序列文档中元数据的字段名称。指定字段中的元数据应该是用于标记唯一文档序列的数据。元数据很少，如果不是永远都不会更改。

指定字段的名称不能是_id或与timeseries.timeField相同。该字段可以是任何类型，但不能是数组。

timeseries.granularity

string

可选，如果设置了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

document

从MongoDB 5.3开始，您可以创建一个带有分片索引的集合。分片索引存储在集合相同的WiredTiger文件中。生成的集合称为分片集合。

clusteredIndex 字段具有以下语法

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

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

新在版本5.3.

changeStreamPreAndPostImages

document

可选。

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

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

changeStreamPreAndPostImages 具有以下语法

changeStreamPreAndPostImages: {
   enabled: <boolean>
}

要为集合启用变更流前像和后像，将 enabled 设置为 true。

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

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

新在版本6.0.

大小

数字

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

最大值

数字

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

存储引擎

document

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

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

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

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

从MongoDB 7.2版本开始，在创建集合时无法指定wiredTiger存储引擎的加密选项。db.createCollection()。要配置WiredTiger存储引擎的加密，请参阅静态加密。

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

validator

document

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

validator选项接受一个文档，该文档指定了验证规则或表达式。您可以使用与查询操作符相同的操作符指定表达式，除了$near、$nearSphere、$text和$where之外。

要了解如何创建具有模式验证的集合，请参阅指定JSON Schema验证。

validationLevel

string

可选。确定MongoDB在更新期间如何严格地应用验证规则到现有文档。

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

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

validationAction

string

可选。确定是否在无效文档上抛出错误或仅对违规情况进行警告，但允许插入无效文档。

重要：仅对由validationLevel确定的文档进行文档验证。

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

indexOptionDefaults

document

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

indexOptionDefaults选项接受一个storageEngine文档，其形式如下

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

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

viewOn

string

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

流水线

数组

由聚合管道阶段组成的数组。使用聚合管道阶段。通过在 viewOn 集合或视图中应用指定的 pipeline 来创建视图的 db.createView() 方法。有关详细信息，请参阅 db.createView()。

校对

document

指定集合的默认校对。

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

校对选项的语法如下

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

在指定校对时，locale 字段是必需的；所有其他校对字段都是可选的。有关字段的描述，请参阅校对文档。

如果在校集级别指定了校对

该集合上的索引将使用该校对创建，除非索引创建操作明确指定了不同的校对。
除非明确指定了不同的校对，否则该集合上的操作使用集合的默认校对。
您不能为操作指定多个校对。例如，您不能为每个字段指定不同的校对，或者在执行带有排序的查找时，您不能为查找和排序使用不同的校对。

如果未为集合或操作指定校对，MongoDB 将使用先前版本中用于字符串比较的简单二进制比较。

对于集合，您只能在创建集合时指定校对。设置后，您不能修改集合的默认校对。

有关示例，请参阅指定校对。

写关注

document

可选。一个文档，表示操作的写关注。省略以使用默认写关注。

在分片集群上发出时，mongos 将写关注的 create 命令及其辅助 db.createCollection() 转换为 "majority"。

访问控制

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

任务	所需权限
创建非固定集合	`createCollection`数据库上的权限，或者 `insert`创建集合的权限
创建固定集合	`convertToCapped`集合的权限 `createCollection`数据库上的权限
创建视图	`createCollection`数据库上的权限。然而，如果用户在数据库上拥有`createCollection`和创建视图的`find`权限，则用户还必须拥有以下附加权限源集合或视图上的`find`权限。如果有的话，在`find`中引用的任何其他集合或视图。

数据库上具有内置角色readWrite的用户具有运行列出的操作所需的权限。或者创建具有所需角色的用户，或者将角色授予现有用户。

行为

db.createCollection() 具有以下行为

资源锁定

db.createCollection() 在操作期间对指定的集合或视图获取独占锁。所有后续对集合的操作都必须等待 db.createCollection() 释放锁。通常情况下，db.createCollection() 仅持有锁很短的时间。

创建视图需要获取对数据库中 system.views 集合的额外独占锁。此锁阻止在命令完成之前创建或修改数据库中的视图。

事务

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

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

提示

另请参阅

在事务中创建集合和索引

具有相同名称和选项的集合或视图

如果你使用与现有集合或视图相同名称和选项运行 db.createCollection()，则 db.createCollection() 返回成功。

示例

创建一个受限集合

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

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

此命令创建一个最大大小为 5 兆字节和最多 5000 个文档的名为 log 的集合。

有关受限集合的更多信息，请参阅受限集合。

创建时间序列集合

要创建一个时间序列集合，用于捕捉过去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 兆字节。要限制事件大小，您可以
- 将文档大小限制为 8 兆字节。如果其他更改流事件字段（如 updateDescription）不是很大，您可以在更改流输出中同时请求预图像和后图像。
- 如果其他更改流事件字段（如 updateDescription）不是很大，则在更改流输出中仅请求文档大小为 16 兆字节的后图像。
- 如果
  - 文档更新只影响文档结构或内容的很小一部分，并且
  - 不会引起 replace 更改事件。替换事件始终包括后图像。
要请求预图像，您在 db.collection.watch() 中将 fullDocumentBeforeChange 设置为 required 或 whenAvailable。要请求后图像，您可以使用相同的方法设置 fullDocument。
预图像写入到 config.system.preimages 集合。
- config.system.preimages 集合可能会变得很大。要限制集合大小，您可以设置预图像的 expireAfterSeconds 时间，如前面所示。
- 预图像由后台进程异步删除。

重要

向后不兼容功能

从 MongoDB 6.0 开始，如果您正在使用文档预图像和后图像进行更改流，则在使用 changeStreamPreAndPostImages 之前必须禁用每个集合的更改流预图像和后图像，使用 collMod 命令，然后才能降级到早期版本的 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存储引擎。

例如，要为users集合的文件块指定zlib压缩器，请使用以下命令设置block_compressor选项

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

从MongoDB 7.2版本开始，在创建集合时无法指定wiredTiger存储引擎的加密选项。db.createCollection()。要配置WiredTiger存储引擎的加密，请参阅静态加密。

db.commandHelp

下一步

db.createView