collMod
定义
collMod
collMod
可以让您向集合添加选项或修改视图定义。提示
在
mongosh
中,还可以通过hideIndex()
和unhideIndex()
辅助方法运行此命令。辅助方法对
mongosh
用户来说很方便,但它们返回的信息级别可能与数据库命令不同。如果不追求方便或需要额外的返回字段,请使用数据库命令。注意
collMod
修改的视图并非指的是物化视图。有关按需物化视图的讨论,请参阅$merge
。
兼容性
此命令可用于以下环境中托管的部署:
MongoDB Atlas:用于云中 MongoDB 部署的完全托管服务
注意
所有 MongoDB Atlas 集群都支持此命令。有关 Atlas 对所有命令的支持的信息,请参阅不支持的命令。
MongoDB Enterprise:基于订阅、自我管理的 MongoDB 版本
MongoDB Community:源代码可用、免费使用且可自行管理的 MongoDB 版本
语法
该命令具有以下语法:
db.runCommand( { collMod: <collection or view>, <option1>: <value1>, <option2>: <value2>, ... } )
对于 <collection or view>
,指定当前数据库中集合或视图的名称。
选项
更改索引属性
要更改索引选项,请指定想要更改的索引选项的现有键模式或名称:
db.runCommand( { collMod: <collection>, index: { keyPattern: <index_spec> | name: <index_name>, expireAfterSeconds: <number>, // Set the TTL expiration threshold hidden: <boolean>, // Change index visibility in the query planner prepareUnique: <boolean>, // Reject new duplicate index entries unique: <boolean> // Convert an index to a unique index }, dryRun: <boolean> } )
如果索引不存在,该命令将出错并显示以下消息:"cannot find index <name|keyPattern> for ns <db.collection>"
。
index
index
选项可以更改现有索引的以下属性:索引属性说明expireAfterSeconds
用于确定 TTL 集合过期阈值的秒数。
如果成功,该命令将返回一份包含以下内容的文档:
expireAfterSeconds_new
,expireAfterSeconds
expireAfterSeconds_old
,expireAfterSeconds
的旧值(如果索引之前设置了expireAfterSeconds
的值)。
修改索引选项
expireAfterSeconds
会重置该索引的$indexStats
。如果您使用 MongoDB 5.0 之前版本创建的 TTL 索引,或者要将 MongDB 5.0 创建的数据与之前版本同步,请参阅使用 NaN 配置索引,以避免错误配置问题。
TTL 索引
expireAfterSeconds
值必须介于0
和2147483647
(包含两者)之间。hidden
确定索引是否对查询计划器隐藏的布尔值。
如果
hidden
值发生更改,该命令将返回一个文档,其中包含已更改属性的旧值和新值:hidden_old
和hidden_new
。但是,如果
hidden
值没有变化(即隐藏已隐藏的索引或取消隐藏已取消隐藏的索引),该命令会从输出中忽略hidden_old
和hidden_new
字段。要隐藏索引,必须将 featureCompatibilityVersion 设置为
4.4
或更大。如果该值发生变化,修改索引选项
hidden
会重置索引的$indexStats
。prepareUnique
一个布尔值,用于确定索引是否接受新的重复条目。
当
prepareUnique
为true
时,新的重复条目会失败并出现 DuplicateKey 错误。由此产生的索引可转换为唯一索引。要转换索引,使用collMod
和unique
选项。如果更新现有索引使得
prepareUnique
为true
,则不会检查该索引是否存在预先存在的重复索引条目。6.0 版本中的新功能。
unique
确定索引是否唯一的布尔值。
不支持
false
的值。当
unique
为true
时,collMod
会扫描keyPattern
索引有无重复项,如果没有重复索引条目,则将其转换为唯一索引。如果在初始扫描期间检测到重复条目,
collMod
将返回CannotConvertIndexToUnique
和冲突文档列表。要将具有重复条目的索引转换为唯一索引,请更正所有报告的冲突并重新运行collMod
。要结束转换,请将
prepareUnique
设置为false
。要查看如何将非唯一索引转换为唯一索引的示例,请参阅将现有索引转换为唯一索引。
6.0 版本中的新功能。
验证文档
validator
validator
允许用户为集合指定验证规则或表达式。validator
选项采用指定验证规则或表达式的文档。可以使用与该查询运算符相同的操作符来指定表达式,但$near
、$nearSphere
、$text
和$where
除外。注意
更新和插入期间进行验证。现有文档在修改之前不会进行验证检查。
不能为
admin
、local
和config
数据库中的集合指定验证器。无法为
system.*
集合指定验证器。
validationLevel
validationLevel
确定 MongoDB 在更新期间将验证规则应用于现有文档的严格程度。"off"
- 不对插入或更新进行验证。
"strict"
- 默认将验证规则应用于所有插入和所有更新。
"moderate"
- 将验证规则应用于现有有效文档的插入和更新。请勿将规则应用于现有无效文档的更新。
要查看使用
validationLevel
的示例,请参阅为现有文档指定验证级别。
validationAction
validationAction
选项确定是否对无效文档进行error
,或者仅warn
违反但允许无效文档。重要
文档验证仅适用于由
validationLevel
确定的文档。要查看使用
validationAction
的示例,请参阅选择如何处理无效文档。
修改视图
注意
此命令修改的视图并非指的是物化视图。有关按需物化视图的讨论,请参阅 $merge
。
pipeline
如果在运行访问控制的 MongoDB 部署上修改视图,则需使用此命令。
视图定义是公开的;即视图上的
db.getCollectionInfos()
和explain
操作将包括定义视图的管道。因此,应避免在视图定义中直接引用敏感字段和值。
db.runCommand( { collMod: "myView", viewOn: "activities", pipeline: [ { $match: { status: "Q" } }, { $project: { user: 1, date: 1, description: 1} } ] } )
修改时间序列集合
expireAfterSeconds
要启用自动删除文档或修改时间序列集合的当前过期时间间隔,请更改
expireAfterSeconds
值:db.runCommand( { collMod: <collection>, expireAfterSeconds: <number> | "off" } ) 将
expireAfterSeconds
设定为"off"
可禁用自动删除,或设定为非负十进制数 (>=0
) 以指定文档过期的秒数。
granularity
要修改时间序列集合的粒度,可以将
timeseries.granularity
从较短的时间单位增加到较长的时间单位:db.runCommand( { collMod: "weather24h", timeseries: { granularity: "seconds" | "minutes" | "hours" } } ) 要更新自定义分桶字段
bucketRoundingSeconds
和bucketMaxSpanSeconds
而不是granularity
,请将这两个自定义字段包含在collMod
命令中并将它们设置为相同的值:db.runCommand( { collMod: "weather24h", timeseries: { bucketRoundingSeconds: 86400, bucketMaxSpanSeconds: 86400 } } ) 您无法减少粒度间隔或自定义分桶值。
重要
如果任何time-series collection明确指定了自定义分桶字段
bucketMaxSpanSeconds
和bucketRoundingSeconds
,则无法降级到 MongoDB 6.3 以下。如果可能,请转换为相应的granularity
。 如果不能,则必须在降级之前删除该collection。要将集合从自定义分桶转换为
granularity
,bucketMaxSpanSeconds
和bucketRoundingSeconds
值都必须小于或等于granularity
等效值:granularity
bucketRoundingSeconds
限值(包含本数)bucketMaxSpanSeconds
限值(包含本数)seconds
603600minutes
360086400hours
864002592000
调整固定大小集合的大小
6.0 版本中的新功能。
从 MongoDB 6.0 开始,您可以重新调整固定大小集合。要更改固定大小集合的最大字节数,请使用 cappedSize
选项。要更改现有固定大小集合中的最大文档数,请使用 cappedMax
选项。
注意
您不能使用这些命令来调整 oplog 的大小。请改用 replSetResizeOplog
。
例如,以下命令将固定大小集合的大小上限设置为 100000 字节,并将集合中的最大文档数设置为 500:
db.runCommand( { collMod: <collection>, cappedSize: 100000, cappedMax: 500 } )
附带文档前映像和后映像的变更流
6.0 版本中的新功能。
从 MongoDB 6.0 开始,可使用变更流事件来输出更改前后的文档版本(文档前映像和后映像):
前映像是指被替换、更新或删除之前的文档。已插入的文档没有前映像。
后图像是插入、替换或更新后的文档。 已删除的文档没有后图像。
使用
db.createCollection()
、create
或collMod
为集合启用changeStreamPreAndPostImages
。
要使用 collMod
启用集合的 change stream 前图像和后图像,请使用 changeStreamPreAndPostImages
字段:
db.runCommand( { collMod: <collection>, changeStreamPreAndPostImages: { enabled: <boolean> } } )
要启用集合的变更流前图像和后图像,请将 changeStreamPreAndPostImages
设定为 true
。例如:
db.runCommand( { collMod: "orders", changeStreamPreAndPostImages: { enabled: true } } )
要禁用集合的变更流前后映像,请将 changeStreamPreAndPostImages
设为 false
。例如:
db.runCommand( { collMod: "orders", changeStreamPreAndPostImages: { enabled: false } } )
如果图像属于以下情况,则前像和后像不可用于变更流事件:
在文档更新或删除操作时未对集合启用。
在
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 开始,如果您为变更流使用文档前像和后像,则必须使用 collMod
命令为每个集合禁用 changeStreamPreAndPostImages,然后才能降级到更早版本的 MongoDB。
添加评论
可选。您可以为该命令附加注释。评论必须是顶层字段,可以是任何有效的 BSON 类型。您指定的注释会与该命令的记录一起出现在以下位置:
mongod 日志消息,位于
attr.command.cursor.comment
字段中。command.comment
字段中的数据库分析器输出。currentOp
输出,在command.comment
字段。
写关注
可选。一份表达 collMod
命令的写关注文档。
省略以使用默认的写关注。
访问控制
如果部署强制执行身份验证/授权,您必须具有以下特权才能运行 collMod
命令:
内置角色dbAdmin
提供所需的特权。
行为
资源锁定
collMod
命令在操作期间获取指定集合的集合锁。
示例
更改索引的过期值
以下示例更新 user_log
集合上现有 TTL 索引 { lastAccess: 1 }
的 expireAfterSeconds
属性。该索引当前的 expireAfterSeconds
属性设置为 1800
秒(或 30 分钟),示例将该值更改为 3600
秒(或 60 分钟)。
db.runCommand({ collMod: "user_log", index: { keyPattern: { lastAccess: 1 }, expireAfterSeconds: 3600 } })
如果成功,该操作将返回一个文档,其中包含已更改属性的旧值和新值:
{ "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 }
向查询规划器隐藏索引
注意
要隐藏索引,必须将 featureCompatibilityVersion 设置为 5.0
或更大。
下面的示例隐藏了 orders
集合上的现有索引。具体而言,该操作会从查询规划器中隐藏具有规范 { shippedDate: 1 }
的索引。
db.runCommand( { collMod: "orders", index: { keyPattern: { shippedDate: 1 }, hidden: true } } )
如果成功,该操作将返回一个文档,其中包含已更改属性的旧值和新值:
{ "hidden_old" : false, "hidden_new" : true, "ok" : 1 }
注意
如果操作成功但 hidden
值未更改(具体来说,隐藏已隐藏的索引或取消隐藏已取消隐藏的索引),则该命令会从输出中忽略 hidden_old
和 hidden_new
字段。
要隐藏文本索引,您必须通过 name
而非通过 keyPattern
指定该索引。