DOCSP-39895: Bulk write guide #117

norareidy · 2024-05-28T21:29:38Z

Pull Request Info

JIRA - https://jira.mongodb.org/browse/DOCSP-39895
Staging - https://preview-mongodbnorareidy.gatsbyjs.io/rust/DOCSP-39895-bulk-write-guide/fundamentals/crud/write-operations/bulk/

Self-Review Checklist

Is this free of any warnings or errors in the RST?
Did you run a spell-check?
Did you run a grammar-check?
Are all the links working?
Are the facets and meta keywords accurate?

rustagir

Good work so far! Lmk if you have any questions about my feedback.

rustagir · 2024-06-03T19:55:33Z

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

+Overview
+--------
+
+In this guide, you can learn how to use **bulk operations**.


Suggested change

In this guide, you can learn how to use **bulk operations**.

In this guide, you can learn how to perform **bulk operations**.

rustagir · 2024-06-03T19:56:30Z

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

+In this guide, you can learn how to use **bulk operations**.
+
+Bulk operations perform multiple write operations against one or more
+namespaces. Instead of making a call to the database for each operation,


S: since you are introducing the namespace terminology, add a clause or sentence explaining what that means

You can also indicate that the bulk_write() method is in the Client class, which enables this feature against any namespace in the cluster

rustagir · 2024-06-03T19:56:59Z

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

+
+Bulk operations perform multiple write operations against one or more
+namespaces. Instead of making a call to the database for each operation,
+bulk operations perform multiple operations with one database call.


Suggested change

bulk operations perform multiple operations with one database call.

bulk operations perform multiple operations within one call to the database.

rustagir · 2024-06-03T19:57:30Z

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

+- :ref:`bulk-sample-data`
+- :ref:`bulk-operation-types`
+- :ref:`bulk-modify-behavior`
+- :ref:`bulk-mixed-namespaces`
+- :ref:`bulk-addtl-info`


S: for multi-repo crosslinking and organization, make sure all anchors contain rust

rustagir · 2024-06-03T19:58:24Z

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

+  To perform bulk write operations, ensure that your application meets the
+  following requirements:
+
+  - You are connected to MongoDB Server version 8.0 or later.
+  - You are using {+driver-short+} version 3.0 or later.


S: indentation

rustagir · 2024-06-03T20:09:44Z

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

+     - | The filter that matches one or more documents you want to update. When specified in an ``UpdateOneModel``,
+       | only the first matching document will be updated. When specified in an ``UpdateManyModel``, all
+       | matching documents will be updated.


I: remove the newline breaks | from the beginning of each line in the paragraph

Applies everywhere you might have done this

rustagir · 2024-06-03T20:10:16Z

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

+       | Type: ``UpdateModifications``
+
+   * - ``array_filters`` 
+     - | (Optional) A set of filters specifying which array elements an update applies to.


Suggested change

- | (Optional) A set of filters specifying which array elements an update applies to.

- | (Optional) A set of filters specifying which array elements an update applies to if you are updating an array-valued field.

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

rustagir · 2024-06-03T20:15:30Z

source/includes/fundamentals/code-snippets/crud/bulk.rs

+    let insert_many_result = mushrooms.insert_many(docs, None).await?;
+
+    // begin-insert
+    let mushrooms: Collection<Mushroom> = client.database("db").collection("mushrooms");


S: reduce horizontal scroll (applies to all)

Suggested change

let mushrooms: Collection<Mushroom> = client.database("db").collection("mushrooms");

let mushrooms: Collection<Mushroom> = client

.database("db")

.collection("mushrooms");

rustagir

A few more things but good work!

rustagir · 2024-06-05T14:17:04Z

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

+Overview
+--------
+
+In this guide, you can learn how to perform **bulk operations**.


Suggested change

In this guide, you can learn how to perform **bulk operations**.

In this guide, you can learn how to use the {+driver-short+} to perform **bulk operations**.

rustagir · 2024-06-05T14:20:02Z

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

+Bulk operations perform multiple write operations against one or more
+namespaces, which refer to a database name and a collection name in
+``<database>.<collection>`` form. Since the bulk operation method is in 
+the ``Client`` class, you can perform bulk operations against any namespace
+in your cluster. 


S; use wording from the Server glossary

Suggested change

Bulk operations perform multiple write operations against one or more

namespaces, which refer to a database name and a collection name in

``<database>.<collection>`` form. Since the bulk operation method is in

the ``Client`` class, you can perform bulk operations against any namespace

in your cluster.

Bulk operations perform multiple write operations against one or more

**namespaces**. A namespace is a combination of the database name and the collection name, in the format

``<database>.<collection>``. Since you perform bulk operations on a

the ``Client`` instance, you can perform bulk operations against any namespace

in the cluster accessed by your client.

rustagir · 2024-06-05T14:21:40Z

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

+Instead of making a call to the database for each operation, bulk operations
+perform multiple operations within one call to the database.


S: right now, this sentence seems a little isolated, maybe you can make this a description of why one might use bulk ops.

Suggested change

Instead of making a call to the database for each operation, bulk operations

perform multiple operations within one call to the database.

You might perform a bulk operation to reduce the number of calls to the server. Instead of sending

a request for each operation, bulk operations perform multiple operations within one action.

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

source/includes/fundamentals/code-snippets/crud/bulk.rs

rustagir

lgtm with a few last comments! great work documenting this APi!

rustagir · 2024-06-06T20:46:09Z

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

+To perform a bulk insert operation, create an ``InsertOneModel`` instance for each document
+you want to insert. Then, pass a list of models to the ``bulk_write()`` method.
+
+To construct an ``InsertOneModel``, specify the following struct fields:


S: introduce this table (and in other sections) by clarifying that you set these fields by using the corresponding builder methods.

rustagir · 2024-06-06T20:48:10Z

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

+The following example sets the ``ordered`` field to ``false`` by chaining the ``ordered()`` method
+to the ``bulk_write()`` method: 


Suggested change

The following example sets the ``ordered`` field to ``false`` by chaining the ``ordered()`` method

to the ``bulk_write()`` method:

The following example attempts to perform update and insert operations on the ``mushrooms`` collection

and sets the ``ordered`` field to ``false`` by chaining the ``ordered()`` method

to the ``bulk_write()`` method:

rustagir · 2024-06-06T20:49:46Z

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

+The ``_id`` field is immutable and cannot be changed in an update operation. Since the ``UpdateOneModel``
+includes instructions to update this field, the bulk operation generates a ``BulkWriteError`` and performs
+only an insert operation. If you do not set the ``ordered`` field to ``false``, the bulk operation will not
+attempt any subsequent operations after the unsuccessful update and will not insert the specified document.


Suggested change

The ``_id`` field is immutable and cannot be changed in an update operation. Since the ``UpdateOneModel``

includes instructions to update this field, the bulk operation generates a ``BulkWriteError`` and performs

only an insert operation. If you do not set the ``ordered`` field to ``false``, the bulk operation will not

attempt any subsequent operations after the unsuccessful update and will not insert the specified document.

The ``_id`` field is immutable and cannot be changed in an update operation. Since the ``UpdateOneModel``

includes instructions to update this field, the bulk operation returns a ``BulkWriteError`` and performs

only the insert operation. If you set the ``ordered`` field to ``true``, the driver does not

attempt any subsequent operations after the unsuccessful update operation, and the driver does not insert any documents.

isabelatkinson

Looks great, just a few suggestions. Also recommend considering adding a section about generating verbose results using this action method.

isabelatkinson · 2024-06-07T19:48:36Z

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

+Bulk Operation Types
+--------------------
+
+To perform a bulk write operation, pass an array of ``WriteModel`` struct instances to the 


Suggested change

To perform a bulk write operation, pass an array of ``WriteModel`` struct instances to the

To perform a bulk write operation, pass an array of ``WriteModel`` enum instances to the

isabelatkinson · 2024-06-07T21:21:37Z

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

+       | When set to ``true``, the driver does not perform subsequent write operations if one operation fails.
+       | When set to ``false``, the driver continues to attempt write operations if one fails.


Very minor, but the actual continue-on-error behavior is done by the server, not the driver (for the most part). I'd remove mention of the driver here.

isabelatkinson · 2024-06-07T21:39:44Z

source/includes/fundamentals/code-snippets/crud/bulk.rs

+    );
+    // end-options
+
+    // begin-mixed-namespaces


Up to you whether this would be worth the additional text, but this could be a good spot to make the collections generic over a non-Document type and demonstrate how to use this helper method.

e.g.

#[derive(Serialize)] struct Sweet { name: String, price: f32, } let sweets: Collection<Sweet> = client.database("ingredients").collection("sweets"); let sweet = Sweet { name: "brown sugar".to_string(), price: 3.99, }; let insert_sweet_model = sweets.insert_one_model(sweet)?; // ditto for dessert

I added a section to Insert Operations instead that uses a Mushroom struct and insert_one_model()!

Also added a section on bulk write return values, which includes a verbose_results() explanation

rustagir

A few things, re-request if needed!

rustagir · 2024-06-10T20:00:10Z

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

+You can also use custom struct types to represent your sample data. For
+an example that performs a bulk operation using the ``Mushroom`` struct type,
+see the :ref:`bulk-insert-structs-example` on this page.


Suggested change

You can also use custom struct types to represent your sample data. For

an example that performs a bulk operation using the ``Mushroom`` struct type,

see the :ref:`bulk-insert-structs-example` on this page.

You can also use custom struct types to represent your sample data. For

an example that performs a bulk operation by using ``Mushroom`` structs to model the same data,

see the :ref:`bulk-insert-structs-example` on this page.

rustagir · 2024-06-10T20:00:53Z

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

+Insert Structs Example
+``````````````````````
+
+You can also model your documents as structs and insert them into the ``db.mushrooms`` namespace.


Suggested change

You can also model your documents as structs and insert them into the ``db.mushrooms`` namespace.

You can also model your documents by using structs and bulk insert struct instances

into the ``db.mushrooms`` namespace.

rustagir · 2024-06-10T20:02:10Z

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

+The following code uses the ``insert_one_model()`` method to construct an ``InsertOneModel``
+from each ``Mushroom`` instance:


Suggested change

The following code uses the ``insert_one_model()`` method to construct an ``InsertOneModel``

from each ``Mushroom`` instance:

The following code uses the ``insert_one_model()`` method to construct an ``InsertOneModel``

from each ``Mushroom`` instance, then inserts both models in a bulk operation:

rustagir · 2024-06-10T20:02:52Z

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

+See Bulk Write Results
+----------------------


Suggested change

See Bulk Write Results

----------------------

Return Type

------------

rustagir · 2024-06-10T20:03:26Z

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

+- ``upserted_count``: the number of upserted documents
+- ``deleted_count``: the number of deleted documents
+
+You can also use the ``verbose_results()`` method to see more detailed information about each


Suggested change

You can also use the ``verbose_results()`` method to see more detailed information about each

You can also use the ``verbose_results()`` method to see detailed information about each

rustagir · 2024-06-10T20:04:34Z

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

+      SummaryBulkWriteResult { inserted_count: 0, matched_count: 1, modified_count: 1,
+      upserted_count: 0, deleted_count: 1 }


Q: if this example uses the verbose_results() method, why is it printing a SummaryBulkWriteResult instead of a VerboseBulkWriteResult result?

verbose_results() returns a VerboseBulkWriteResult, but the summary field of the VerboseBulkWriteResult (which is what I'm printing) has a value of SummaryBulkWriteResult. Kinda confusing, here's the struct and its fields in the source code.

Since this ends up giving you the same information as omitting the verbose_results() call, I changed it to print the update_results and delete_results fields instead

rustagir · 2024-06-10T20:05:48Z

source/includes/fundamentals/code-snippets/crud/bulk.rs

@@ -149,7 +201,7 @@ async fn main() -> mongodb::error::Result<()> {
            .build()),
    ];

-    let result = client.bulk_write(models).ordered(false).await?;
+    let result = client.bulk_write(models).ordered(false).verbose_results().await?;


Q: why use verbose_results() here when the operation results in an error?

oops, didn't mean to add this here - removed

isabelatkinson

looks great!

norareidy added 9 commits May 28, 2024 17:29

DOCSP-39895: Bulk write guide

d99c4b4

in progress

f3090f9

edits

0905d43

more info

9388256

add output

c594d75

include coll in examples

dcac147

reduce scroll, wording

6afca98

rustfmt

cdfeb69

version requirements

bc1665c

rustagir requested changes Jun 3, 2024

View reviewed changes

norareidy added 2 commits June 3, 2024 16:22

code edits

a1fe2e4

RR feedback

07b621d

norareidy requested a review from rustagir June 4, 2024 20:43

code output edit

5f0fa34

rustagir requested changes Jun 5, 2024

View reviewed changes

norareidy added 3 commits June 5, 2024 13:59

RR feedback 2

b6e0cf6

edit

da7f1fe

indexes link

5999554

norareidy requested a review from rustagir June 5, 2024 20:27

rustagir approved these changes Jun 6, 2024

View reviewed changes

RR last feedback

979e5b0

isabelatkinson reviewed Jun 7, 2024

View reviewed changes

norareidy added 4 commits June 10, 2024 11:46

tech review

2029e4b

edits

6c74272

reword

ba1d00d

add return val section

69ae77d

rustagir self-requested a review June 10, 2024 19:43

rustagir reviewed Jun 10, 2024

View reviewed changes

RR new feedback

fb62ddb

norareidy requested a review from isabelatkinson June 10, 2024 20:43

isabelatkinson approved these changes Jun 10, 2024

View reviewed changes

norareidy merged commit 673e0b6 into mongodb:master Jun 11, 2024
1 of 2 checks passed

norareidy deleted the DOCSP-39895-bulk-write-guide branch June 11, 2024 13:50

	In this guide, you can learn how to use bulk operations.
	In this guide, you can learn how to perform bulk operations.

	bulk operations perform multiple operations with one database call.
	bulk operations perform multiple operations within one call to the database.

	- \| (Optional) A set of filters specifying which array elements an update applies to.
	- \| (Optional) A set of filters specifying which array elements an update applies to if you are updating an array-valued field.

		Instead of making a call to the database for each operation, bulk operations
		perform multiple operations within one call to the database.

		The following example sets the ``ordered`` field to ``false`` by chaining the ``ordered()`` method
		to the ``bulk_write()`` method:

	To perform a bulk write operation, pass an array of ``WriteModel`` struct instances to the
	To perform a bulk write operation, pass an array of ``WriteModel`` enum instances to the

		\| When set to ``true``, the driver does not perform subsequent write operations if one operation fails.
		\| When set to ``false``, the driver continues to attempt write operations if one fails.

	You can also model your documents as structs and insert them into the ``db.mushrooms`` namespace.
	You can also model your documents by using structs and bulk insert struct instances
	into the ``db.mushrooms`` namespace.

		The following code uses the ``insert_one_model()`` method to construct an ``InsertOneModel``
		from each ``Mushroom`` instance:

	You can also use the ``verbose_results()`` method to see more detailed information about each
	You can also use the ``verbose_results()`` method to see detailed information about each

		SummaryBulkWriteResult { inserted_count: 0, matched_count: 1, modified_count: 1,
		upserted_count: 0, deleted_count: 1 }

DOCSP-39895: Bulk write guide #117

DOCSP-39895: Bulk write guide #117

Uh oh!

Conversation

norareidy commented May 28, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Info

Self-Review Checklist

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

isabelatkinson left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

isabelatkinson Jun 7, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rustagir left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

norareidy commented May 28, 2024 •

edited

Loading

isabelatkinson Jun 7, 2024 •

edited

Loading

norareidy Jun 10, 2024 •

edited

Loading

norareidy Jun 10, 2024 •

edited

Loading