Skip to content

Commit 84a502d

Browse files
authored
DOCSP 33220 Clarify unique index missing fields limitation (#4889)
* DOCSP-33220 clarify unique index missing field limitation * DOCSP-33220 clarify unique index missing field limitation * DOCSP-33220 copy edits and adding example * DOCSP-33220 copy edits and adding example * DOCSP-33220 copy edits and adding example * DOCSP33220 updating example and heading update * DOCSP33220 updating example and heading update * DOCSP33220 updating example and heading update * DOCSP-33220 wording changes * DOCSP-33220 typos * DOCSP33220 copy edits
1 parent d8ab36b commit 84a502d

File tree

1 file changed

+98
-15
lines changed

1 file changed

+98
-15
lines changed

source/core/index-unique.txt

Lines changed: 98 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -192,17 +192,17 @@ value of ``{ "a.loc": "B", "a.qty": null }``.
192192

193193
.. _unique-index-and-missing-field:
194194

195-
Unique Index and Missing Field
196-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
195+
Missing Document Field in a Unique Single-Field Index
196+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
197197

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.
204204

205-
For example, a collection has a unique index on ``x``:
205+
For example, a collection has a unique single-field index on ``x``:
206206

207207
.. code-block:: javascript
208208

@@ -216,9 +216,8 @@ field ``x``:
216216

217217
db.collection.insertOne( { y: 1 } )
218218

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``:
222221

223222
.. code-block:: javascript
224223

@@ -237,11 +236,95 @@ the unique constraint on the value of the field ``x``:
237236
}
238237
})
239238

240-
.. seealso::
239+
.. _unique-partial-indexes:
241240

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+
} )
243327

244-
.. _unique-partial-indexes:
245328

246329
Unique Partial Indexes
247330
~~~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)