Skip to content

Commit 506aea9

Browse files
kyuan-mongodbkyuan-mongodb
authored
DOCSP-13848 crud compound operations (#64)
* added CRUD Compound Operations page
1 parent d3e37a9 commit 506aea9

File tree

4 files changed

+426
-5
lines changed

4 files changed

+426
-5
lines changed

‎source/fundamentals/crud.txt

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ CRUD Operations
99

1010
/fundamentals/crud/read-operations
1111
/fundamentals/crud/write-operations
12+
/fundamentals/crud/compound-operations
1213

1314
CRUD (Create, Read, Update, Delete) operations enable you to work with
1415
data stored in MongoDB.
@@ -18,7 +19,6 @@ data stored in MongoDB.
1819
- :doc:`Write Operations </fundamentals/crud/write-operations>` insert, modify,
1920
or delete documents in your database.
2021

21-
..
22-
Some operations combine aspects of read and write operations. See our
23-
guide on :doc:`compound operations </fundamentals/crud/compound-operations>`
24-
to learn more about these hybrid methods.
22+
Some operations combine aspects of read and write operations. To learn
23+
more about these hybrid methods, see our guide on :doc:`compound
24+
operations </fundamentals/crud/compound-operations>`.

‎source/fundamentals/crud/compound-operations.txt

Lines changed: 324 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,324 @@
1+
===================
2+
Compound Operations
3+
===================
4+
5+
.. default-domain:: mongodb
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 1
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to perform **compound operations**.
17+
18+
Compound operations combine a read and write operation into
19+
a single operation. If you perform a read and write operation
20+
separately, there's a chance someone else may alter the document between
21+
both operations. MongoDB prevents this by placing a write lock on the
22+
document you are modifying for the duration of your compound operation.
23+
24+
MongoDB supports the following compound operations:
25+
26+
- :ref:`Find and delete one document <go-find-and-delete>`
27+
- :ref:`Find and update one document <go-find-and-update>`
28+
- :ref:`Find and replace one document <go-find-and-replace>`
29+
30+
.. tip::
31+
32+
If you need to read and write to more than one document, use
33+
:manual:`transactions </core/transactions/>`.
34+
35+
Sample Data
36+
~~~~~~~~~~~
37+
38+
Run the following snippet to load the documents into the ``ratings``
39+
collection of the ``tea`` database:
40+
41+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/compoundOperations.go
42+
:language: go
43+
:dedent:
44+
:start-after: begin insertDocs
45+
:end-before: end insertDocs
46+
47+
.. include:: /includes/fundamentals/tea-sample-data-ending.rst
48+
49+
.. _go-find-and-delete:
50+
51+
Find and Delete
52+
---------------
53+
54+
The ``FindOneAndDelete()`` function finds the first document that matches
55+
the specified query filter and deletes it. The function returns a
56+
``SingleResult`` containing the deleted document.
57+
58+
.. note::
59+
60+
This function differs from the ``DeleteOne()`` function.
61+
``FindOneAndDelete()`` performs a find and delete as a single
62+
operation, and eliminates the possibility of someone altering a
63+
document between both operations.
64+
65+
Modify Behavior
66+
~~~~~~~~~~~~~~~
67+
68+
You can modify the behavior of the ``FindOneAndDelete()`` function by
69+
passing in a ``FineOneAndDeleteOptions``. If you don't specify a
70+
``FineOneAndDeleteOptions``, the driver uses the default values for each
71+
option.
72+
73+
The ``FineOneAndDeleteOptions`` type allows you to configure options
74+
with the following functions:
75+
76+
.. list-table::
77+
:widths: 30 70
78+
:header-rows: 1
79+
80+
* - Function
81+
- Description
82+
83+
* - ``SetCollation()``
84+
- | The type of language collation to use when sorting results.
85+
| Default: ``nil``
86+
87+
* - ``SetMaxTime()``
88+
- | The maximum amount of time that the query can run on the server.
89+
| Default: ``nil``
90+
91+
* - ``SetProjection()``
92+
- | The fields to include in the document returned.
93+
| Default: ``nil``
94+
95+
* - ``SetSort()``
96+
- | The sort fields and directions to order the documents matched.
97+
| Default: ``nil``
98+
99+
* - ``SetHint()``
100+
- | The index to use to scan for documents.
101+
| Default: ``nil``
102+
103+
Example
104+
```````
105+
106+
The following example matches and deletes a document where the ``type``
107+
is "Assam" with the ``FindOneAndDelete()`` function:
108+
109+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/compoundOperations.go
110+
:language: go
111+
:dedent:
112+
:start-after: begin FindOneAndDelete
113+
:end-before: end FindOneAndDelete
114+
115+
After running this example, the output resembles the following:
116+
117+
.. code-block:: none
118+
:copyable: false
119+
120+
[{_id ObjectID("...")} {type Assam} {rating 5}]
121+
122+
.. _go-find-and-update:
123+
124+
Find and Update
125+
---------------
126+
127+
The ``FindOneAndUpdate()`` function finds the first document that matches
128+
the specified query filter and updates it according to the update
129+
document. The function returns a ``SingleResult`` containing the matched
130+
document.
131+
132+
.. note::
133+
134+
This function differs from the ``UpdateOne()`` function.
135+
``FindOneAndUpdate()`` performs a find and update as a single
136+
operation, and eliminates the possibility of someone altering a
137+
document between both operations.
138+
139+
Modify Behavior
140+
~~~~~~~~~~~~~~~
141+
142+
You can modify the behavior of the ``FindOneAndUpdate()`` function by
143+
passing in a ``FineOneAndUpdateOptions``. If you don't specify a
144+
``FineOneAndUpdateOptions``, the driver uses the default values for each
145+
option.
146+
147+
The ``FineOneAndUpdateOptions`` type allows you to configure options
148+
with the following functions:
149+
150+
.. list-table::
151+
:widths: 30 70
152+
:header-rows: 1
153+
154+
* - Function
155+
- Description
156+
157+
* - ``SetArrayFilters()``
158+
- | The array elements the update applies to.
159+
| Default: ``nil``
160+
161+
* - ``SetBypassDocumentValidation()``
162+
- | Whether to allow the write operation to opt-out of :manual:`document level validation </core/schema-validation>`.
163+
| Default: ``false``
164+
165+
* - ``SetCollation()``
166+
- | The type of language collation to use when sorting results.
167+
| Default: ``nil``
168+
169+
* - ``SetMaxTime()``
170+
- | The maximum amount of time that the query can run on the server.
171+
| Default: ``nil``
172+
173+
* - ``SetProjection()``
174+
- | The fields to include in the document returned.
175+
| Default: ``nil``
176+
177+
* - ``SetReturnDocument()``
178+
- | Whether to return the original or updated document in the ``SingleResult``.
179+
| Default: ``options.Before``
180+
181+
* - ``SetSort()``
182+
- | The sort fields and directions to order the documents matched.
183+
| Default: ``nil``
184+
185+
* - ``SetUpsert()``
186+
- | Whether to insert a new document if the query filter doesn't match any documents.
187+
| Default: ``false``
188+
189+
* - ``SetHint()``
190+
- | The index to use to scan for documents.
191+
| Default: ``nil``
192+
193+
Example
194+
```````
195+
196+
The following example performs the following actions in order with the
197+
``FindOneAndUpdate()`` function:
198+
199+
- Matches a document where the ``type`` is "Oolong"
200+
- Updates the matched document's ``rating`` to ``9``
201+
- Returns the updated document
202+
203+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/compoundOperations.go
204+
:language: go
205+
:dedent:
206+
:start-after: begin FindOneAndUpdate
207+
:end-before: end FindOneAndUpdate
208+
209+
After running this example, the output resembles the following:
210+
211+
.. code-block:: none
212+
:copyable: false
213+
214+
[{_id ObjectID("...")} {type Oolong} {rating 9}]
215+
216+
.. _go-find-and-replace:
217+
218+
Find and Replace
219+
----------------
220+
221+
The ``FindOneAndReplace()`` function finds the first document that
222+
matches the specified query filter and replaces it with the replacement
223+
document. The function returns a ``SingleResult`` containing the matched
224+
document.
225+
226+
.. note::
227+
228+
This function differs from the ``ReplaceOne()`` function.
229+
``FindOneAndReplace()`` performs a find and replace as a single
230+
operation, and eliminates the possibility of someone altering a
231+
document between both operations.
232+
233+
Modify Behavior
234+
~~~~~~~~~~~~~~~
235+
236+
You can modify the behavior of the ``FindOneAndReplace()`` function by
237+
passing in a ``FineOneAndReplaceOptions``. If you don't specify a
238+
``FineOneAndReplaceOptions``, the driver uses the default values for each
239+
option.
240+
241+
The ``FineOneAndReplaceOptions`` type allows you to configure options
242+
with the following functions:
243+
244+
.. list-table::
245+
:widths: 30 70
246+
:header-rows: 1
247+
248+
* - Function
249+
- Description
250+
251+
* - ``SetBypassDocumentValidation()``
252+
- | Whether to allow the write operation to opt-out of :manual:`document level validation </core/schema-validation>`.
253+
| Default: ``false``
254+
255+
* - ``SetCollation()``
256+
- | The type of language collation to use when sorting results.
257+
| Default: ``nil``
258+
259+
* - ``SetMaxTime()``
260+
- | The maximum amount of time that the query can run on the server.
261+
| Default: ``nil``
262+
263+
* - ``SetProjection()``
264+
- | The fields to include in the document returned.
265+
| Default: ``nil``
266+
267+
* - ``SetReturnDocument()``
268+
- | Whether to return the original or replaced document in the ``SingleResult``.
269+
| Default: ``nil``
270+
271+
* - ``SetSort()``
272+
- | The sort fields and directions to order the documents matched.
273+
| Default: ``nil``
274+
275+
* - ``SetUpsert()``
276+
- | Whether to insert a new document if the query filter doesn't match any documents.
277+
| Default: ``false``
278+
279+
* - ``SetHint()``
280+
- | The index to use to scan for documents.
281+
| Default: ``nil``
282+
283+
Example
284+
```````
285+
286+
The following example performs the following actions in order with the
287+
``FindOneAndReplace()`` function:
288+
289+
- Matches a document where the ``type`` is "English Breakfast"
290+
- Replaces the matched document with a new document where the ``type`` is "Ceylon" and ``rating`` is ``6``
291+
292+
.. literalinclude:: /includes/fundamentals/code-snippets/CRUD/compoundOperations.go
293+
:language: go
294+
:dedent:
295+
:start-after: begin FindOneAndReplace
296+
:end-before: end FindOneAndReplace
297+
298+
After running this example, the output resembles the following:
299+
300+
.. code-block:: none
301+
:copyable: false
302+
303+
[{_id ObjectID("...")} {type English Breakfast} {rating 5}]
304+
305+
Additional Information
306+
----------------------
307+
308+
For more information on performing the read or write operations
309+
mentioned in this guide, see the following guides:
310+
311+
- :doc:`Retrieve Data </fundamentals/crud/read-operations/retrieve>`
312+
- :doc:`Delete a Document </fundamentals/crud/write-operations/delete>`
313+
- :doc:`Update or Replace a Document </fundamentals/crud/write-operations/change-a-document>`
314+
- :ref:`Access Data in a SingleResult <bson-unmarshalling>`
315+
316+
API Documentation
317+
~~~~~~~~~~~~~~~~~
318+
319+
- `FindOneAndDelete() <{+api+}/mongo#Collection.FindOneAndDelete>`__
320+
- `FindOneAndDeleteOptions <{+api+}/mongo/options#FindOneAndDeleteOptions>`__
321+
- `FindOneAndUpdate() <{+api+}/mongo#Collection.FindOneAndUpdate>`__
322+
- `FindOneAndUpdateOptions <{+api+}/mongo/options#FindOneAndUpdateOptions>`__
323+
- `FindOneAndReplace() <{+api+}/mongo#Collection.FindOneAndReplace>`__
324+
- `FindOneAndReplaceOptions <{+api+}/mongo/options#FindOneAndReplaceOptions>`__

‎source/includes/fundamentals/automatic-db-coll-creation.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
.. tip:: Non-existent Databases and Collections
22

3-
The server automatically creates the necessary database and
3+
The server implicitly creates the necessary database and
44
collection when you perform a write operation against them if they
55
don't already exist.
66

0 commit comments

Comments
 (0)