db.createCollection()
定义
兼容性
可以使用 db.createCollection()
查找托管在以下环境中的部署:
MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务
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 | 布尔 | |||||||||||
timeseries.timeField | 字符串 | 创建时间序列集合时需要。包含每个时间序列文档中日期的字段的名称。时间序列集合中的文档必须具有有效 BSON 日期,以作为 timeField 的值。 | ||||||||||
timeseries.metaField | 字符串 | 可选。包含每个时间序列文档中元数据的字段的名称。指定字段中的元数据应用于标识一系列唯一文档的数据。元数据应该很少改变(如果有的话)。 指定字段的名称可能不是 | ||||||||||
timeseries.granularity | 字符串 | 可选,如果设置 将 有关粒度和桶间隔的更多信息,请参阅设置时间序列数据的粒度。 | ||||||||||
timeseries.bucketMaxSpanSeconds | 整型 | 可选,与 要降级到 MongoDB 6.3 以下,必须修改集合以使用相应的 | ||||||||||
timeseries.bucketRoundingSeconds | 整型 | 可选,与 例如,将两个参数设置为 | ||||||||||
expireAfterSeconds | 数字 | |||||||||||
clusteredIndex | 文档 | 从 MongoDB 5.3开始,您可以创建具有集群化索引的集合。集群化索引与集合存储在同一个 WiredTiger 文件中。得到的集合称为集群化集合。
5.3 版本中的新增功能。 | ||||||||||
changeStreamPreAndPostImages | 文档 | 可选。 从 MongoDB 6.0 开始,可使用变更流事件来输出更改前后的文档版本(文档前映像和后映像):
要为集合启用变更流前图像和后图像,设立 有关变更流输出的完整示例,请参阅使用文档前像和后像的变更流。 如需了解有关本页的 6.0 版本中的新功能。 | ||||||||||
size | 数字 | 可选。指定固定大小集合的最大大小(以字节为单位)。一旦固定大小集合达到其最大大小,MongoDB 就会删除旧文档,为新文档腾出空间。对于固定大小集合, size 字段为必需项,对于其他集合,则忽略该字段。 | ||||||||||
max | 数字 | 可选。固定大小集合中允许的最大文档数。 size 限制优先于此限制。如果固定大小集合在达到最大文档数之前达到size 限制,则 MongoDB 将删除旧文档。如果您希望使用max 限制,请确保固定大小集合所需的size 限制足以包含最大数量的文档。 | ||||||||||
storageEngine | 文档 | 可选。仅适用于 WiredTiger 存储引擎。 允许用户在创建集合时针对每个集合指定存储引擎的配置。
在复制过程中,对创建集合时指定的存储引擎配置进行验证并记录到 oplog 中,以支持节点使用不同存储引擎的副本集。 从 MongoDB 7.2开始,在使用 | ||||||||||
validator | 文档 | 可选。允许用户为集合指定验证规则或表达式。
要了解如何使用模式验证创建集合,请参阅指定 JSON 模式验证。 | ||||||||||
validationLevel | 字符串 | 可选。确定 MongoDB 在更新期间将验证规则应用于现有文档的严格程度。
要查看使用 | ||||||||||
validationAction | 字符串 | 可选。 确定是对无效文档上的 重要文档验证仅适用于由 要查看使用 | ||||||||||
indexOptionDefaults | 文档 | 可选。允许用户在创建集合时指定索引的默认配置。
在复制过程中,对创建索引时指定的存储引擎配置进行验证并记录到 oplog 中,以支持其成员使用不同存储引擎的副本集。 | ||||||||||
viewOn | 字符串 | 要从中创建视图的源集合或视图的名称。有关详细信息,请参阅 db.createView() 。 | ||||||||||
pipeline | 阵列 | |||||||||||
collation | 文档 | 为集合指定默认排序规则。 排序规则允许用户为字符串比较指定特定于语言的规则,例如字母大小写和重音符号规则。 排序规则选项的语法如下:
指定排序规则时, 如果在集合级别指定排序规则:
如果没有为收集或操作指定排序规则,MongoDB 将使用先前版本中使用的简单二进制比较来进行字符串比较。 对于集合,只能在创建集合时指定排序规则。设置后,无法修改集合的默认排序规则。 有关示例,请参阅指定排序规则。 | ||||||||||
writeConcern | 文档 | 可选。表达该操作的写关注的文档。省略以使用默认的写关注。 在分片集群上发出时, |
访问控制
如果部署强制执行身份验证/授权,则 db.createCollection()
需要以下权限:
任务 | 所需权限 |
---|---|
创建固定大小集合 | 数据库上的
|
创建固定大小集合 |
|
创建视图 |
但是,如果用户在数据库上具有 |
在数据库中拥有 readWrite
内置角色的用户具有运行列表操作所需的特权。创建一个拥有所需角色的用户,或者将该角色授予现有用户。
行为
db.createCollection()
有以下行为:
资源锁定
db.createCollection()
在操作期间获得指定集合或视图的独占锁。对集合的所有后续操作都必须等到 db.createCollection()
释放该锁为止。db.createCollection()
通常会短暂占用该锁。
创建视图需获得数据库中 system.views
集合的额外独占锁。此锁会阻止创建或修改数据库中的视图,直到命令完成。
事务
如果事务不是跨分片写事务,则可以在分布式事务中创建集合和索引。
要在事务中使用 db.createCollection()
,该事务必须使用读关注 "local"
。如果指定 "local"
以外的读关注级别,则该事务将失败。
具有相同名称和选项的collection或视图
如果使用与现有collection或视图相同的名称和选项运行db.createCollection()
,则db.createCollection()
会返回成功。
示例
创建固定大小集合
固定大小集合具有最大大小或文档数,可以防止其增长超过最大阈值。所有固定大小集合都必须指定最大大小,也可以指定最大文档数。如果集合在达到最大文档计数之前达到最大大小限制,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.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
users
block_compressor
压缩器,请使用以下命令设置 选项:
db.createCollection( "users", { storageEngine: { wiredTiger: { configString: "block_compressor=zlib" } } } )
从 MongoDB 7.2开始,在使用db.createCollection()
创建集合时无法指定wiredTiger
存储引擎加密选项。 要为 WiredTiger 存储引擎配置加密,请参阅静态加密。