collMod¶

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 both the old and new values for the changed property: expireAfterSeconds_old and expireAfterSeconds_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 existing expireAfterSeconds property, the operation errors with no 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 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() and db.collection.unhideIndex(). New in version 4.4.版本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>".

See also参阅

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

Document Validation¶

validator¶

New in version 3.2.版本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, and config databases.
• You cannot specify a validator for system.* collections.

validationLevel¶

New in version 3.2.版本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.版本3.2中的新功能。

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¶

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() 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.

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

Write Concern¶

Optional. A document expressing the write concern of the drop command.

Omit to use the default write concern.

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.

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¶

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 }

To hide a text index, you must specify the index by name and not by keyPattern.

Add Document Validation to an Existing Collection¶

The following example adds a validator to an existing collection named contacts.

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.