Skip to content

Commit 722b531

Browse files
authored
DOCSP 33220 Clarify unique index missing fields limitation (#4889) (#5062)
* 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 bf38c9f commit 722b531

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
@@ -184,17 +184,17 @@ value of ``{ "a.loc": "B", "a.qty": null }``.
184184

185185
.. _unique-index-and-missing-field:
186186

187-
Unique Index and Missing Field
188-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
187+
Missing Document Field in a Unique Single-Field Index
188+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
189189

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

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

199199
.. code-block:: javascript
200200

@@ -208,9 +208,8 @@ field ``x``:
208208

209209
db.collection.insertOne( { y: 1 } )
210210

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

215214
.. code-block:: javascript
216215

@@ -229,11 +228,95 @@ the unique constraint on the value of the field ``x``:
229228
}
230229
})
231230

232-
.. seealso::
231+
.. _unique-partial-indexes:
233232

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

236-
.. _unique-partial-indexes:
237320

238321
Unique Partial Indexes
239322
~~~~~~~~~~~~~~~~~~~~~~

0 commit comments

Comments
 (0)