-
Notifications
You must be signed in to change notification settings - Fork 1.7k
/
index-unique.txt
210 lines (145 loc) · 6.63 KB
/
index-unique.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
.. index:: index; unique
.. _index-type-unique:
==============
Unique Indexes
==============
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
A unique index ensures that the indexed fields do not store duplicate
values; i.e. enforces uniqueness for the indexed fields. By default,
MongoDB creates a unique index on the :ref:`_id <document-id-field>`
field during the creation of a collection.
Create a Unique Index
---------------------
To create a unique index, use the :method:`db.collection.createIndex()`
method with the ``unique`` option set to ``true``.
.. code-block:: javascript
db.collection.createIndex( <key and index type specification>, { unique: true } )
.. index:: index; unique
.. _index-unique-index:
Unique Index on a Single Field
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
For example, to create a unique index on the ``user_id`` field of the
``members`` collection, use the following operation in the
:binary:`~bin.mongo` shell:
.. code-block:: javascript
db.members.createIndex( { "user_id": 1 }, { unique: true } )
Unique Compound Index
~~~~~~~~~~~~~~~~~~~~~
You can also enforce a unique constraint on :ref:`compound indexes
<index-type-compound>`. If you use the unique constraint on a
:ref:`compound index <index-type-compound>`, then MongoDB will enforce
uniqueness 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 the
following operation in the :binary:`~bin.mongo` shell:
.. code-block:: javascript
db.members.createIndex( { groupNumber: 1, lastname: 1, firstname: 1 }, { unique: true } )
The created index enforces uniqueness for the *combination* of
``groupNumber``, ``lastname``, and ``firstname`` values.
Behavior
--------
Restrictions
~~~~~~~~~~~~~
MongoDB cannot create a :ref:`unique index <index-type-unique>` on the
specified index field(s) if the collection already contains data that
would violate the unique constraint for the index.
You may not specify a unique constraint on a :ref:`hashed
index <index-type-hashed>`.
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``:
.. code-block:: javascript
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``:
.. code-block:: javascript
db.collection.insert( { a: [ { b: 5 }, { b: 5 } ] } )
.. _unique-index-and-missing-field:
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``:
.. code-block:: javascript
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``:
.. code-block:: javascript
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``:
.. code-block:: javascript
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``:
.. code-block:: javascript
WriteResult({
"nInserted" : 0,
"writeError" : {
"code" : 11000,
"errmsg" : "E11000 duplicate key error index: test.collection.$a.b_1 dup key: { : null }"
}
})
.. seealso:: :ref:`unique-partial-indexes`
.. _unique-partial-indexes:
Unique Partial Indexes
~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: 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 :ref:`unique constraint
<index-type-unique>`, 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
:ref:`partial-index-with-unique-constraints`.
Sharded Clusters and Unique Indexes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You cannot specify a unique constraint on a :ref:`hashed index
<index-type-hashed>`.
For a ranged sharded collection, only the following indexes can be
:doc:`unique </core/index-unique>`:
- the index on the shard key
- a :term:`compound index` where the shard key is a :ref:`prefix
<compound-index-prefix>`
- the default ``_id`` index; **however**, the ``_id`` index only
enforces the uniqueness constraint per shard **if** the ``_id`` field
is **not** the shard key or the prefix of the shard key.
.. admonition:: Uniqueness and the ``_id`` Index
:class: important
If the ``_id`` field is not the shard key or the prefix of the
shard key, ``_id`` index only enforces the uniqueness constraint
per 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 is
not part of the shard key, the collection could have a document
with ``_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 the
shard key, MongoDB expects applications to enforce the uniqueness
of the ``_id`` values across the shards.
The unique index constraints mean that:
- For a to-be-sharded collection, you cannot shard the collection if
the collection has other unique indexes.
- For an already-sharded collection, you cannot create unique indexes
on other fields.