Unique Indexes

A unique index ensures that the indexed fields do not store duplicatevalues; i.e. enforces uniqueness for the indexed fields. By default,MongoDB creates a unique index on the _idfield during the creation of a collection.

New Internal Format

Starting in MongoDB 4.2, for featureCompatibilityVersion (fCV) of 4.2 (or greater), MongoDB uses a new internalformat for unique indexes that is incompatible with earlier MongoDBversions. The new format applies to both existing unique indexes aswell as newly created/rebuilt unique indexes.

Create a Unique Index

To create a unique index, use the db.collection.createIndex()method with the unique option set to true.

db.collection.createIndex( <key and index type specification>, { unique: true } )

Unique Index on a Single Field

For example, to create a unique index on the user_id field of themembers collection, use the following operation in themongo shell:

db.members.createIndex( { "user_id": 1 }, { unique: true } )

Unique Compound Index

You can also enforce a unique constraint on compound indexes. If you use the unique constraint on acompound index, then MongoDB will enforceuniqueness on the combination of the index key values.

For example, to create a unique index on groupNumber, lastname,and firstname fields of the members collection, use thefollowing operation in the mongo shell:

db.members.createIndex( { groupNumber: 1, lastname: 1, firstname: 1 }, { unique: true } )

The created index enforces uniqueness for the combination ofgroupNumber, lastname, and firstname values.

For another example, consider a collection with the following document:

{ _id: 1, a: [ { loc: "A", qty: 5 }, { qty: 10 } ] }

Create a unique compound multikey indexon a.loc and a.qty:

db.collection.createIndex( { "a.loc": 1, "a.qty": 1 }, { unique: true } )

The unique index permits the insertion of the following documents intothe collection since the index enforces uniqueness for thecombination of a.loc and a.qty values:

db.collection.insert( { _id: 2, a: [ { loc: "A" }, { qty: 5 } ] } )
db.collection.insert( { _id: 3, a: [ { loc: "A", qty: 10 } ] } )

See also

Unique Constraint Across Separate Documents and Unique Index and Missing Field

Behavior

Restrictions

MongoDB cannot create a unique index on thespecified index field(s) if the collection already contains data thatwould violate the unique constraint for the index.

You may not specify a unique constraint on a hashedindex.

Building Unique Index on Replica Sets and Sharded Clusters

For replica sets and sharded clusters, using a rolling procedure to create a unique indexrequires that you stop all writes to the collection during theprocedure. If you cannot stop all writes to the collection during theprocedure, do not use the rolling procedure. Instead, build your unique indexon the collection by:

• issuing db.collection.createIndex() on the primary for areplica set, or
• issuing db.collection.createIndex() on themongos for a sharded cluster.

Unique Constraint Across Separate Documents

The unique constraint applies to separate documents in the collection.That is, the unique index prevents separate documents from having thesame value for the indexed key.

Because the constraint applies to separate documents, for a uniquemultikey index, a document may have arrayelements that result in repeating index key values as long as the indexkey values for that document do not duplicate those of anotherdocument. In this case, the repeated index entry is inserted into theindex only once.

For example, consider a collection with the following documents:

{ _id: 1, a: [ { loc: "A", qty: 5 }, { qty: 10 } ] }
{ _id: 2, a: [ { loc: "A" }, { qty: 5 } ] }
{ _id: 3, a: [ { loc: "A", qty: 10 } ] }

Create a unique compound multikey index on a.loc and a.qty:

db.collection.createIndex( { "a.loc": 1, "a.qty": 1 }, { unique: true } )

The unique index permits the insertion of the following document intothe collection if no other document in the collection has an index keyvalue of { "a.loc": "B", "a.qty": null }.

db.collection.insert( { _id: 4, a: [ { loc: "B" }, { loc: "B" } ] } )

Unique Index and Missing Field

If a document does not have a value for the indexed field in a uniqueindex, the index will store a null value for this document. Because ofthe unique constraint, MongoDB will only permit one document that lacksthe indexed field. If there is more than one document without a valuefor the indexed field or is missing the indexed field, the index buildwill fail with a duplicate key error.

For example, a collection has a unique index on x:

db.collection.createIndex( { "x": 1 }, { unique: true } )

The unique index allows the insertion of a document without the fieldx if the collection does not already contain a document missing thefield x:

db.collection.insert( { y: 1 } )

However, the unique index errors on the insertion of a document withoutthe field x if the collection already contains a document missingthe field x:

db.collection.insert( { z: 1 } )

The operation fails to insert the document because of the violation ofthe unique constraint on the value of the field x:

WriteResult({
   "nInserted" : 0,
   "writeError" : {
      "code" : 11000,
      "errmsg" : "E11000 duplicate key error index: test.collection.$a.b_1 dup key: { : null }"
   }
})

See also

Unique Partial Indexes

Unique Partial Indexes

New in version 3.2.

Partial indexes only index the documents in a collection that meet aspecified filter expression. If you specify both thepartialFilterExpression and a unique constraint, the unique constraint only applies to thedocuments that meet the filter expression.

A partial index with a unique constraint does not prevent the insertionof documents that do not meet the unique constraint if the documents donot meet the filter criteria. For an example, seePartial Index with Unique Constraint.

Sharded Clusters and Unique Indexes

You cannot specify a unique constraint on a hashed index.

For a ranged sharded collection, only the following indexes can beunique:

• the index on the shard key

• a compound index where the shard key is a prefix

• the default _id index; however, the _id index onlyenforces the uniqueness constraint per shard if the _id fieldis not the shard key or the prefix of the shard key.

Uniqueness and the _id Index

If the _id field is not the shard key or the prefix of theshard key, _id index only enforces the uniqueness constraintper shard and not across shards.

For example, consider a sharded collection (with shard key {x:1}) that spans two shards A and B. Because the _id key isnot part of the shard key, the collection could have a documentwith _id value 1 in shard A and another document with_id value 1 in shard B.

If the _id field is not the shard key nor the prefix of theshard key, MongoDB expects applications to enforce the uniquenessof the _id values across the shards.

The unique index constraints mean that:

• For a to-be-sharded collection, you cannot shard the collection ifthe collection has other unique indexes.
• For an already-sharded collection, you cannot create unique indexeson other fields.