Skip to content

Commit 414f8f5

Browse files
andf-mongodbandf-mongodb
committed
DOCSP-15179-DOCS-9187 upsert with unique index refactor
1 parent 893277a commit 414f8f5

File tree

6 files changed

+209
-136
lines changed

6 files changed

+209
-136
lines changed

‎source/includes/extracts-parameter-upsert.yaml‎

Lines changed: 52 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,13 +8,34 @@ content: |
88
99
- Updates a single document that matches the ``{{queryOrFilter}}``.
1010
11-
To avoid multiple upserts, ensure that the ``{{queryOrFilter}}`` fields
12-
are :ref:`uniquely indexed <index-type-unique>`.
11+
{{usageWithMulti}}
12+
13+
To avoid multiple :term:`upserts <upsert>`, ensure that the
14+
``{{queryOrFilter}}`` field(s) are :ref:`uniquely indexed
15+
<index-type-unique>`. {{uniqueIndexExample}}
16+
17+
Defaults to ``false``, which does *not* insert a new document when no
18+
match is found.
1319
14-
Defaults to ``false``.
1520
replacement:
1621
conjunction: ''
1722
returnNewDocument: ''
23+
usageWithMulti: ''
24+
uniqueIndexExample: ''
25+
---
26+
ref: findAndModify-behavior-command
27+
source:
28+
file: extracts-parameter-upsert.yaml
29+
ref: _update-single-upsert-behavior
30+
replacement:
31+
upsertMethod: ":dbcommand:`findAndModify`"
32+
queryOrFilter: query
33+
uniqueIndexExample: "See :ref:`upsert-and-unique-index-dbcommand` for
34+
an example."
35+
conjunction: "Used in conjunction with the ``update`` field.
36+
37+
38+
"
1839
---
1940
ref: findAndModify-behavior-method
2041
source:
@@ -23,11 +44,39 @@ source:
2344
replacement:
2445
upsertMethod: ":method:`~db.collection.findAndModify()`"
2546
queryOrFilter: query
47+
uniqueIndexExample: "See :ref:`upsert-and-unique-index` for an
48+
example."
2649
conjunction: "Used in conjunction with the ``update`` field.
2750
2851
2952
"
3053
---
54+
ref: update-upsert-behavior-command
55+
source:
56+
file: extracts-parameter-upsert.yaml
57+
ref: _update-single-upsert-behavior
58+
replacement:
59+
upsertMethod: ":dbcommand:`update`"
60+
queryOrFilter: query
61+
usageWithMulti: "If both ``upsert`` and ``multi`` are true and no
62+
documents match the query, the update operation inserts only a
63+
single document."
64+
uniqueIndexExample: "See :ref:`update-command-behaviors-unique-index`
65+
for an example."
66+
---
67+
ref: update-upsert-behavior-method
68+
source:
69+
file: extracts-parameter-upsert.yaml
70+
ref: _update-single-upsert-behavior
71+
replacement:
72+
upsertMethod: ":method:`~db.collection.update()`"
73+
queryOrFilter: query
74+
usageWithMulti: "If both ``upsert`` and ``multi`` are true and no
75+
documents match the query, the update operation inserts only a
76+
single document."
77+
uniqueIndexExample: "See :ref:`update-with-unique-indexes` for an
78+
example."
79+
---
3180
ref: findOneAndUpdate-behavior-method
3281
source:
3382
file: extracts-parameter-upsert.yaml

‎source/includes/extracts-upsert-unique-index.yaml‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
ref: _upsert-unique-index-base
2+
content: |
3+
4+
When using the {{upsert}} option with the {{command}}
5+
{{commandOrMethod}}, **and not** using a :ref:`unique index
6+
<index-type-unique>` on the query field(s), multiple
7+
instances of {{aOrAn}} {{command}} operation with similar query
8+
field(s) could result in duplicate documents being inserted in
9+
certain circumstances.
10+
11+
Consider an example where no document with the name ``Andy`` exists
12+
and multiple clients issue the following command at roughly the same
13+
time:
14+
15+
{{codeExample}}
16+
17+
If all {{command}} operations finish the query phase
18+
before any client successfully inserts data, **and** there is no
19+
:ref:`unique index <index-type-unique>` on the ``name`` field, each
20+
{{command}} operation may result in an insert, creating multiple
21+
documents with ``name: Andy``.
22+
23+
To ensure that only one such document is created, and the other
24+
{{command}} operations update this new document instead, create a
25+
:ref:`unique index <index-type-unique>` on the ``name`` field. This
26+
guarantees that only one document with ``name: Andy`` is permitted
27+
in the collection.
28+
29+
With this unique index in place, the multiple {{command}} operations
30+
now exhibit the following behavior:
31+
32+
- Exactly one {{command}} operation will successfully insert a new
33+
document.
34+
35+
- All other {{command}} operations will update the newly-inserted
36+
document, incrementing the ``score`` value.
37+
38+
---
39+
ref: upsert-unique-index-findAndModify-command
40+
source:
41+
file: extracts-upsert-unique-index.yaml
42+
ref: _upsert-unique-index-base
43+
replacement:
44+
command: ":dbcommand:`findAndModify`"
45+
commandOrMethod: "command"
46+
aOrAn: "a"
47+
upsert: "``upsert: true``"
48+
codeExample: |
49+
50+
.. code-block:: javascript
51+
52+
db.runCommand(
53+
{
54+
findAndModify: "people",
55+
query: { name: "Andy" },
56+
update: { $inc: { score: 1 } },
57+
upsert: true
58+
}
59+
)
60+
61+
---
62+
ref: upsert-unique-index-findAndModify-method
63+
source:
64+
file: extracts-upsert-unique-index.yaml
65+
ref: _upsert-unique-index-base
66+
replacement:
67+
command: ":method:`~db.collection.findOneAndUpdate()`"
68+
commandOrMethod: "method"
69+
aOrAn: "a"
70+
upsert: "``upsert: true``"
71+
codeExample: |
72+
73+
.. code-block:: javascript
74+
75+
db.people.findAndModify(
76+
{
77+
query: { name: "Andy" },
78+
update: { $inc: { score: 1 } },
79+
upsert: true
80+
}
81+
)
82+
83+
---
84+
ref: upsert-unique-index-update-command
85+
source:
86+
file: extracts-upsert-unique-index.yaml
87+
ref: _upsert-unique-index-base
88+
replacement:
89+
command: ":dbcommand:`update`"
90+
commandOrMethod: "command"
91+
aOrAn: "an"
92+
upsert: ":ref:`upsert: true <update-command-upsert>`"
93+
codeExample: |
94+
95+
.. code-block:: javascript
96+
97+
db.runCommand(
98+
{
99+
update: "people",
100+
updates: [
101+
{ q: { name: "Andy" }, u: { $inc: { score: 1 } }, multi: true, upsert: true }
102+
]
103+
}
104+
)
105+
106+
---
107+
ref: upsert-unique-index-update-method
108+
source:
109+
file: extracts-upsert-unique-index.yaml
110+
ref: _upsert-unique-index-base
111+
replacement:
112+
command: ":method:`~db.collection.update()`"
113+
commandOrMethod: "method"
114+
aOrAn: "a"
115+
upsert: ":ref:`upsert: true <update-upsert>`"
116+
codeExample: |
117+
118+
.. code-block:: javascript
119+
120+
db.people.update(
121+
{ name: "Andy" },
122+
{ $inc: { score: 1 } },
123+
{
124+
upsert: true,
125+
multi: true
126+
}
127+
)
128+
129+
...

‎source/reference/command/findAndModify.txt‎

Lines changed: 5 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,7 @@ Definition
160160

161161
- boolean
162162

163-
- .. include:: /includes/extracts/findAndModify-behavior-method.rst
163+
- .. include:: /includes/extracts/findAndModify-behavior-command.rst
164164

165165

166166

@@ -373,49 +373,12 @@ following:
373373
Behavior
374374
--------
375375

376-
Upsert and Unique Index
377-
~~~~~~~~~~~~~~~~~~~~~~~
376+
.. _upsert-and-unique-index-dbcommand:
378377

379-
When the :dbcommand:`findAndModify` command includes the ``upsert:
380-
true`` option **and** the query field(s) is not uniquely indexed, the
381-
command could insert a document multiple times in certain circumstances.
378+
Upsert with Unique Index
379+
~~~~~~~~~~~~~~~~~~~~~~~~
382380

383-
Consider an example where no document with the name ``Andy`` exists and
384-
multiple clients issue the following command:
385-
386-
.. code-block:: javascript
387-
388-
db.runCommand(
389-
{
390-
findAndModify: "people",
391-
query: { name: "Andy" },
392-
sort: { rating: 1 },
393-
update: { $inc: { score: 1 } },
394-
upsert: true
395-
}
396-
)
397-
398-
If all the commands finish the ``query`` phase before any command
399-
starts the ``modify`` phase, **and** there is no unique index on the
400-
``name`` field, the commands may each perform an upsert, creating
401-
multiple duplicate documents.
402-
403-
To prevent the creation of multiple duplicate documents,
404-
create a :ref:`unique index <index-type-unique>` on
405-
the ``name`` field. With the unique index in place, then the multiple
406-
:dbcommand:`findAndModify` commands will exhibit one of the
407-
following behaviors:
408-
409-
- Exactly one :dbcommand:`findAndModify` successfully inserts a
410-
new document.
411-
412-
- Zero or more :dbcommand:`findAndModify` commands update the
413-
newly inserted document.
414-
415-
- Zero or more :dbcommand:`findAndModify` commands fail when
416-
they attempt to insert a duplicate. If the command fails due to
417-
a unique index constraint violation, you can retry the command.
418-
Absent a delete of the document, the retry should not fail.
381+
.. include:: /includes/extracts/upsert-unique-index-findAndModify-command.rst
419382

420383
.. _cmd-findAndModify-sharded-collection:
421384

‎source/reference/command/update.txt‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -223,9 +223,7 @@ Each document contains the following fields:
223223

224224
- .. _update-command-upsert:
225225

226-
Optional. If ``true``, perform an insert if no documents match the query. If
227-
both ``upsert`` and ``multi`` are true and no documents match the
228-
query, the update operation inserts only a single document.
226+
.. include:: /includes/extracts/update-upsert-behavior-command.rst
229227

230228
* - ``multi``
231229

@@ -416,6 +414,13 @@ For example:
416414

417415
For examples, see :ref:`update-command-example-agg`.
418416

417+
.. _update-command-behaviors-unique-index:
418+
419+
Upsert with Unique Index
420+
~~~~~~~~~~~~~~~~~~~~~~~~
421+
422+
.. include:: /includes/extracts/upsert-unique-index-update-command.rst
423+
419424
Limits
420425
~~~~~~
421426

‎source/reference/method/db.collection.findAndModify.txt‎

Lines changed: 3 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -308,47 +308,10 @@ For more information on projection, see also:
308308

309309
.. _upsert-and-unique-index:
310310

311-
Upsert and Unique Index
312-
~~~~~~~~~~~~~~~~~~~~~~~
311+
Upsert with Unique Index
312+
~~~~~~~~~~~~~~~~~~~~~~~~
313313

314-
When :method:`~db.collection.findAndModify()` includes the ``upsert:
315-
true`` option **and** the query field(s) is not uniquely indexed, the
316-
method could insert a document multiple times in certain circumstances.
317-
318-
In the following example, no document with the name ``Andy`` exists,
319-
and multiple clients issue the following command:
320-
321-
.. code-block:: javascript
322-
323-
db.people.findAndModify({
324-
query: { name: "Andy" },
325-
sort: { rating: 1 },
326-
update: { $inc: { score: 1 } },
327-
upsert: true
328-
})
329-
330-
Then, if these clients' :method:`~db.collection.findAndModify()`
331-
methods finish the ``query`` phase before any command starts the
332-
``modify`` phase, **and** there is no unique index on the ``name``
333-
field, the commands may all perform an upsert, creating
334-
multiple duplicate documents.
335-
336-
To prevent the creation of multiple duplicate documents with the same
337-
name, create a :ref:`unique index <index-type-unique>` on the ``name``
338-
field. With this unique index in place, the multiple methods will
339-
exhibit one of the following behaviors:
340-
341-
- Exactly one :method:`~db.collection.findAndModify()`
342-
successfully inserts a new document.
343-
344-
- Zero or more :method:`~db.collection.findAndModify()` methods
345-
update the newly inserted document.
346-
347-
- Zero or more :method:`~db.collection.findAndModify()` methods fail
348-
when they attempt to insert documents with the same name. If the
349-
method fails due to the unique index constraint violation on the
350-
``name`` field, you can retry the method. Absent a delete of the
351-
document, the retry should not fail.
314+
.. include:: /includes/extracts/upsert-unique-index-findAndModify-method.rst
352315

353316
.. _method-findAndModify-sharded-collection:
354317

0 commit comments

Comments
 (0)