Skip to content

Commit 9a10f85

Browse files
kay-kimkay-kim
committed
DOCS-64 document rename behavior when old name does not exist
1 parent 146d948 commit 9a10f85

File tree

3 files changed

+378
-106
lines changed

3 files changed

+378
-106
lines changed

‎source/reference/command/findAndModify.txt

Lines changed: 110 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -7,68 +7,133 @@ findAndModify
77
.. dbcommand:: findAndModify
88

99
The :dbcommand:`findAndModify` command atomically modifies and
10-
returns a single document. The shell and many :term:`drivers
11-
<driver>` provide a :method:`findAndModify()` helper method. The
12-
command has the following prototype form:
10+
returns a single document. By default, the returned document does
11+
not include the modifications made on the update. To return the
12+
document with the modifications made on the update, use the ``new``
13+
option.
14+
15+
The command has the following syntax:
1316

1417
.. code-block:: javascript
1518

16-
{ findAndModify: "collection", <options> }
19+
{ findAndModify: <collection>, <options> }
20+
21+
The :dbcommand:`findAndModify` command takes the following are
22+
sub-document ``options``:
23+
24+
:field document query:
25+
26+
Optional. Specifies the selection criteria for the
27+
modification. The ``query`` field employs the same
28+
:ref:`query selectors <query-selectors>` as used in the
29+
:method:`db.collection.find()` method. Although the query may
30+
match multiple documents, only one document will be selected
31+
for the modification.
32+
33+
The ``query`` field has the following syntax:
34+
35+
.. code-block:: javascript
36+
37+
query: { <query expression> }
38+
39+
:field document sort:
40+
41+
Optional. Determines which document will be modified if the
42+
query selects multiple documents. The first document as
43+
determined by the ``sort`` will be the one modified.
44+
45+
The ``sort`` field has the following syntax:
46+
47+
.. code-block:: javascript
48+
49+
sort: { field1: value1, field2: value2, ... }
50+
51+
:field boolean remove:
52+
53+
Optional if ``update`` field exists. When ``true``, removes
54+
the selected document. The default is ``false``.
55+
56+
The ``remove`` field has the following syntax:
57+
58+
.. code-block:: javascript
59+
60+
remove: <boolean>
1761

18-
Replace, ``collection`` with the name of the collection
19-
containing the document that you want to modify, and specify
20-
options, as a sub-document that specifies the following:
62+
:field document update:
2163

22-
:field query: A query object. This statement might resemble the
23-
:term:`document` passed to :method:`db.collection.find()`, and
24-
should return *one* document from the database.
64+
Optional if ``remove`` field exists. Performs an update of
65+
the selected document. The ``update`` field employs the same
66+
:ref:`update operators <update-operators>` or ``key:value``
67+
specifications to modify the selected document.
2568

26-
:field sort: Optional. If the query selects multiple documents, the
27-
first document given by this sort clause will be the
28-
one modified.
69+
.. code-block:: javascript
2970

30-
:field remove: When ``true``, :dbcommand:`findAndModify` removes
31-
the selected document.
71+
update: { <update expression> }
3272

33-
:field update: an :ref:`update operator <update-operators>` to
34-
modify the selected document.
73+
:field boolean new:
3574

36-
:field new: when ``true``, returns the modified document rather
37-
than the original. :dbcommand:`findAndModify` ignores
38-
the ``new`` option for ``remove`` operations.
75+
Optional. When ``true``, returns the modified document rather
76+
than the original. The :dbcommand:`findAndModify` method
77+
ignores the ``new`` option for ``remove`` operations. The
78+
default is ``false``.
3979

40-
:field fields: a subset of fields to return. See ":ref:`projection
41-
operators <projection-operators>`" for more
42-
information.
80+
.. code-block:: javascript
4381

44-
:field upsert: when ``true``, creates a new document if the
45-
specified ``query`` returns no documents. The
46-
default is ``false``. The return value for these
47-
operations is ``null`` in version 2.2
82+
new: <boolean>
4883

49-
.. versionchanged:: 2.2
50-
Previously, ``upsert`` operations returned a an empty document
51-
(e.g. ``{ }``,) see :ref:`the 2.2 release notes
52-
<2.2-findandmodify-returns-null>` for more information.
84+
:field document fields:
85+
86+
Optional. A subset of fields to return.
87+
88+
.. code-block:: javascript
5389

54-
For example:
90+
fields: { field1: <boolean>, field2: <boolean> ... }
91+
92+
:field boolean upsert:
93+
94+
Optional. Used in conjunction with the ``update`` field. When
95+
``true``, the :dbcommand:`findAndModify` command creates a
96+
new document if the ``query`` returns no documents. The
97+
default is ``false``. In version 2.2, the
98+
:dbcommand:`findAndModify` command returns ``null`` when
99+
``upsert`` is ``true``.
100+
101+
.. code-block:: javascript
102+
103+
upsert: <boolean>
104+
105+
.. versionchanged:: 2.2
106+
Previously, ``upsert`` operations returned a an empty
107+
document (e.g. ``{ }``,) see :ref:`the 2.2 release notes
108+
<2.2-findandmodify-returns-null>` for more information.
109+
110+
Consider the following example:
55111

56112
.. code-block:: javascript
57113

58114
{ findAndModify: "people",
59-
{ query: { name: "Tom", state: "active", rating: { $gt: 10 } },
60-
sort: { rating: 1 },
61-
update: { $inc: { score: 1 } }
62-
}
63-
}
64-
65-
This operation, finds a document in the ``people`` collection
66-
where the ``name`` field has the value ``Tom``, the
67-
``active`` value in the ``state`` field and a value in the
68-
``rating`` field :operator:`greater than <$gt>` 10. If there is
69-
more than one result for this query, MongoDB sorts the results of
70-
the query in descending order, and :operator:`increments <$inc>`
71-
the value of the ``score`` field by 1. Using the shell helper,
115+
query: { name: "Tom", state: "active", rating: { $gt: 10 } },
116+
sort: { rating: 1 },
117+
update: { $inc: { score: 1 } }
118+
}
119+
120+
This command performs the following actions:
121+
122+
#. The ``query`` finds a document in the ``people`` collection where the
123+
``name`` field has the value ``Tom``, the ``state`` field has the
124+
value ``active`` and the ``rating`` field has a value
125+
:operator:`greater than <$gt>` 10.
126+
127+
#. The ``sort`` orders the results of the query in ascending order.
128+
129+
#. The update :operator:`increments <$inc>` the value of the
130+
``score`` field by 1.
131+
132+
#. The command returns the original (pre-modification) document
133+
selected for this update.
134+
135+
The shell and many :term:`drivers <driver>` provide a
136+
:method:`findAndModify()` helper method. Using the shell helper,
72137
this same operation can take the following form:
73138

74139
.. code-block:: javascript

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

Lines changed: 106 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -4,50 +4,98 @@ db.collection.findAndModify()
44

55
.. default-domain:: mongodb
66

7-
.. method:: db.collection.findAndModify()
8-
9-
The :method:`db.collection.findAndModify()` method atomically modifies and
10-
returns a single document. Always call :method:`db.collection.findAndModify()`
11-
on a collection object, using the following form:
12-
13-
.. code-block:: javascript
14-
15-
db.collection.findAndModify();
16-
17-
Replace, ``collection`` with the name of the collection
18-
containing the document that you want to modify, and specify
19-
options, as a sub-document that specifies the following:
20-
21-
:field document query: A query object. This statement might
22-
resemble the :term:`document` passed to
23-
:method:`db.collection.find()`, and should return *one*
24-
document from the database.
25-
26-
:field sort: Optional. If the query selects multiple documents, the
27-
first document given by this sort clause will be the
28-
one modified.
29-
30-
:field remove: Optional. When ``true``, :dbcommand:`findAndModify`
31-
removes the selected document. The default is
32-
``false``
33-
34-
:field update: An :ref:`update operator <update-operators>` to
35-
modify the selected document.
36-
37-
:field new: Optional. When ``true``, returns the modified document
38-
rather than the original. :dbcommand:`findAndModify`
39-
ignores the ``new`` option for ``remove``
40-
operations. The default is ``false``.
41-
42-
:field fields: Optional. A subset of fields to return. See
43-
":ref:`projection operators <projection-operators>`"
44-
for more information.
45-
46-
:field upsert: Optional. When ``true``, :dbcommand:`findAndModify`
47-
creates a new document if the specified ``query``
48-
returns no documents. The default is ``false``.
49-
50-
For example:
7+
.. method:: db.collection.findAndModify
8+
9+
The :method:`db.collection.findAndModify()` method atomically
10+
modifies and returns a single document. By default, the returned
11+
document does not include the modifications made on the update. To
12+
return the document with the modifications made on the update, use
13+
the ``new`` option.
14+
15+
The :method:`db.collection.findAndModify()` method takes a document
16+
parameter with the following subdocument fields:
17+
18+
:field document query:
19+
20+
Optional. Specifies the selection criteria for the
21+
modification. The ``query`` field employs the same
22+
:ref:`query selectors <query-selectors>` as used in the
23+
:method:`db.collection.find()` method. Although the query may
24+
match multiple documents, only one document will be selected
25+
for the modification.
26+
27+
The ``query`` field has the following syntax:
28+
29+
.. code-block:: javascript
30+
31+
query: { <query expression> }
32+
33+
:field document sort:
34+
35+
Optional. Determines which document will be modified if the
36+
query selects multiple documents. The first document as
37+
determined by the ``sort`` will be the one modified.
38+
39+
The ``sort`` field has the following syntax:
40+
41+
.. code-block:: javascript
42+
43+
sort: { field1: value1, field2: value2, ... }
44+
45+
:field boolean remove:
46+
47+
Optional if ``update`` field exists. When ``true``, removes
48+
the selected document. The default is ``false``.
49+
50+
The ``remove`` field has the following syntax:
51+
52+
.. code-block:: javascript
53+
54+
remove: <boolean>
55+
56+
:field document update:
57+
58+
Optional if ``remove`` field exists. Performs an update of
59+
the selected document. The ``update`` field employs the same
60+
:ref:`update operators <update-operators>` or ``key:value``
61+
specifications to modify the selected document.
62+
63+
.. code-block:: javascript
64+
65+
update: { <update expression> }
66+
67+
:field boolean new:
68+
69+
Optional. When ``true``, returns the modified document rather
70+
than the original. The :dbcommand:`findAndModify` method
71+
ignores the ``new`` option for ``remove`` operations. The
72+
default is ``false``.
73+
74+
.. code-block:: javascript
75+
76+
new: <boolean>
77+
78+
:field document fields:
79+
80+
Optional. A subset of fields to return.
81+
82+
.. code-block:: javascript
83+
84+
fields: { field1: <boolean>, field2: <boolean> ... }
85+
86+
:field boolean upsert:
87+
88+
Optional. Used in conjunction with the ``update`` field. When
89+
``true``, :dbcommand:`findAndModify` creates a new document
90+
if the ``query`` returns no documents. The default is
91+
``false``. In version 2.2, the :dbcommand:`findAndModify`
92+
command returns ``null`` when ``upsert`` is ``true``.
93+
94+
.. code-block:: javascript
95+
96+
upsert: <boolean>
97+
98+
Consider the following example:
5199

52100
.. code-block:: javascript
53101

@@ -57,14 +105,20 @@ db.collection.findAndModify()
57105
update: { $inc: { score: 1 } }
58106
} );
59107

60-
This operation finds a document in the ``people`` collection
61-
where the ``name`` field has the value ``Tom``, the
62-
``active`` value in the ``state`` field and a value in the
63-
``rating`` field :operator:`greater than <$gt>` 10, and
64-
:operator:`increments <$inc>` the value of the ``score`` field by
65-
1. If there is more than one result for this query, MongoDB sorts
66-
the results of the query in ascending order, and updates and
67-
returns the first matching document found.
108+
This command performs the following actions:
109+
110+
#. The ``query`` finds a document in the ``people`` collection where
111+
the ``name`` field has the value ``Tom``, the ``state`` field has
112+
the value ``active`` and the ``rating`` field has a value
113+
: operator:`greater than <$gt>` 10.
114+
115+
#. The ``sort`` orders the results of the query in ascending order.
116+
117+
#. The update :operator:`increments <$inc>` the value of the
118+
``score`` field by 1.
119+
120+
#. The command returns the original (pre-modification) document
121+
selected for this update.
68122

69123
.. warning::
70124

0 commit comments

Comments
 (0)