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