@@ -4,46 +4,196 @@ db.collection.update()
44
55.. default-domain:: mongodb
66
7- .. method:: db.collection.update(query, update, [upsert,] [multi])
8-
9- The :method:`db.collection.update()` takes the following four arguments.
10-
11- :param query: A query object that selects one or more records to
12- update. Use the :ref:`query selectors
13- <query-selectors>` as you would in a :method:`db.collection.find()`
14- operation.
15-
16- :param update: A :term:`document`. If the update document's fields
17- include any :ref:`update operators <update-operators>`,
18- then all the fields must be update operators, and
19- applies those operators to values in the matching
20- document. If none of the update document's the
21- fields are update operators, then :method:`update()
22- <db.collection.update()>` replaces all of the
23- matching document's fields except the :term:`_id`
24- with the fields in the update document.
25-
26- :param boolean upsert: Optional. Defaults to ``false``. When
27- ``true``, this operation will update a
28- document if one matches the query portion
29- and insert a new document if *no* documents
30- match the query portion. The new document
31- will consist of the union of fields and
32- values from the query document and update
33- document.
34-
35- :param boolean multi: Optional. Defaults to ``false``. When
36- ``true``, all the operation updates all
37- documents that match the query. When
38- ``false``, update only the first document
39- that matches the query.
40-
41- Provides the ability to update an existing document in the current
42- database and collection. The second argument to :method:`db.collection.update()`
43- takes the form of a :term:`document`. See ":ref:`update-operators`"
44- for a reference of all operators that affect updates.
45-
46- .. note::
47-
48- An upsert operation only affects *one* document, and cannot
49- update multiple documents.
7+ .. method:: db.collection.update(query, update, [options])
8+
9+ .. versionchanged:: 2.2
10+
11+ The :method:`db.collection.update()` method provides the ability to
12+ modify a document in a collection.
13+
14+ The default behavior of the :method:`db.collection.update()` method
15+ is to update a single document. You can specify the ``multi`` option to
16+ update multiple documents that meet the ``query`` criteria.
17+ Additionally, you can specify the ``upsert`` option to have the
18+ :method:`db.collection.update()` method insert a document into the
19+ collection if no document meets the ``query`` criteria.
20+
21+ Starting in version 2.2, the :method:`db.collection.update()` method
22+ can take an ``options`` :term:`document` as a parameter to specify
23+ the ``multi`` and the ``upsert`` options. However, the
24+ :method:`db.collection.update()` still supports the ``upsert`` and
25+ ``multi`` parameters to specify the ``multi`` and the ``upsert``
26+ options:
27+
28+ .. code-block:: javascript
29+
30+ db.collection.update(query, update, [upsert,] [multi])
31+
32+ The :method:`db.collection.update()` method takes the following
33+ parameters:
34+
35+ :param document query:
36+
37+ A :term:`document` that specifies the selection criteria for
38+ the update. The ``query`` parameter employs the same
39+ :ref:`query selectors <query-selectors>` as used in the
40+ :method:`db.collection.find()` method.
41+
42+ Consider the following example:
43+
44+ .. code-block:: javascript
45+
46+ db.products.update( { item: "book", qty: { $gt: 5 } }, ... }
47+
48+ This query excerpt will update the document(s) in the
49+ ``products`` collection with the ``item`` field value equal
50+ to ``book`` and the ``qty`` field value greater than ``5``.
51+
52+ :param document update:
53+
54+ A :term:`document` that specifies the modifications to apply.
55+
56+ - If the ``update`` parameter contains any :ref:`update
57+ operators <update-operators>` expressions such as the
58+ :operator:`$set` operator expression, then:
59+
60+ - the ``update`` parameter must contain only :ref:`update
61+ operators <update-operators>` expressions.
62+
63+ - the :method:`db.collection.update()` method updates only
64+ the corresponding fields in the document.
65+
66+ Consider the following example:
67+
68+ .. code-block:: javascript
69+
70+ db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6 }, $inc: { y: 5} } )
71+
72+ This query will update in the ``products`` collection a
73+ single document that matches the ``query`` criteria and set
74+ the value of the field ``x`` to ``6`` and increment the
75+ value of the field ``y`` by ``5``. All other fields of the
76+ modified document will remain the same.
77+
78+ - If the ``update`` parameter consists only of ``field:
79+ value`` expressions,
80+
81+ - the :method:`db.collection.update()` method updates the
82+ document to contain only the :term:`_id` field and the
83+ fields in the ``updates`` parameter.
84+
85+ - the :method:`db.collection.update()` method updates
86+ cannot update multiple documents.
87+
88+ Consider the following example:
89+
90+ .. code-block:: javascript
91+
92+ db.products.update( { item: "book", qty: { $gt: 5 } }, { x: 6, y: 15 } )
93+
94+ This query will update in the ``products`` collection a
95+ single document that matches the ``query`` criteria and set
96+ the value of the field ``x`` to ``6`` and set the value of
97+ the field ``y`` to ``15``. *All other fields* of the
98+ modified document will be removed other than the
99+ :term:`_id` field.
100+
101+ :param document options:
102+
103+ Optional. A :term:`document` that specifies whether to
104+ perform an :term:`upsert` and/or a multiple update. You can
105+ use the ``options`` parameter instead of the individual
106+ ``upsert`` and ``multi`` parameters.
107+
108+ Consider the following example which specifies the ``multi`` option:
109+
110+ .. code-block:: javascript
111+
112+ db.products.update( { item: "book", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { multi: true } )
113+
114+ This query will update **all** documents in the ``products``
115+ collection that matches the ``query`` criteria, setting the
116+ value of the field ``x`` to ``6`` and the value of the field
117+ ``y`` to ``15``. All other fields in the updated documents
118+ remain unchanged.
119+
120+ Consider the following example which specifies the ``upsert`` option:
121+
122+ .. code-block:: javascript
123+
124+ db.products.update( { item: "magazine", qty: { $gt: 5 } }, { $set: { x: 6, y: 15 } }, { upsert: true } )
125+
126+ This query will either:
127+
128+ - update a single document in the ``products`` collection
129+ that matches the ``query`` criteria, setting the value of
130+ the field ``x`` to ``6`` and the value of the field ``y``
131+ to ``15``, *or*
132+
133+ - if no matching document exists, insert a document in the
134+ ``products`` collection, with the field ``item`` set to
135+ ``book``, the field ``x`` set to ``25``, and the field
136+ ``y`` set to ``50``.
137+
138+ :param boolean upsert:
139+
140+ Optional. A boolean that specifies whether to perform
141+ an :term:`upsert`.
142+
143+ When not specified, the default value is ``false``. When
144+ ``true``, the :method:`db.collection.update()` method will
145+ update an existing document that matches the ``query``
146+ selection criteria **or** if no document matches the
147+ criteria, insert a new document with the fields and values of
148+ the ``query`` and ``update``.
149+
150+ Consider the following example:
151+
152+ .. code-block:: javascript
153+
154+ db.products.update( { item: "book", qty: { $gt: 100 } }, { $set: { x: 25, y: 50 } }, true )
155+
156+ This query will either:
157+
158+ - update an existing document that matches the ``query``
159+ criteria, setting the field ``x`` to ``25`` and the field
160+ ``y`` to ``50``, *or*
161+
162+ - if no matching document exists, insert into the
163+ ``products`` collection a new document with the field
164+ ``item`` set to ``book``, the field ``x`` set to ``25``,
165+ and the field ``y`` set to ``50``.
166+
167+ Starting in version 2.2, you can use the ``options``
168+ parameter instead of the ``upsert`` parameter.
169+
170+ .. note::
171+
172+ An upsert operation affects only *one* document, and
173+ cannot update multiple documents.
174+
175+ :param boolean multi:
176+
177+ Optional. A boolean that specifies whether to update multiple
178+ documents that meet the ``query`` criteria.
179+
180+ When not specified, the default value is ``false`` and the
181+ :method:`db.collection.update()` method updates a single
182+ document that meet the ``query`` criteria.
183+
184+ When ``true``, the :method:`db.collection.update()` method
185+ updates all documents that meet the ``query`` criteria.
186+
187+ Consider the following example:
188+
189+ .. code-block:: javascript
190+
191+ db.products.update( { item: "book", qty: { $gt: 100 } }, { $set: { x: 25, y: 50 } }, false, true )
192+
193+ This query will update **all** documents in the ``products``
194+ collection that matches the ``query`` criteria, setting the
195+ value of the field ``x`` to ``25`` and the value of the field
196+ ``y`` to ``50``.
197+
198+ Starting in version 2.2, you can use the ``options``
199+ parameter instead of the ``multi`` parameter.
0 commit comments