Unique Indexes¶

On this page

Behavior

A unique index causes MongoDB to reject all documents that contain a duplicate value for the indexed field.

To create a unique index, use the db.collection.createIndex() method with the unique option set to true. For example, to create a unique index on the user_id field of the members collection, use the following operation in the mongo shell:

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

By default, unique is false on MongoDB indexes.

If you use the unique constraint on a compound index, then MongoDB will enforce uniqueness on the combination of values rather than the individual value for any or all values of the key.

Behavior¶

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 the same value for the indexed key, but the index does not prevent a document from having multiple elements or embedded documents in an indexed array from having the same value. In the case of a single document with repeating values, the repeated value is inserted into the index only once.

For example, a collection has a unique index on a.b:

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

The unique index permits the insertion of the following document into the collection if no other document in the collection has the a.b value of 5:

db.collection.insert( { a: [ { b: 5 }, { b: 5 } ] } )

Unique Index and Missing Field¶

If a document does not have a value for the indexed field in a unique index, the index will store a null value for this document. Because of the unique constraint, MongoDB will only permit one document that lacks the indexed field. If there is more than one document without a value for the indexed field or is missing the indexed field, the index build will 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 field x if the collection does not already contain a document missing the field x:

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

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

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

The operation fails to insert the document because of the violation of the 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 }"
   }
})

You can combine the unique constraint with the sparse index to filter these null values from the unique index and avoid the error.

Unique Partial Indexes¶

New in version 3.2.

Partial indexes only index the documents in a collection that meet a specified filter expression. If you specify both the partialFilterExpression and a unique constraint, the unique constraint only applies to the documents that meet the filter expression. A partial index with a unique constraint does not prevent the insertion of documents that do not meet the unique constraint if the documents do not meet the filter criteria. For an example, see Partial Index with Unique Constraint.

Restrictions¶

You may not specify a unique constraint on a hashed index.