Docs Home → Develop Applications → MongoDB Manual
collMod![](/zh-cn/docs/v4.4/assets/link.svg)
On this page
Definition![](/zh-cn/docs/v4.4/assets/link.svg)
collMod
collMod
makes it possible to add options to a collection or to modify view definitions.Tip
In the
mongo
Shell, this command can also be run through thehideIndex()
andunhideIndex()
helper methods.Helper methods are convenient for
mongo
users, but they may not return the same level of information as database commands. In cases where the convenience is not needed or the additional return fields are required, use the database command.Note
The view modified by this command does not refer to materialized views. For discussion of on-demand materialized views, see
$merge
instead.The command takes the following prototype form:
Note
Starting in MongoDB 4.2
The
noPadding
andusePowerOf2Sizes
MMAPv1 options for thecollMod
command are removed. Do not use those options because upgrading from MongoDB 4.0 to 4.2 causes the 4.2 secondary members to immediately halt.The view definition
pipeline
cannot include the$out
or the$merge
stage. If the view definition includes nested pipeline (e.g. the view definition includes$lookup
or$facet
stage), this restriction applies to the nested pipelines as well.
db.runCommand( { collMod: <collection or view>, <option1>: <value1>, <option2>: <value2> ... } ) For the
<collection or view>
, specify the name of a collection or view in the current database.
Options![](/zh-cn/docs/v4.4/assets/link.svg)
Index Options![](/zh-cn/docs/v4.4/assets/link.svg)
index
The
index
option can change the following properties of an existing index:Index PropertyDescriptionexpireAfterSeconds
The number of seconds that determines the expiration threshold of a TTL Collection.
If successful, the command returns a document that contains both the old and new values for the changed property:
expireAfterSeconds_old
andexpireAfterSeconds_new
.You can only modify an existing TTL index; i.e. an index with an existing
expireAfterSeconds
property. If the index does not have an existingexpireAfterSeconds
property, the operation errors withno expireAfterSeconds field to update
.Modifying the index option
expireAfterSeconds
resets the$indexStats
for the index.hidden
A boolen that determines whether the index is hidden or not from the query planner.
If the
hidden
value changes, the command returns a document that contains both the old and new values for the changed property:hidden_old
andhidden_new
.However, if the
hidden
value has not changed (i.e. hiding an already hidden index or unhiding an already unhidden index), the command omits thehidden_old
andhidden_new
fields from the output.To hide an index, you must have featureCompatibilityVersion set to
4.4
or greater.Modifying the index option
hidden
resets the$indexStats
for the index if the value changes.New in version 4.4.
To change index options, specify either the key pattern or name of the existing index and the index option or options you wish to change:
db.runCommand( { collMod: <collection>, index: { keyPattern: <index_spec> || name: <index_name>, expireAfterSeconds: <number>, // If changing the TTL expiration threshold hidden: <boolean> // If changing the visibility of the index from the query planner } } ) If the index does not exist, the command errors with the message
"cannot find index <name|keyPattern> for ns <db.collection>"
.
Document Validation![](/zh-cn/docs/v4.4/assets/link.svg)
validator
New in version 3.2.
validator
allows users to specify validation rules or expressions for a collection. For more information, see Schema Validation.The
validator
option takes a document that specifies the validation rules or expressions. You can specify the expressions using the same operators as the query operators with the exception of$near
,$nearSphere
,$text
, and$where
.Note
Validation occurs during updates and inserts. Existing documents do not undergo validation checks until modification.
You cannot specify a validator for collections in the
admin
,local
, andconfig
databases.You cannot specify a validator for
system.*
collections.
validationLevel
New in version 3.2.
The
validationLevel
determines how strictly MongoDB applies the validation rules to existing documents during an update.validationLevel
Description"off"
No validation for inserts or updates."strict"
Default Apply validation rules to all inserts and all updates."moderate"
Apply validation rules to inserts and to updates on existing valid documents. Do not apply rules to updates on existing invalid documents.
validationAction
New in version 3.2.
The
validationAction
option determines whether toerror
on invalid documents or justwarn
about the violations but allow invalid documents.Important
Validation of documents only applies to those documents as determined by the
validationLevel
.validationAction
Description"error"
Default Documents must pass validation before the write occurs. Otherwise, the write operation fails."warn"
Documents do not have to pass validation. If the document fails validation, the write operation logs the validation failure.
To view the validation specifications for a collection, use the
db.getCollectionInfos()
method.
Views![](/zh-cn/docs/v4.4/assets/link.svg)
Note
The view modified by this command does not refer to materialized
views. For discussion of on-demand materialized views, see
$merge
instead.
viewOn
The underlying source collection or view for the view. The view definition is determined by applying the specified
pipeline
to this source.Required if modifying a view on a MongoDB deployment that is running with access control.
pipeline
The aggregation pipeline that defines the view.
Note
Required if modifying a view on a MongoDB deployment that is running with access control.
The view definition is public; i.e.
db.getCollectionInfos()
andexplain
operations on the view will include the pipeline that defines the view. As such, avoid referring directly to sensitive fields and values in view definitions.
db.runCommand( { collMod: "myView", viewOn: "activities", pipeline: [ { $match: { status: "Q" } }, { $project: { user: 1, date: 1, description: 1} } ] } )
Attach Comment![](/zh-cn/docs/v4.4/assets/link.svg)
New in version 4.4.
Optional. You can attach a comment to this command. The comment must be a top-level field and can be any valid BSON type. The comment that you specify appears alongside records of this command in the following locations:
mongod log messages, in the
attr.command.cursor.comment
field.Database profiler output, in the
command.comment
field.currentOp
output, in thecommand.comment
field.
Write Concern![](/zh-cn/docs/v4.4/assets/link.svg)
Optional. A document expressing the write concern of the collMod
command.
Omit to use the default write concern.
Access Control![](/zh-cn/docs/v4.4/assets/link.svg)
If the deployment enforces authentication/authorization, you must have
the following privilege to run the collMod
command:
The built-in role dbAdmin
provides the required privileges.
Behavior![](/zh-cn/docs/v4.4/assets/link.svg)
Resource Locking![](/zh-cn/docs/v4.4/assets/link.svg)
The collMod
command obtains a collection lock on
the specified collection for the duration of the operation.
Examples![](/zh-cn/docs/v4.4/assets/link.svg)
Change Expiration Value for Indexes![](/zh-cn/docs/v4.4/assets/link.svg)
The following example updates the expireAfterSeconds
property of an
existing TTL index { lastAccess: 1 }
on a collection named
user_log
. The current expireAfterSeconds
property for the index
is set to 1800
seconds (or 30 minutes) and the example changes the
value to 3600
seconds (or 60 minutes).
db.runCommand({ collMod: "user_log", index: { keyPattern: { lastAccess: 1 }, expireAfterSeconds: 3600 } })
If successful, the operation returns a document that includes both the old and new value for the changed property:
{ "expireAfterSeconds_old" : 1800, "expireAfterSeconds_new" : 3600, "ok" : 1 }
Hide an Index from the Query Planner![](/zh-cn/docs/v4.4/assets/link.svg)
Note
To hide an index, you must have featureCompatibilityVersion set to 4.4
or greater. However, once hidden, the
index remains hidden even with featureCompatibilityVersion set to 4.2
on MongoDB 4.4 binaries.
The following example hides an existing
index on the orders
collection. Specifically, the operation hides
the index with the specification { shippedDate: 1 }
from the query
planner.
db.runCommand({ collMod: "orders", index: { keyPattern: { shippedDate: 1 }, hidden: true } })
If successful, the operation returns a document that includes both the old and new value for the changed property:
{ "hidden_old" : false, "hidden_new" : true, "ok" : 1 }
Note
If the operation is successful but the hidden
value has not
changed (i.e. hiding an already hidden index or unhiding an already
unhidden index), the command omits the hidden_old
and
hidden_new
fields from the output.
To hide a text index, you must specify the index by name
and not by
keyPattern
.
Add Document Validation to an Existing Collection![](/zh-cn/docs/v4.4/assets/link.svg)
The following example adds a validator to an existing collection named
contacts
.
Note
MongoDB 3.6 adds the $jsonSchema
operator to support JSON
Schema validation.
db.runCommand( { collMod: "contacts", validator: { $jsonSchema: { bsonType: "object", required: [ "phone" ], properties: { phone: { bsonType: "string", description: "must be a string and is required" }, email: { bsonType : "string", pattern : "@mongodb\.com$", description: "must be a string and match the regular expression pattern" }, status: { enum: [ "Unknown", "Incomplete" ], description: "can only be one of the enum values" } } } }, validationLevel: "moderate", validationAction: "warn" } )
With the moderate
validationLevel
, MongoDB applies
validation rules to insert operations and to update operationss to
existing documents that already fulfill the validation criteria.
Updates to existing documents that do not fulfill the validation
criteria are not checked for validity.
With the warn
validationAction
, MongoDB logs any
violations but allows the insertion or update to proceed.
For example, the following insert operation violates the validation rule.
db.contacts.insert( { name: "Amanda", status: "Updated" } )
However, since the validationAction
is warn
only, MongoDB only
logs the validation violation message and allows the operation to
proceed:
2017-12-01T12:31:23.738-05:00 W STORAGE [conn1] Document would fail validation collection: example.contacts doc: { _id: ObjectId('5a2191ebacbbfc2bdc4dcffc'), name: "Amanda", status: "Updated" }
For more information, see Schema Validation.