In MongoDB, what does a unique index enforce, and what happens when a write violates it?

## What a unique index is A MongoDB index is normally just an access path: a sorted structure that lets the planner find documents without scanning the whole collection. Adding `unique: true` turns that access path into a **constraint** as well. The server refuses to store two index entries with the same key, and because the index is maintained inside the same write that modifies the document, the check is atomic with the write — there is no window in which a duplicate briefly exists. ```javascript db.users.createIndex({ email: 1 }, { unique: true }) ``` ## What a violation looks like An `insertOne`, `updateOne`, `replaceOne`, an upsert or a `bulkWrite` operation that would produce a second entry with an existing key fails with a **duplicate key error, code 11000**, usually printed as `E11000 duplicate key error collection: app.users index: email_1 dup key: { email: "[email protected]" }`. The important part is what does *not* happen: the existing document is not overwritten, the duplicate is not silently dropped, and the index is not left in a half-built state. The offending write simply does not apply. In an unordered `bulkWrite` the other operations in the batch still run and the duplicates come back in the write-error list; in an ordered bulk write, processing stops at the first failure. Application code normally catches error code 11000 specifically and turns it into a domain-level "already taken" response rather than a 500. ## Compound unique indexes On `{ tenantId: 1, slug: 1 }` with `unique: true`, uniqueness is over the **tuple**, not over each field. These two documents coexist happily: ```json { "tenantId": "acme", "slug": "welcome" } { "tenantId": "globex", "slug": "welcome" } ``` and only a second `{ "tenantId": "acme", "slug": "welcome" }` is rejected. This is the standard way to express "unique per tenant", "one vote per user per poll", and similar scoped constraints. Candidates who assume a compound unique index makes each column unique individually get this wrong in interviews constantly. ## Building on existing data `createIndex(..., { unique: true })` scans the collection first. If it finds two documents that already share a key, the build **fails** and no index is created; you have to find and repair the duplicates before retrying. Very old MongoDB versions had a `dropDups` option that deleted the offending documents automatically — it was removed long ago, and proposing it is a dated answer. ## Missing fields and null A field that is absent from a document is still indexed, as the value `null`. Under a plain unique index that means at most **one** document in the collection may omit the field, which is almost never what you want for an optional attribute such as an optional `taxId`. The modern fix is a partial index whose `partialFilterExpression` restricts the index to documents that actually carry the field, so uniqueness applies only inside that subset. ## Arrays and multikey uniqueness If the indexed field holds an array, the index is multikey: one entry per array element. A unique multikey index therefore forbids the *same element value* from appearing in two different documents, and also forbids a single document from containing the same value twice in that array. That is occasionally exactly what you want (globally unique tags) and more often a surprise. ## Sharded collections On a sharded collection, a unique index can only be enforced if its key is prefixed by the shard key. The reason is mechanical: each shard maintains its own indexes, so nothing on shard A can see the keys stored on shard B. Only when the shard key is a prefix does the routing guarantee that all documents with a given key land on the same shard, which makes a local index check sufficient. Wanting `email` globally unique on a collection sharded by `userId` is one of the most common design walls teams hit; the usual answers are to choose the shard key so it prefixes the constraint, or to keep a small separate collection whose `_id` is the value that must be unique and write to it first. ## Practical notes The `_id` index exists on every collection, is unique, and cannot be dropped, hidden, or made partial. Application-level "check then insert" is not a substitute for a unique index: two concurrent requests can both pass the check. Treat the index as the source of truth and the pre-check as a UX nicety.