- Reference >
- Database Commands >
- Administration Commands >
- collMod
collMod¶
On this page
Definition¶
-
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 the
hideIndex
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:
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.
For the
<collection or view>
, specify the name of a collection or view in the current database.Use the
userFlags
field in thedb.collection.stats()
output to check the options enabled for a collection.- The
Options¶
TTL Collections¶
-
index
¶ The
index
option changes the expiration time of a TTL Collection.Specify the key or index name, and new expiration time with a document of the form:
In this example,
<index_spec>
is an existing index in the collection. In cases of multiple indexes with the same key pattern, the user is required to specify the index by name.seconds
is the number of seconds to subtract from the current time.On success
collMod
returns a document with fieldsexpireAfterSeconds_old
andexpireAfterSeconds_new
set to their respective values.On failure,
collMod
returns a document withno expireAfterSeconds field to update
if there is no existingexpireAfterSeconds
field orcannot find index { **key**: 1.0 } for ns **namespace**
if the specifiedkeyPattern
does not exist.
Document Validation¶
-
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 :$geoNear
,$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¶
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
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.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.
Write Concern¶
Optional. A document expressing the write concern of the collMod
command.
Omit to use the default write concern.
Access Control¶
If the deployment enforces authentication/authorization, you must have
the following privilege to run the collMod
command:
Required Privileges | |
---|---|
Modify a non-capped collection | collMod in the database |
Modify a view |
|
The built-in role dbAdmin
provides the required privileges.
Behavior¶
Examples¶
Change Expiration Value for Indexes¶
To update the expiration value for a collection
named sessions
indexed on a lastAccess
field from 30
minutes to 60 minutes, use the following operation:
Which will return the document:
Add Document Validation to an Existing Collection¶
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.
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.
However, since the validationAction
is warn
only, MongoDB only
logs the validation violation message and allows the operation to
proceed:
For more information, see Schema Validation.