@@ -184,17 +184,17 @@ value of ``{ "a.loc": "B", "a.qty": null }``.
184
184
185
185
.. _unique-index-and-missing-field:
186
186
187
- Unique Index and Missing Field
188
- ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187
+ Missing Document Field in a Unique Single- Field Index
188
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189
189
190
- If a document does not have a value for the indexed field in a unique
191
- index, the index will store a null value for this document. Because of
192
- the unique constraint, MongoDB will only permit one document that lacks
193
- the indexed field. If there is more than one document without a value
194
- for the indexed field or is missing the indexed field , the index build
195
- will fail with a duplicate key error.
190
+ If a document has a ``null`` or missing value for the indexed field in a unique
191
+ single-field index, the index stores a `` null`` value for that document.
192
+ Because of the unique constraint, a single-field unique index can only
193
+ contain one document that contains a ``null`` value in its index entry. If there is
194
+ more than one document with a ``null`` value in its index entry , the index
195
+ build fails with a duplicate key error.
196
196
197
- For example, a collection has a unique index on ``x``:
197
+ For example, a collection has a unique single-field index on ``x``:
198
198
199
199
.. code-block:: javascript
200
200
@@ -208,9 +208,8 @@ field ``x``:
208
208
209
209
db.collection.insertOne( { y: 1 } )
210
210
211
- However, the unique index errors on the insertion of a document without
212
- the field ``x`` if the collection already contains a document missing
213
- the field ``x``:
211
+ However, you cannot insert a document without the field ``x`` if the
212
+ collection already contains a document missing the field ``x``:
214
213
215
214
.. code-block:: javascript
216
215
@@ -229,11 +228,95 @@ the unique constraint on the value of the field ``x``:
229
228
}
230
229
})
231
230
232
- .. seealso: :
231
+ .. _unique-partial-indexes :
233
232
234
- :ref:`unique-partial-indexes`
233
+ Missing Document Fields in a Unique Compound Index
234
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
235
+
236
+ If a document has a ``null`` or missing value for one or more indexed
237
+ fields in a unique compound index, the index stores a null value for
238
+ each ``null`` or missing field in the document's index entry. Because of
239
+ the unique constraint, a unique compound index only permits one document
240
+ that has a ``null`` value for all indexed fields in an index entry. If
241
+ there is more than one index entry with a ``null`` value for all indexed
242
+ fields, the index build fails with a duplicate key error. MongoDB
243
+ permits multiple documents with missing fields in unique compound
244
+ indexes as long as each index entry is unique.
245
+
246
+ For example, a collection ``students`` has a unique compound index on fields
247
+ ``name``, ``age``, and ``grade``:
248
+
249
+ .. code-block:: javascript
250
+
251
+ db.students.createIndex(
252
+ {
253
+ "name": 1,
254
+ "age": -1,
255
+ "grade": 1
256
+ },
257
+ { unique: true }
258
+ )
259
+
260
+ If the collection does not already contain identical documents, the
261
+ unique compound index allows the insertion of the following documents
262
+ that are all missing the ``grade`` field.
263
+
264
+ .. code-block:: javascript
265
+
266
+ db.students.insertMany(
267
+ { "name": "Meredith", "age": 12 },
268
+ { "name": "Olivia", "age": 11 },
269
+ { "name": "Benjamin" }
270
+ )
271
+
272
+ However, you cannot insert a document that has the same index key (value
273
+ for ``name``, ``age``, and ``grade``) as another document in the
274
+ collection.
275
+
276
+ .. code-block:: javascript
277
+
278
+ db.students.insertOne( { name: "Meredith", age: 12 } )
279
+
280
+ The operation fails to insert the document because of the violation of
281
+ the unique constraint on the values of the fields ``name``, ``age``, and ``grade``:
282
+
283
+ .. code-block:: javascript
284
+
285
+ WriteResult({
286
+ "nInserted" : 0,
287
+ "writeError" : {
288
+ "code" : 11000,
289
+ "errmsg" :
290
+ "E11000 duplicate key error collection: test.students
291
+ index: name_1_age_-1_grade_1
292
+ dup key: { name: "Meredith", age: 12, grade: null }
293
+ }
294
+ } )
295
+
296
+ You also cannot insert a document that is unique but shares an index
297
+ key with an existing index entry.
298
+
299
+ .. code-block:: javascript
300
+
301
+ db.students.insertOne( { name: "Olivia", "age": 11, "favorite color": "red"} )
302
+
303
+ The operation fails to insert the document because of the violation of
304
+ the unique constraint on the values of the fields ``name``, ``age``, and
305
+ ``grade``:
306
+
307
+ .. code-block:: javascript
308
+
309
+ WriteResult({
310
+ "nInserted" : 0,
311
+ "writeError" : {
312
+ "code" : 11000,
313
+ "errmsg" :
314
+ "E11000 duplicate key error collection: test.students
315
+ index: name_1_age_-1_grade_1
316
+ dup key: { name: "Olivia", age: 11, grade: null }
317
+ }
318
+ } )
235
319
236
- .. _unique-partial-indexes:
237
320
238
321
Unique Partial Indexes
239
322
~~~~~~~~~~~~~~~~~~~~~~
0 commit comments