validate (database command)

Definition

validate

The validate command checks a collection's data and indexes for correctness and returns the results. The command also repairs any inconsistencies in the count and data size of a collection.

Tip

In mongosh, this command can also be run through the validate() helper method.

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.

Changed in version 5.0.

Starting in version 5.0, the validate command can also find inconsistencies in the collection and fix them if possible.

Index inconsistencies include:

• An index is multikey but there are no multikey fields.

• An index has multikeyPaths covering fields that are not multikey.

• An index does not have multikeyPaths but there are multikey documents (for indexes built before 3.4).

If any inconsistencies are detected by the db.collection.validate() command, a warning is returned and the repair flag on the index is set to true.

db.collection.validate() also validates any documents that violate the collection's schema validation rules.

Note

The validate command does not support views and raises an error when run against a view.

The db.collection.validate() method in mongosh provides a wrapper around validate.

Compatibility

This command is available in deployments hosted in the following environments:

• MongoDB Atlas: The fully managed service for MongoDB deployments in the cloud

• MongoDB Enterprise: The subscription-based, self-managed version of MongoDB

• MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Syntax

The command has the following syntax:

db.runCommand(
   {
     validate: <string>,  // Collection name
     full: <boolean>,  // Optional
     repair: <boolean>,  // Optional, added in MongoDB 5.0
     metadata: <boolean>,  // Optional, added in MongoDB 5.0.4
     checkBSONConformance: <boolean>  // Optional, added in MongoDB 6.2
     background: <boolean> // Optional
   }
)

Command Fields

The command takes the following fields:

db.runCommand( { collMod: <collectionName> } )

Behavior

Examples

• To validate a collection myCollection using the default validation setting (specifically, full: false):

  db.runCommand( { validate: "myCollection" } )

• To perform a full validation of collection myCollection, specify full: true:

  db.runCommand( { validate: "myCollection", full: true } )

• To repair collection myCollection, specify repair: true:

  db.runCommand( { validate: "myCollection", repair: true } )

• To validate the metadata in the myCollection collection, specify metadata: true:

  db.runCommand( { validate: "myCollection", metadata: true } )

• To perform additional BSON conformance checks in myCollection, specify checkBSONConformance: true:

  db.runCommand( { validate: "myCollection", checkBSONConformance: true } )

Validate Output

Specify full: true for more detailed output.

validate.uuid

The universally unique identifier (UUID) for the collection.

New in version 6.2.

validate.nInvalidDocuments

The number of invalid documents in the collection. Invalid documents are those that are not readable, which means the BSON document is corrupt and has an error or a size mismatch.

validate.nNonCompliantDocuments

The number of documents not conforming to the collection's schema. Non-compliant documents are not counted as invalid in nInvalidDocuments.

Starting in MongoDB 6.2, nNonCompliantDocuments also includes the number of documents that do not conform to the BSON or time series collection requirements.

validate.nrecords

The number of documents in the collection.

validate.nIndexes

The number of indexes on the collection that were validated.

validate.keysPerIndex

A document that contains the name and index entry count for each index on the collection.

"keysPerIndex" : {
   "_id_" : <num>,
   "<index2_name>" : <num>,
   ...
}

keysPerIndex identifies the index by its name only.

validate.indexDetails

Changed in version 8.1.

A document that contains the status of the index validation for each index and the index specification.

"indexDetails" : {
   "_id_" : {
      "valid" : <boolean>,
      "spec" : <document>
   },
   "<index2_name>" : {
      "valid" : <boolean>,
      "spec" : <document>
   },
   ...
}

• indexDetails identifies the specific index (or indexes) that is invalid. Earlier versions of MongoDB would mark all indexes as invalid, if any of the indexes were invalid.

• indexDetails identifies the index by its name only. Earlier versions of MongoDB displayed the full namespace of the index; i.e. <db>.<collection>.$<index_name>.

• The spec document is the index specification, which varies depending on how the index is defined. Some example spec document fields include:

  • spec.v. The index version.

  • spec.unique. A Boolean value that indicates if the index is unique.

  • spec.key. The index key identifier.

  • spec.name. The index name.

  New in version 8.1.

validate.ns

The full namespace name of the collection. Namespaces include the database name and the collection name in the form database.collection.

validate.valid

A boolean that is true if validate determines that all aspects of the collection are valid. When false, see the errors field for more information.

validate.repaired

A boolean that is true if validate repaired the collection.

validate.repairMode

New in version 8.2.

A string that indicates what types of data inconsistencies the validate command attempted to repair, if detected. Possible repairMode values include:

• None: No repair actions are taken.

• FixErrors: Attempts to fix any validation errors.

• AdjustMultikey: Attempts to fix multikey inconsistencies by adjusting multikey metadata.

validate.warnings

An array that contains warning messages, if any, regarding the validate operation itself. The warning messages do not indicate that the collection is itself invalid. For example:

"warnings" : [
   "Could not complete validation of table:collection-28-6471619540207520785. This is a transient issue as the collection was actively in use by other operations."
],

validate.errors

If the collection is not valid (i.e valid is false), this field will contain a message describing the validation error.

validate.extraIndexEntries

An array that contains information for each index entry that points to a document that does not exist in the collection.

"extraIndexEntries" : [
   {
      "indexName" : <string>,
      "recordId" : <NumberLong>,  // for the non-existent document
      "indexKey" : {
         "<key1>" : <value>,
         ...
      }
   }
   ...
]

Note

For the extraIndexEntries array, the sum of all the indexKey field sizes has a limit of 1MB where the sizes include both the keys and values for the indexKey. If the sum exceeds this size, the warning field displays a message.

validate.missingIndexEntries

An array that contains information for each document that is missing the corresponding index entry.

"missingIndexEntries" : [
   {
      "indexName" : <string>,
      "recordId" : <NumberLong>,
      "idKey" : <_id key value>,     // The _id value of the document. Only present if an ``_id`` index exists.
      "indexKey" : {                 // The missing index entry
         "<key1>" : <value>,
         ...
      }
   }
   ...
 ]

Note

For the missingIndexEntries array, the sum of the idKey field size and all its indexKey field sizes has a limit of 1MB where the field sizes include both the keys and values for the idKey and indexKey. If the sum exceeds this size, the warning field displays a message.

validate.corruptRecords

An array of RecordId values for documents that are unreadable, possibly because the data is damaged. These documents are reported as corrupt during validation. A RecordId is a 64-bit integer internal key that uniquely identifies a document in a collection.

"corruptRecords" : [
   Long(1),  // RecordId 1
   Long(2)   // RecordId 2
]

New in version 5.0.

validate.ok

An integer with the value 1 when the command succeeds. If the command fails the ok field has a value of 0.