collMod
On this page
- Definition
- Syntax
- Options
- Change Index Properties
- Validate Documents
- Modify Views
- Modify Time Series Collections
- Resize a Capped Collection
- Change Streams with Document Pre- and Post-Images
- Write Concern
- Access Control
- Behavior
- Resource Locking
- Examples
- Change Expiration Value for Indexes
- Hide an Index from the Query Planner
- Convert an Existing Index to a Unique Index
Definition
collMod
collMod
makes it possible to add options to a collection or to modify view definitions.Tip
In
mongosh
, this command can also be run through thehideIndex()
andunhideIndex()
helper methods.Helper methods are convenient for
mongosh
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.
Syntax
The command has the following syntax:
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.A view definition
pipeline
cannot include the$out
or the$merge
stage. This restriction also applies to embedded pipelines, such as pipelines used in$lookup
or$facet
stages.
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
Change Index Properties
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:
expireAfterSeconds_new
, the new value forexpireAfterSeconds
expireAfterSeconds_old
, the old value forexpireAfterSeconds
, if the index had a value forexpireAfterSeconds
before.
Modifying the index option
expireAfterSeconds
resets the$indexStats
for the index.If you use TTL indexes created before MongoDB 5.0, or if you want to sync data created in MongDB 5.0 with a pre-5.0 installation, see Indexes Configured Using NaN to avoid misconfiguration issues.
hidden
A boolean 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.
prepareUnique
A boolean that determines whether the index will accept new duplicate entries.
New duplicate entries fail with DuplicateKey errors when
prepareUnique
istrue
. The resulting index can be converted to a unique index. To convert the index, usecollMod
with theunique
option.If an existing index is updated so that
prepareUnique
istrue
, the index is not checked for pre-existing, duplicate index entries.New in version 6.0.
unique
A boolean that determines whether or not the index is unique.
When
unique
istrue
,collMod
scans thekeyPattern
index for duplicates and then converts it to a unique index if there are no duplicate index entries.If duplicates are detected during the initial scan,
collMod
returnsCannotConvertIndexToUnique
and a list of conflicting documents. To convert an index with duplicate entries to a unique index, correct any reported conflicts and reruncollMod
.To end a conversion, set
prepareUnique
tofalse
.New in version 6.0.
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>, // 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 } } ) If the index does not exist, the command errors with the message
"cannot find index <name|keyPattern> for ns <db.collection>"
.
Validate Documents
validator
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
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.To see an example that uses
validationLevel
, see Specify Validation Level for Existing Documents.
validationAction
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
.To see an example that uses
validationAction
, see Choose How to Handle Invalid Documents.
Modify 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
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} } ] } )
Modify Time Series Collections
expireAfterSeconds
Note
This is distinct from using the
index
option with theexpireAfterSeconds
property to change the expiration time for a TTL Collection.To enable automatic document removal or modify the current expiration interval for a time series collection, change the
expireAfterSeconds
value:db.runCommand( { collMod: <collection>, expireAfterSeconds: <number> || "off" } ) Set
expireAfterSeconds
to"off"
to disable automatic removal, or a non-negative decimal number (>=0
) to specify the number of seconds after which documents expire.
timeseries-granularity
To modify the granularity of a time series collection, change the
timeseries.granularity
value:db.runCommand({ collMod: "weather24h", timeseries: { granularity: "seconds" || "minutes" || "hours" } }) You cannot decrease granularity. For example, if granularity is set to
minutes
, you can increase it tohours
, but you cannot decrease it toseconds
.The following table shows the maximum time interval included in one bucket of data when using a given
granularity
value:granularity
Covered Time Span"seconds"
(default)one hour"minutes"
24 hours"hours"
30 daysImportant
As with all system collections, do not run any operations on the underlying
system.buckets
collection.
Resize a Capped Collection
New in version 6.0.
Starting in MongoDB 6.0, you can resize a capped collection. To change a
capped collection's maximum size in
bytes, use the cappedSize
option. To change the maximum number of
documents in an existing capped collection, use the cappedMax
option.
Note
You can't use these commands to resize the oplog. Use
replSetResizeOplog
instead.
cappedSize
Specifies a new maximum size, in bytes, for a capped collection.
cappedSize
must be greater than0
and less than1e+15
(1 PB).
cappedMax
Specifies a new maximum number of documents in a capped collection. Setting
cappedMax
less than or equal to0
implies no limit.
For example, the following command sets the maximum size of a capped collection to 100000 bytes and sets the maximum number of documents in the collection to 500:
db.runCommand( { collMod: <collection>, cappedSize: 100000, cappedMax: 500 } )
Change Streams with Document Pre- and Post-Images
New in version 6.0.
Starting in MongoDB 6.0, you can use change stream events to output the version of a document before and after changes (the document pre- and post-images):
The pre-image is the document before it was replaced, updated, or deleted. There is no pre-image for an inserted document.
The post-image is the document after it was inserted, replaced, or updated. There is no post-image for a deleted document.
Enable
changeStreamPreAndPostImages
for a collection usingdb.createCollection()
,create
, orcollMod
.
To use collMod
to enable change stream pre- and post-images
for a collection, use the changeStreamPreAndPostImages
field:
db.runCommand( { collMod: <collection>, changeStreamPreAndPostImages: { enabled: <boolean> } } )
To enable change stream pre- and post-images for a collection, set
changeStreamPreAndPostImages
to true
. For example:
db.runCommand( { collMod: "orders", changeStreamPreAndPostImages: { enabled: true } } )
To disable change stream pre- and post-images for a collection, set
changeStreamPreAndPostImages
to false
. For example:
db.runCommand( { collMod: "orders", changeStreamPreAndPostImages: { enabled: false } } )
Pre- and post-images are not available for a change stream event if the images were:
Not enabled on the collection at the time of a document update or delete operation.
Removed after the pre- and post-image retention time set in
expireAfterSeconds
.The following example sets
expireAfterSeconds
to100
seconds:use admin db.runCommand( { setClusterParameter: { changeStreamOptions: { preAndPostImages: { expireAfterSeconds: 100 } } } } ) The following example returns the current
changeStreamOptions
settings, includingexpireAfterSeconds
:db.adminCommand( { getClusterParameter: "changeStreamOptions" } ) Setting
expireAfterSeconds
tooff
uses the default retention policy: pre- and post-images are retained until the corresponding change stream events are removed from the oplog.If a change stream event is removed from the oplog, then the corresponding pre- and post-images are also deleted regardless of the
expireAfterSeconds
pre- and post-image retention time.
Additional considerations:
Enabling pre- and post-images consumes storage space and adds processing time. Only enable pre- and post-images if you need them.
Limit the change stream event size to less than 16 megabytes. To limit the event size, you can:
Limit the document size to 8 megabytes. You can request pre- and post-images simultaneously in the change stream output if other change stream event fields like
updateDescription
are not large.Request only post-images in the change stream output for documents up to 16 megabytes if other change stream event fields like
updateDescription
are not large.Request only pre-images in the change stream output for documents up to 16 megabytes if:
document updates affect only a small fraction of the document structure or content, and
do not cause a
replace
change event. Areplace
event always includes the post-image.
To request a pre-image, you set
fullDocumentBeforeChange
torequired
orwhenAvailable
indb.collection.watch()
. To request a post-image, you setfullDocument
using the same method.Pre-images are written to the
config.system.preimages
collection.The
config.system.preimages
collection may become large. To limit the collection size, you can setexpireAfterSeconds
time for the pre-images as shown earlier.Pre-images are removed asynchronously by a background process.
Important
Backward-Incompatible Feature
Starting in MongoDB 6.0, if you are using document pre- and post-images
for change streams, you must disable
changeStreamPreAndPostImages for each collection using
the collMod
command before you can downgrade to an earlier
MongoDB version.
Tip
See also:
For change stream events and output, see Change Events.
To watch a collection for changes, see
db.collection.watch()
.For complete examples with the change stream output, see Change Streams with Document Pre- and Post-Images.
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:
Task | Required Privileges |
---|---|
Modify a non-capped collection | collMod in the database |
Modify a view |
The built-in role dbAdmin
provides the required privileges.
Behavior
Resource Locking
The collMod
command obtains an exclusive lock on the
parent database of the specified collection for the duration of the
operation. All subsequent operations on the database and all its
collections must wait until collMod
releases the lock.
Examples
Change Expiration Value for Indexes
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
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
.
Convert an Existing Index to a Unique Index
Create the apples
collection:
db.apples.insertMany( [ { type: "Delicious", quantity: 12 }, { type: "Macintosh", quantity: 13 }, { type: "Delicious", quantity: 13 }, { type: "Fuji", quantity: 15 }, { type: "Washington", quantity: 10 }, ] )
Add a single field index on type
:
db.apples.createIndex( { type: 1 } )
Prepare the index on the type
field for conversion:
db.runCommand( { collMod: "apples", index: { keyPattern: { type: 1 }, prepareUnique: true } } )
The existing index may contain duplicate entries, but it will not
accept new documents that duplicate an index entry when
prepareUnique
is true
.
Try to insert a document with a duplicate index value:
db.apples.insertOne( { type: "Delicious", quantity: 200 } )
The operation returns an error. The index will not accept new duplicate entries.
Use the unique``option to convert the index to a unique index.
``collMod
checks the collection for duplicate index entries before
converting the index:
db.runCommand( { collMod: "apples", index: { keyPattern: { type: 1 }, unique: true } } )
The response to this operation varies by driver. You will always receive an error message about the duplicate entries.
"errmsg" : "Cannot convert the index to unique. Please resolve conflicting documents before running collMod again."
Some drivers also return a list of ObjectIds
for the duplicate
entries:
{ "ok" : 0, "errmsg" : "Cannot convert the index to unique. Please resolve \ conflicting documents before running collMod again.", "code" : 359, "codeName" : "CannotConvertIndexToUnique", "violations" : [ { "ids" : [ ObjectId("62a2015777e2d47c4da33146"), ObjectId("62a2015777e2d47c4da33148") ] } ] }
To complete the conversion, modify the duplicate entries to remove any
conflicts and re-run collMod()
with the unique
option.