Skip to content

Commit 0548eb1

Browse files
rustagirrustagir
authored
DOCSP-30540: insert fundamental guide (#11)
1 parent 58348ac commit 0548eb1

File tree

4 files changed

+378
-5
lines changed

4 files changed

+378
-5
lines changed

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

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,17 @@ Write Operations
77
.. toctree::
88
:caption: Write Operations
99

10-
..
1110
/fundamentals/crud/write-operations/insert
11+
12+
..
1213
/fundamentals/crud/write-operations/delete
1314
/fundamentals/crud/write-operations/change
1415
/fundamentals/crud/write-operations/arrays
1516
/fundamentals/crud/write-operations/upsert
16-
/fundamentals/crud/write-operations/bulk
1717

18-
.. - :ref:`rust-insert-guide`
18+
- :ref:`rust-insert-guide`
19+
1920
.. - :ref:`rust-delete-guide`
2021
.. - :ref:`rust-change-guide`
2122
.. - :ref:`rust-arrays-guide`
2223
.. - :ref:`rust-upsert-guide`
23-
.. - :ref:`rust-bulk-guide`

‎source/fundamentals/crud/write-operations/insert.txt

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
.. _rust-insert-guide:
2+
3+
================
4+
Insert Documents
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
Overview
14+
--------
15+
16+
In this guide, you can learn how to **insert** documents into a MongoDB
17+
collection.
18+
19+
Before you can find, update, and delete any documents in MongoDB, you need
20+
to insert them. You can insert documents by using the following methods:
21+
22+
- ``insert_one()`` to insert one document
23+
- ``insert_many()`` to insert one or more documents
24+
25+
The _id Field
26+
-------------
27+
28+
In MongoDB, each document *must* contain a unique ``_id`` field.
29+
MongoDB allows you to manage this field in the following ways:
30+
31+
- Manage this field yourself, ensuring that each ``_id`` value you set
32+
is unique.
33+
- Let the driver automatically generate unique ``ObjectId`` values. The
34+
driver generates a unique ``ObjectId`` value for each document if you do
35+
not specify a value for the ``_id`` field when performing an insert.
36+
37+
Unless you provide strong guarantees for uniqueness, we recommend that
38+
you let the driver automatically generate ``_id`` values for your
39+
documents.
40+
41+
.. important:: Duplicate _id Values
42+
43+
If you attempt to perform a write operation that includes duplicate ``_id``
44+
values, the duplicate values violate unique index constraints and cause
45+
the write operation to fail.
46+
47+
To learn more about the ``_id`` field, see :manual:`Unique Indexes
48+
</core/index-unique/>` in the Server manual.
49+
50+
To learn more about document structure and rules, see
51+
:manual:`Documents </core/document>` in the Server manual.
52+
53+
Insert a Document
54+
-----------------
55+
56+
Use the ``insert_one()`` method to insert a single document into a
57+
collection.
58+
59+
Upon successful insertion, the method returns an
60+
``InsertOneResult`` instance that contains the ``_id`` of the inserted
61+
document.
62+
63+
Example
64+
~~~~~~~
65+
66+
.. TODO decide if using structs in CRUD fundamentals
67+
68+
The following example uses the ``insert_one()`` method to insert a
69+
document into the ``books`` collection:
70+
71+
.. io-code-block::
72+
:copyable: true
73+
74+
.. input:: /includes/fundamentals/code-snippets/crud/insert.rs
75+
:start-after: begin-insert-one
76+
:end-before: end-insert-one
77+
:language: rust
78+
:dedent:
79+
80+
.. output::
81+
:language: console
82+
:visible: false
83+
84+
Inserted document with _id: ObjectId("...")
85+
86+
.. include:: /includes/fundamentals/automatic-creation.rst
87+
88+
Modify insert_one Behavior
89+
~~~~~~~~~~~~~~~~~~~~~~~~~~
90+
91+
You can modify the behavior of the ``insert_one()`` method by
92+
constructing and passing an ``InsertOneOptions`` struct. The
93+
following table describes the options available in
94+
``InsertOneOptions``:
95+
96+
.. list-table::
97+
:header-rows: 1
98+
:stub-columns: 1
99+
:class: compatibility-large
100+
101+
* - Option
102+
- Description
103+
104+
* - ``bypass_document_validation``
105+
- | If ``true``, allows the driver to perform a write that violates
106+
document-level validation. To learn more about validation, see
107+
:manual:`Schema Validation </core/schema-validation>` in the Server manual.
108+
109+
| Type: ``bool``
110+
| Default: ``false``
111+
112+
* - ``write_concern``
113+
- | The write concern for the operation. To learn more about write
114+
concerns, see :manual:`Write Concern
115+
</reference/write-concern/>` in the Server manual.
116+
117+
| Type: ``WriteConcern``
118+
119+
* - ``comment``
120+
- | An arbitrary ``Bson`` value tied to the operation to trace
121+
it through the database profiler, ``currentOp``, and
122+
logs. This option is available only when connecting to
123+
{+server+} versions 4.4 and later.
124+
125+
| Type: ``Bson``
126+
127+
The following code shows how to construct an ``InsertOneOptions``
128+
instance:
129+
130+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/insert.rs
131+
:start-after: begin-one-options
132+
:end-before: end-one-options
133+
:language: rust
134+
:copyable:
135+
:dedent:
136+
137+
Insert Multiple Documents
138+
-------------------------
139+
140+
Use the ``insert_many()`` method to insert multiple documents into a
141+
collection.
142+
143+
Upon successful insertion, the method returns an
144+
``InsertManyResult`` instance that contains the ``_id`` values of the
145+
inserted documents.
146+
147+
Example
148+
~~~~~~~
149+
150+
.. TODO decide if using structs in CRUD fundamentals
151+
152+
The following example uses the ``insert_many()`` method to insert
153+
multiple documents into the ``books`` collection:
154+
155+
.. io-code-block::
156+
:copyable: true
157+
158+
.. input:: /includes/fundamentals/code-snippets/crud/insert.rs
159+
:start-after: begin-insert-many
160+
:end-before: end-insert-many
161+
:language: rust
162+
:dedent:
163+
164+
.. output::
165+
:language: console
166+
:visible: false
167+
168+
Inserted documents with _ids:
169+
ObjectId("...")
170+
ObjectId("...")
171+
ObjectId("...")
172+
173+
.. include:: /includes/fundamentals/automatic-creation.rst
174+
175+
Modify insert_many Behavior
176+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
177+
178+
You can modify the behavior of the ``insert_many()`` method by
179+
constructing and passing an ``InsertManyOptions`` struct. The
180+
following table describes the options available in
181+
``InsertManyOptions``:
182+
183+
.. list-table::
184+
:header-rows: 1
185+
:stub-columns: 1
186+
:class: compatibility-large
187+
188+
* - Option
189+
- Description
190+
191+
* - ``bypass_document_validation``
192+
- | If ``true``, allows the driver to perform a write that violates
193+
document-level validation. To learn more about validation, see
194+
:manual:`Schema Validation </core/schema-validation>` in the Server manual.
195+
196+
| Type: ``bool``
197+
| Default: ``false``
198+
199+
* - ``ordered``
200+
- | If ``true``, when any insert fails, the operation returns
201+
without inserting the remaining documents. If ``false``, even
202+
if an insert fails, the operation continues with the remaining
203+
writes. To learn more about ordered inserts, see the
204+
:ref:`Ordered Behavior Example <rust-ordered-behavior>` section
205+
of this guide.
206+
207+
| Type: ``bool``
208+
| Default: ``true``
209+
210+
* - ``write_concern``
211+
- | The write concern for the operation. To learn more about write
212+
concerns, see :manual:`Write Concern
213+
</reference/write-concern/>` in the Server manual.
214+
215+
| Type: ``WriteConcern``
216+
217+
* - ``comment``
218+
- | An arbitrary ``Bson`` value tied to the operation to trace
219+
it through the database profiler, ``currentOp``, and
220+
logs. This option is available only when connecting to
221+
{+server+} versions 4.4 and later.
222+
223+
| Type: ``Bson``
224+
225+
The following code shows how to construct an ``InsertManyOptions``
226+
instance:
227+
228+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/insert.rs
229+
:start-after: begin-many-options
230+
:end-before: end-many-options
231+
:language: rust
232+
:copyable:
233+
:dedent:
234+
235+
.. _rust-ordered-behavior:
236+
237+
Ordered Behavior Example
238+
~~~~~~~~~~~~~~~~~~~~~~~~
239+
240+
Assume you want to insert the following documents into the ``books``
241+
collection:
242+
243+
.. code-block:: json
244+
:copyable: false
245+
246+
{ "_id": 1, "title": "Where the Wild Things Are" }
247+
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
248+
{ "_id": 1, "title": "Blueberries for Sal" }
249+
{ "_id": 3, "title": "Goodnight Moon" }
250+
251+
When you attempt to insert these documents, the result depends on the
252+
value of the ``ordered`` option in your ``InsertManyOptions``:
253+
254+
- If ``ordered`` is ``true`` (the default value), the driver throws a
255+
``BulkWriteError`` when it attempts to insert the document with the
256+
duplicate ``_id`` value. However, the driver still inserts the
257+
documents before the error occurs.
258+
259+
- If you set ``ordered`` to ``false``, the driver still throws a
260+
``BulkWriteError`` when it attempts to insert the document with the
261+
duplicate ``_id`` value, but it inserts every other document.
262+
263+
The following code shows how to perform an unordered write operation to
264+
insert the preceding documents:
265+
266+
.. literalinclude:: /includes/fundamentals/code-snippets/crud/insert.rs
267+
:start-after: begin-unordered
268+
:end-before: end-unordered
269+
:emphasize-lines: 8-9
270+
:language: rust
271+
:copyable:
272+
:dedent:
273+
274+
Even though this operation results in a ``BulkWriteError``, you can
275+
still find the non-error-producing documents in your collection:
276+
277+
.. code-block:: json
278+
:copyable: false
279+
280+
{ "_id": 1, "title": "Where the Wild Things Are" }
281+
{ "_id": 2, "title": "The Very Hungry Caterpillar" }
282+
{ "_id": 3, "title": "Goodnight Moon" }
283+
284+
Additional Information
285+
----------------------
286+
287+
.. TODO For runnable examples of the insert operations, see the following usage
288+
.. examples:
289+
290+
.. TODO To learn more about performing the operations mentioned, see the
291+
.. following guides:
292+
..
293+
.. - :ref:`rust-query-guide`
294+
295+
API Documentation
296+
~~~~~~~~~~~~~~~~~
297+
298+
To learn more about any of the methods or types discussed in this
299+
guide, see the following API Documentation:
300+
301+
- `insert_one() <{+api+}/struct.Collection.html#method.insert_one>`__
302+
- `InsertOneResult <{+api+}/results/struct.InsertOneResult.html>`__
303+
- `InsertOneOptions <{+api+}/options/struct.InsertOneOptions.html>`__
304+
- `insert_many() <{+api+}/struct.Collection.html#method.insert_many>`__
305+
- `InsertManyResult <{+api+}/results/struct.InsertManyResult.html>`__
306+
- `InsertManyOptions <{+api+}/options/struct.InsertManyOptions.html>`__
307+
- `BulkWriteError <{+api+}/error/struct.BulkWriteError.html>`__
308+
- `BulkWriteFailure <{+api+}/error/struct.BulkWriteFailure.html>`__

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

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

33
If a database and collection don't exist when
44
you perform a write operation on them, the server automatically

0 commit comments

Comments
 (0)