Unique Indexes and Duplicate Values

Unique Index on a Single Field

For example, to create a unique index on the email field of the users collection, use the following operation in mongosh:

db.users.createIndex( { "email": 1 }, { unique: true } )

Unique Compound Index

You can also enforce a unique constraint on the combination of index key values for a compound index.

For example, to create a unique index on name, email, and password fields of the users collection, use the following operation in mongosh:

db.users.createIndex( { name: 1, email: 1, password: 1 }, { unique: true } )

Create a unique compound multikey index on email and name:

db.users.createIndex( { "email": 1, "name": 1 }, { unique: true } )

The unique index permits the insertion of the following documents into the collection since the index enforces uniqueness for the combination of email and name values:

db.users.insertMany( [
   { name: "Catelyn Stark", email: [ "catelyn@gameofthron.es", "sean_bean@gameofthron.es" ], password: "$2b$12$hash2" },
   { name: "Arya Stark", email: [ "catelyn@gameofthron.es" ], password: "$2b$12$hash3" }
] )

Even though both documents have "catelyn@gameofthron.es" in their email arrays, the operation succeeds because the combination of each email value with the name field is unique.

Restrictions

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

To convert an existing non-unique index to a unique index, see Convert an Existing Index to a Unique Index.

You cannot specify a unique constraint on a hashed index.

Building Unique Index on Replica Sets and Sharded Clusters

For replica sets and sharded clusters, using a rolling procedure to create a unique index requires that you stop all writes to the collection during the procedure. If you cannot stop all writes to the collection during the procedure, do not use the rolling procedure. Instead, to build your unique index on the collection you must either:

• Run db.collection.createIndex() on the primary for a replica set

• Run db.collection.createIndex() on the mongos for a sharded cluster

Unique Constraint Across Separate Documents

The unique index prevents different documents in the collection from having the same value for the indexed key.

Because the constraint applies to separate documents, for a unique multikey index, a document may have array elements that result in repeating index key values as long as the index key values for that document do not duplicate those of another document. In this case, the repeated index entry is inserted into the index only once.

For example, create a unique compound multikey index on email and name:

db.users.createIndex( { "email": 1, "name": 1 }, { unique: true } )

The unique index permits the insertion of the following document into the collection if no other document in the collection has an index key value of { "email": "arya@winterfell.com", "name": null }.

db.users.insertOne( { _id: ObjectId("59b99db4cfa9a34dcd7885b9"), email: [ "arya@winterfell.com", "arya@gameofthron.es" ] } )

Missing Document Field in a Unique Single-Field Index

If a document has a null or missing value for the indexed field in a unique single-field index, the index stores a null value for that document. Because of the unique constraint, a single-field unique index can only contain one document that contains a null value in its index entry. If there is more than one document with a null value in its index entry, the index build fails with a duplicate key error.

For example, a collection has a unique single-field index on email:

db.users.createIndex( { "email": 1 }, { unique: true } )

The unique index allows the insertion of a document without the email field if the collection does not already contain a document missing the email field:

db.users.insertOne( { name: "Arya Stark" } )

However, you cannot insert a second document without the email field if the collection already contains a document missing the email field. A second operation that attempts to insert another document without the email field fails to insert the document because of the violation of the unique constraint on email field.

Unique Partial Indexes

If you use both the partialFilterExpression and a unique constraint, the unique constraint only applies to documents that meet the filter expression. For an example, see Partial Index with Unique Constraint.

Sharded Clusters and Unique Indexes

A sharded cluster enforces a unique constraint across shards only when the unique index is on the shard key or includes the shard key as a prefix. You cannot specify a unique constraint on a hashed index.

To learn about the restrictions that apply to unique indexes on sharded collections, and how to maintain uniqueness on a field that is not your shard key, see Maintain Uniqueness in Sharded Clusters.

Sparse and Non-Sparse Unique Indexes

Starting in MongoDB 5.0, unique sparse and unique non-sparse indexes with the same key pattern can exist on a single collection.

db.users.createIndex( { password : 1 }, { name: "unique_index", unique: true } )

db.users.createIndex( { password : 1 }, { name: "unique_sparse_index", unique: true, sparse: true } )

db.users.createIndex( { password : 1 }, { name: "sparse_index", sparse: true } )

db.users.createIndex( { password : 1 }, { name: "basic_index" } )

Basic and Unique Indexes With Duplicate Key Patterns

Basic and unique indexes can exist with the same key pattern.

For example, you can create both of the following indexes that use the same key pattern:

db.users.createIndex( { email : 1 }, { name: "basic_index" } )

db.users.createIndex( { email : 1 }, { name: "unique_index", unique: true } )