• Reference >
• Database Commands >
• Administration Commands >
• collMod

collMod

Definition

collMod

collMod makes it possible to add options to a collection or to modify view definitions.

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

• MongoDB removes the MMAPv1 storage engine and the MMAPv1 specific options noPadding and usePowerOf2Sizes for collMod.
• 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.

copy

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

Index Options

index

The index option can change the following properties of an existing index:

Index Property	Description
expireAfterSeconds	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 for expireAfterSeconds expireAfterSeconds_old, the old value for expireAfterSeconds, if the index had a value for expireAfterSeconds before. Modifying the index option expireAfterSeconds resets the $indexStats for the index.
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 and hidden_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 the hidden_old and hidden_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. See also db.collection.hideIndex() db.collection.unhideIndex() 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 is true. The resulting index can be converted to a unique index. To convert the index, use collMod with the unique option. If an existing index is updated so that prepareUnique is true, 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 is true, collMod scans the keyPattern 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 returns CannotConvertIndexToUnique and a list of conflicting documents. To convert an index with duplicate entries to a unique index, correct any reported conflicts and rerun collMod. To end a conversion, set prepareUnique to false. 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:

copy

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>".

See also

• Hidden Indexes
• db.collection.hideIndex()
• db.collection.unhideIndex()

Document Validation

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, and config 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.

validationAction

The validationAction option determines whether to error on invalid documents or just warn 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

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.

Required if modifying a view on a MongoDB deployment that is running with access control.

The view definition is public; i.e. db.getCollectionInfos() and explain 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.

copy

db.runCommand( {
   collMod: "myView",
   viewOn: "activities",
   pipeline: [
     { $match: { status: "Q" } },
     { $project: { user: 1, date: 1, description: 1} } ]
} )

Time Series Collections

To enable automatic removal of documents or change the expireAfterSeconds parameter value for an existing time series collection, issue the following collMod command:

copy

db.runCommand( {
   collMod: <collection>,
   expireAfterSeconds: <Number> || "off"
} )

The expireAfterSeconds field must be either:

• A non-negative decimal number (>=0)
• The string "off".

A number specifies the number of seconds after which documents expire. The string "off" removes the expireAfterSeconds parameter and disables automatic removal.

See also

Set up Automatic Removal for Time Series Collections (TTL)

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 than 0 and less than 1e+15 (1 PB).

cappedMax

Specifies a new maximum number of documents in a capped collection. Setting cappedMax less than or equal to 0 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:

copy

db.runCommand( {
   collMod: <collection>,
   cappedSize: 100000,
   cappedMax: 500
} )

Change Streams with Document Pre- and Post-Images

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 using db.createCollection(), create, or collMod.

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:

copy

db.runCommand( {
   collMod: "orders",
   changeStreamPreAndPostImages: { enabled: true }
} )

To disable change stream pre- and post-images for a collection, set changeStreamPreAndPostImages to false. For example:

copy

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 to 100 seconds:

    copy

    use admin
    db.runCommand( {
       setClusterParameter:
          { changeStreamOptions: { preAndPostImages: { expireAfterSeconds: 100 } } }
    } )
    

  • The following example returns the current changeStreamOptions settings, including expireAfterSeconds:

    copy

    db.adminCommand( { getClusterParameter: "changeStreamOptions" } )
    

  • Setting expireAfterSeconds to off 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. A replace event always includes the post-image.
• To request a pre-image, you set fullDocumentBeforeChange to required or whenAvailable in db.collection.watch(). To request a post-image, you set fullDocument 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 set expireAfterSeconds 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.

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 drop 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	collMod in the database and either: no find on the view to modify, or both find on the view to modify and find on the source collection/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).

copy

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:

copy

{ "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.

copy

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:

copy

{ "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.

See also

• Hidden Indexes
• db.collection.hideIndex()
• db.collection.unhideIndex()

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.

copy

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.

copy

db.contacts.insertOne( { name: "Amanda", status: "Updated" } )

However, since the validationAction is warn only, MongoDB only logs the validation violation message and allows the operation to proceed:

copy

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.

Convert an Existing Index to a Unique Index

Create the apples collection:

copy

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:

copy

db.apples.createIndex( { type: 1 } )

Prepare the index on the type field for conversion:

copy

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:

copy

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:

copy

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.

←   cloneCollectionAsCapped compact  →

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.