What does MongoDB's `validate` command check on a collection, what does it lock, and what do `full` and `background` change?
answer
- one collection, one member
- documents and indexes against each other
- exclusive lock unless told otherwise
- storage-engine verify versus last stable checkpoint
- ok is not valid
basics
~10 sMongoDB's validate scans one collection's documents and indexes for damage on one member. By default it holds an exclusive collection lock; full adds storage-engine verification, while background reads the last stable checkpoint without blocking.
solid answer
~50 s`validate` checks one collection on the member you run it on: documents are readable, conformant BSON, index entries match records and are in order, unique indexes hold no duplicates, and catalog metadata agrees with memory. A plain run takes an exclusive collection lock, so reads and writes on that collection wait, and it corrects the stored count and data size. `full: true` keeps that lock and adds WiredTiger's own `verify()` on the record store and every index. `background: true` is the online form: it takes no exclusive lock and reads the last stable checkpoint, but it works only on a replica set and rejects `full` and `repair`. Read `valid` in the reply, not `ok`: `ok: 1` only means the command ran. It is not a schema check, although it does count documents that break a validator in `nNonCompliantDocuments`.
code
javascript · 8 lines// Default: exclusive collection lock
db.runCommand({ validate: "orders" })
// Adds WiredTiger verify() on the record store and each index
db.runCommand({ validate: "orders", full: true })
// Replica set only: reads the last stable checkpoint, no exclusive lock
db.runCommand({ validate: "orders", background: true })go deeper
Recall that validate is an integrity check on one collection's documents and indexes, and that it is not the same thing as a schema validator on writes.
Explain the exclusive lock of a plain run, what full adds through WiredTiger verify, how background reads a checkpoint, and why you read valid rather than ok.
Show you would not run a foreground validate on a busy primary, would pick the member and the moment deliberately, and would treat a could-not-complete warning as an unfinished check.
Frame it as a cost decision: exclusive lock and thoroughness against online coverage, and which incidents justify taking a member out of rotation to get a trustworthy answer.
## What `validate` is for The `validate` command answers one question: **is this collection's stored data internally consistent on this member?** It is an integrity check over storage structures. It is unrelated to making a collection reject bad writes, which is what a `$jsonSchema` validator does, even though the two words look alike. It runs against a single collection, and it inspects only the `mongod` you are connected to, so a clean result on one member says nothing about the others. A run looks at these things: - **Documents:** each record is readable, conformant BSON. Unreadable records land in `corruptRecords` and count in `nInvalidDocuments`. - **Index entries against records:** a document with no matching entry appears in `missingIndexEntries`, and an entry pointing at no document appears in `extraIndexEntries`. - **Index order and uniqueness:** entries follow the index's sort order, and unique indexes hold no duplicate keys. - **Multikey metadata:** an index's multikey flags and paths match the documents. - **Catalog state:** the durable catalog entry and the in-memory collection agree. - **Count and data size:** a foreground run corrects the fast count that `collStats` reports. An unclean shutdown can leave these inaccurate. ## The validator nuance `validate` does not enforce schema, but it does look. It evaluates each readable document against the collection's validator and counts violators in `nNonCompliantDocuments`, adding a warning. The source explains why this stays a warning: documents can legitimately bypass validation when inserted or updated. So `valid` stays `true` on an ordinary collection with such documents. Time-series collections differ, because their bucket schema is required and a violation there is recorded as an error. ## What each form locks and does | Form | Lock on the collection | What it adds | Limits | |---|---|---|---| | `{ validate: "c" }` | Exclusive | Documents, indexes, corrected counts | Blocks that collection's reads and writes | | `full: true` | Exclusive | WiredTiger `verify()` on the record store and each index | Slowest; on the oplog the extra check is skipped with a warning | | `background: true` | Intent only, no exclusive lock | Reads the last stable checkpoint | Replica set and replicated collections only; no `full`, no `repair` | | `checkBSONConformance: true` | Follows the form it joins | The time-consuming BSON checks | Not with `repair` or `metadata` | | `metadata: true` | Exclusive, but scans no data | Finds invalid index options quickly | Cannot combine with any other option | Three consequences matter in practice: 1. **A foreground run is an outage for that collection.** The manual warns that on a secondary the command can block all other operations on that member until it finishes, and it suggests running validation on secondaries, stepping a primary down with `rs.stepDown()` first when the primary is the one you must check. 2. **Background sees the past.** It reads a checkpoint, so the newest writes are not covered, it cannot correct counts, and it returns an error if no checkpoint exists yet or the snapshot history has gone. It is also not throttled unless you set `maxValidateMBperSec`, whose default of 0 means no limit. 3. **Only one validation per collection runs at a time.** A second command on the same namespace waits for the first. ## Reading the reply - **`ok`** says the command completed. **`valid`** says what it found. A damaged collection gives `ok: 1` and `valid: false`, plus an `advice` string pointing to recovery steps. - **`errors`** explains a `false`. In 9.0, a key-extraction failure on a `2dsphere` index gives a bounded message that names the index and path and refers to log id 12565600 for the failing document. - **`warnings`** are about the run or about non-fatal findings and do not mean the collection is invalid. On a busy collection, `full` can report that it `Could not complete validation` and call it transient; that means the verify was not finished, not that the data is good. - **`indexDetails`** gives `valid` per index, so you can see which one is at fault. `keysPerIndex` gives entry counts by index name. ## Where this fits Use `validate` when you have a reason to doubt storage: after a disk fault, an unclean shutdown you distrust, or an unexplained query error on one member. It is a poor routine health probe on a live primary because of the lock and the time it takes on large collections. Running it requires the `validate` privilege action on the database or collection. For comparing members to each other, `validate` is the wrong tool, since it never looks past the one member it runs on.
- Why might you still get a warning that `validate` could not complete, even with `full: true`?On WiredTiger, `full` calls `verify()` on each table, and that call can find the table busy. The server then adds a warning that it `Could not complete validation` and calls it a transient issue because the collection was in use. It does not mark the collection invalid, but the verify step did not finish, so re-run it rather than treating that run as a clean bill of health.
- What can `background: true` miss that a foreground run would catch?It reads the last stable checkpoint, so writes after that checkpoint are out of view. It also does not enforce or correct the fast count, because that needs exclusive access. It rejects `full`, so WiredTiger's `verify()` never runs. It is a good online screen for documents and indexes, not a substitute for a full check on a member you already distrust.
- validate enforces the collection's $jsonSchema rules on documents already stored
- An ok: 1 reply from validate means the collection is healthy
- You can combine background: true with full: true for a thorough online check
- Running validate on a secondary cannot affect that secondary's other work
- A valid: true reply proves every document satisfies the collection's validator
- A clean validate on one member shows that the whole replica set is clean
Assumes MongoDB 9.0, read from the r9.0.4 source; the bounded 2dsphere error message in the errors array is new in 9.0.