validate
Definition
Changed in version 6.2.
validate
The
validate
command checks a collection's data and indexes for correctness and returns the results.Tip
In
mongosh
, this command can also be run through thevalidate()
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 totrue
.db.collection.validate()
also validates any documents that violate the collection's schema validation rules.The
db.collection.validate()
method inmongosh
provides a wrapper aroundvalidate
.
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 } )
Command Fields
The command takes the following fields:
Field | Type | Description | |
---|---|---|---|
validate | string | The name of the collection to validate. | |
boolean | Optional. A flag that determines whether the command performs a slower but more thorough check or a faster but less thorough check.
The default is Starting in MongoDB 3.6, for the WiredTiger storage engine, only the
In previous versions, the data validation process for the WT storage engine always forces a checkpoint. | ||
boolean | Optional. A flag that determines whether the command performs a repair.
The default is A repair can only be run on a standalone node. The repair fixes these issues:
New in version 5.0. | ||
boolean | Optional. A flag which allows users to perform a quick validation to detect invalid index options without scanning all of the documents and indexes.
The default is Running the validate command with The
The If there is an invalid index detected, the validate command will prompt
you to use the
New in version 5.0.4. | ||
boolean | Optional. If
New in version 6.2. |
Behavior
Performance
The validate
command can be slow, particularly on
larger data sets.
The validate
command obtains an exclusive lock W
on
the collection. This will block all reads and writes on the collection
until the operation finishes. When run on a secondary, the
validate
operation can block all other operations on that
secondary until it finishes.
Warning
Due to the performance impact of validation, consider running
validate
only on secondary replica set nodes.
You can use rs.stepDown()
to instruct the current
primary node to become a secondary to avoid impacting a live
primary node.
Data Throughput Metrics
Starting in version MongoDB 4.4,
The
$currentOp
and thecurrentOp
command includedataThroughputAverage
anddataThroughputLastSecond
information for validate operations in progress.The log messages for validate operations include
dataThroughputAverage
anddataThroughputLastSecond
information.
Collection Validation Improvements
Starting in MongoDB 6.2, the validate
command and
db.collection.validate()
method:
Check collections to ensure the BSON documents conform to the BSON specifications.
Check time series collections for internal data inconsistencies.
Have a new option
checkBSONConformance
that enables comprehensive BSON checks.
Restrictions
MongoDB drivers automatically set afterClusterTime for operations associated with causally
consistent sessions. Starting in MongoDB 4.2, the
validate
command no longer supports afterClusterTime. As such, validate
cannot be
associated with causally consistent sessions.
Index Key Format
Starting in MongoDB 6.0, the validate
command returns a message if a
unique index has a key format that is
incompatible. The message indicates an old format is used.
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
Note
The output may vary depending on the version and specific configuration of your MongoDB instance.
Specify full: true for more detailed output.
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.keysPerIndex
A document that contains the name and index entry count for each index on the collection.
"keysPerIndex" : { "_id_" : <num>, "<index2_name>" : <num>, ... } Starting in MongoDB 4.2 (and 4.0.10+ and 3.6.13+),
keysPerIndex
identifies the index by its name only. Earlier versions of MongoDB displayed the full namespace of the index; i.e.<db>.<collection>.$<index_name>
validate.indexDetails
A document that contains the status of the index validation for each index.
"indexDetails" : { "_id_" : { "valid" : <boolean> }, "<index2_name>" : { "valid" : <boolean> }, ... } Starting in MongoDB 4.2 (and 4.0.10+ and 3.6.13+),
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>
.
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
ifvalidate
determines that all aspects of the collection are valid. Whenfalse
, see theerrors
field for more information.
validate.repaired
A boolean that is
true
ifvalidate
repaired the collection.
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 theindexKey
field sizes has a limit of 1MB where the sizes include both the keys and values for theindexKey
. If the sum exceeds this size, the warning field displays a message.Available starting in MongoDB 4.2 (and 4.0.10+ and 3.6.13+)
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 theidKey
field size and all itsindexKey
field sizes has a limit of 1MB where the field sizes include both the keys and values for theidKey
andindexKey
. If the sum exceeds this size, the warning field displays a message.Available starting in MongoDB 4.2 (and 4.0.10+ and 3.6.13+)
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. ARecordId
is a 64-bit integer internal key that uniquely identifies a document in a collection."corruptRecords" : [ NumberLong(1), // RecordId 1 NumberLong(2) // RecordId 2 ] New in version 5.0.
validate.ok
An integer with the value
1
when the command succeeds. If the command fails theok
field has a value of0
.