DOCSP-44422 - Bulk write API #257

mongoKart · 2024-10-16T20:57:58Z

Pull Request Info

PR Reviewing Guidelines

JIRA - https://jira.mongodb.org/browse/DOCSP-44422

Staging Links

fundamentals/crud/write-operations/bulk-write

fundamentals/crud/write-operations

whats-new

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?

netlify · 2024-10-16T20:58:28Z

✅ Deploy Preview for mongodb-docs-csharp ready!

Name	Link
🔨 Latest commit	`d1bc7de`
🔍 Latest deploy log	https://app.netlify.com/sites/mongodb-docs-csharp/deploys/67214db2a919b2000887108b
😎 Deploy Preview	https://deploy-preview-257--mongodb-docs-csharp.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

rustagir

really solid start!

rustagir · 2024-10-17T13:42:35Z

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

+Consider a scenario in which you want to insert a document into a collection,
+update multiple other documents, then delete a document. If you use
+individual methods, each operation requires its own database call. This guide
+shows you how to use bulk write operations to perform multiple write operations
+in a single database call.


S: Reshuffle sentences so first sentence is more expository:

Suggested change

Consider a scenario in which you want to insert a document into a collection,

update multiple other documents, then delete a document. If you use

individual methods, each operation requires its own database call. This guide

shows you how to use bulk write operations to perform multiple write operations

in a single database call.

This guide shows you how to use the {+driver-short+} to perform **bulk write operations**

that include multiple write operations in a single database call.

Consider a scenario in which you want to insert a document into a collection,

update multiple other documents, then delete a document. If you use

individual methods, each operation requires its own database call. By using bulk write operations,

you can reduce the number of individual database calls to improve efficiency, and perform operations

on multiple namespaces in your deployment...

You should also highlight that this is Client bulkwrite

I didn't know there was another kind. The server docs imply that bulk writes are always client-initiated

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

rustagir · 2024-10-17T13:44:05Z

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

+    The examples in this guide use ``BsonDocument`` as the type for ``TDocument``.
+    You can also use a Plain Old CLR Object (POCO) as the type for ``TDocument``.


S: The phrasing "type for" is a bit vague. Perhaps you could be more descriptive about the relationship
eg use BsonDocument as the type that implements TDocument

reworded. I think the inheritance relationship will be clear to any dev who would be using this page

rustagir · 2024-10-17T13:44:37Z

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

+    To use a POCO, define a class that represents the documents in your collection.
+    The class must have properties that match the fields in your documents.
+    For more information, see :ref:`<csharp-poco>`.


Suggested change

To use a POCO, define a class that represents the documents in your collection.

The class must have properties that match the fields in your documents.

For more information, see :ref:`<csharp-poco>`.

If using a POCO, you must define a class that represents the documents in your collection.

The class must have properties that match the fields in your documents.

For more information, see :ref:`<csharp-poco>`.

rustagir · 2024-10-17T13:47:47Z

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

+class. The
+``BsonDocument`` object represents a new restaurant named "Mongo's Deli" to be inserted
+into the ``sample_restaurants.restaurants`` collection.


S: try to reduce the double references to document field values and real world things (documents vs restaurants)

Suggested change

class. The

``BsonDocument`` object represents a new restaurant named "Mongo's Deli" to be inserted

into the ``sample_restaurants.restaurants`` collection.

class. The model represents a document in which the name is ``"Mongo's Deli"`` that you want to insert

into the ``sample_restaurants.restaurants`` collection.

Could you elaborate on what to avoid? I'm trying to think of another way to say it, because I'd normally use "model" in the context of data models; i.e., a POCO, or class that mirrors a specific document structure.

I meant that we might prefer to avoid interchangeably referring to documents/C# types and restaurants.
Looking back on my suggestion, it seems a bit clunky. Maybe something like:

The BulkWriteInsertOneModel directs the driver to insert a document in which the name field value is "Mongo's Deli" into the restaurants collection.

That works! I didn't find any other uses of the word "restaurant", but let me know if anything else needs to change.

rustagir · 2024-10-17T14:03:08Z

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

+.. tip:: Troubleshooting Bulk Write Operations
+
+    If any of the write operations fail, the {+driver-short+} raises a
+    ``BulkWriteException`` and does not perform any further operations. You can examine
+    the properties of the exception to determine which operation failed.


S: Is this note necessary? It doesn't provide specific guidance on troubleshooting

Maybe "troubleshooting" isn't the best title. the point is really the first sentence.

rustagir · 2024-10-17T14:03:52Z

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

+.. note:: Unordered Bulk Write Operations
+
+   Unordered bulk operations do not guarantee order of execution. The order can
+   differ from the way you list them to optimize the runtime.
+
+   If any of the write operations in an unordered bulk write fail, the driver
+   reports the errors only after attempting all operations.


S: move this note directly under the table

moved some things around

source/includes/fundamentals/code-examples/BulkWrite.cs

rustagir · 2024-10-17T14:05:14Z

source/includes/fundamentals/code-examples/BulkWrite.cs

+            new BulkWriteUpdateManyModel<BsonDocument>(
+                ,collection


S: something looks off here

Suggested change

new BulkWriteUpdateManyModel<BsonDocument>(

,collection

new BulkWriteUpdateManyModel<BsonDocument>(

collection,

rustagir · 2024-10-17T14:05:35Z

source/whats-new.txt

+- Adds an API for bulk write operations. To learn more about bulk write operations, see
+  :ref:`csharp-bulk-write`.


Suggested change

- Adds an API for bulk write operations. To learn more about bulk write operations, see

:ref:`csharp-bulk-write`.

- Adds an API for bulk write operations at the client level. To learn more about bulk write operations, see

:ref:`csharp-bulk-write`.

Same question as above re client bulk writes

There is a bulk write method at the collection level: https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.BulkWrite.html

I think that v3 introduces "client bulk write", through a method at the client level: https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoClient.BulkWrite.html

This enables you to include writes to multiple namespaces in a deployment, which is not possible in collection bulk write.

Ah, I see--so "client" as opposed to "collection" rather than "server". good callout

mongoKart · 2024-10-18T13:20:38Z

good notes. think i got everything, except where discussion still ongoing

Co-authored-by: Rea Rustagi <[email protected]>

rustagir

Answered some comments, can take another look when you respond/resolve the threads!

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

rustagir · 2024-10-18T18:31:06Z

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

+class. The
+``BsonDocument`` object represents a new restaurant named "Mongo's Deli" to be inserted
+into the ``sample_restaurants.restaurants`` collection.


I meant that we might prefer to avoid interchangeably referring to documents/C# types and restaurants.
Looking back on my suggestion, it seems a bit clunky. Maybe something like:

The BulkWriteInsertOneModel directs the driver to insert a document in which the name field value is "Mongo's Deli" into the restaurants collection.

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

rustagir · 2024-10-18T18:34:22Z

source/whats-new.txt

+- Adds an API for bulk write operations. To learn more about bulk write operations, see
+  :ref:`csharp-bulk-write`.


There is a bulk write method at the collection level: https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoCollection-1.BulkWrite.html

I think that v3 introduces "client bulk write", through a method at the client level: https://mongodb.github.io/mongo-csharp-driver/3.0.0/api/MongoDB.Driver/MongoDB.Driver.IMongoClient.BulkWrite.html

This enables you to include writes to multiple namespaces in a deployment, which is not possible in collection bulk write.

sanych-sun · 2024-10-29T16:37:12Z

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

+   * - Property
+     - Description
+
+   * - ``Acknowledged``


Should we mention that in case of unacknowledged results (Acknowledged == false) all other properties throws?

sanych-sun · 2024-10-29T16:40:26Z

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

+.. tip::
+
+    If any of the write operations fail, the {+driver-short+} raises a
+    ``BulkWriteException`` and does not perform any further operations. You can examine


It should be ClientBulkWriteException instead.

sanych-sun · 2024-10-29T16:43:14Z

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

+------------
+
+The ``BulkWrite()`` and ``BulkWriteAsync()`` methods return a ``ClientBulkWriteResult``
+object that contains the following properties:


Should we describe ClientBulkWriteException so users know how to find error responses/partial results? Based on the spec: https://github.com/mongodb/specifications/blob/master/source/crud/bulk-write.md#exception

sanych-sun · 2024-10-29T16:45:20Z

source/includes/fundamentals/code-examples/BulkWrite.cs

+            )
+        };
+
+        var results = client.BulkWriteSync(bulkWriteModels);


BulkWrite we do not use Sync suffix here.

sanych-sun · 2024-10-29T16:46:13Z

source/includes/fundamentals/code-examples/BulkWrite.cs

+        Console.WriteLine("Bulk write results: " + results);
+        // end-bulk-write-sync
+    }
+    static async void BulkWriteAsync()


it's better be: async Task. Even though async void is possible it isn't recommended to use.

sanych-sun · 2024-10-29T16:46:55Z

source/includes/fundamentals/code-examples/BulkWrite.cs

+            VerboseResult = true
+        };
+
+        var results = client.BulkWriteSync(deleteOneModel, clientBulkWriteOptions);


BulkWrite, there is no Sync suffix.

sanych-sun · 2024-10-29T16:47:11Z

source/includes/fundamentals/code-examples/BulkWrite.cs

+        var results = client.BulkWriteSync(deleteOneModel, clientBulkWriteOptions);
+        // end-bulk-write-options-sync
+    }
+    static async void BulkWriteOptionsAsync()


async Task instead of async void

sanych-sun

LGTM

Co-authored-by: Rea Rustagi <[email protected]> (cherry picked from commit 12fc8ef)

Co-authored-by: Rea Rustagi <[email protected]> (cherry picked from commit 12fc8ef) Co-authored-by: Mike Woofter <[email protected]>

mongoKart added 10 commits October 11, 2024 22:04

wip

bf4504d

wip

37aabe0

wip

6690f80

wip

cb693cf

first draft

84a3a8a

build fixes

b3d5494

fixes

2a8b99b

fix includes

a335ac2

Merge branch 'master' into docsp-44422-bulk-write

7fc4096

update what's new

7a1729b

rustagir requested changes Oct 17, 2024

View reviewed changes

mongoKart added 2 commits October 18, 2024 08:06

merge

3013cab

feedback

8afa5b8

mongoKart requested a review from rustagir October 18, 2024 13:20

Apply suggestions from code review

4ee975f

Co-authored-by: Rea Rustagi <[email protected]>

rustagir reviewed Oct 18, 2024

View reviewed changes

mongoKart added 3 commits October 22, 2024 09:58

rr feedback

9c4f7bf

feedback

127e288

feedback

9911dd0

mongoKart requested a review from rustagir October 22, 2024 15:07

rustagir approved these changes Oct 23, 2024

View reviewed changes

mongoKart requested review from a team, adelinowona and sanych-sun and removed request for a team and adelinowona October 23, 2024 20:31

sanych-sun suggested changes Oct 29, 2024

View reviewed changes

feedback

95d479c

fixes

d1bc7de

mongoKart requested a review from sanych-sun October 29, 2024 21:09

sanych-sun approved these changes Oct 30, 2024

View reviewed changes

mongoKart added the backport v3.0 label Oct 30, 2024

mongoKart merged commit 12fc8ef into mongodb:master Oct 30, 2024
7 checks passed

mongoKart deleted the docsp-44422-bulk-write branch October 30, 2024 16:33

github-actions bot pushed a commit that referenced this pull request Oct 30, 2024

DOCSP-44422 - Bulk write API (#257)

888aa99

Co-authored-by: Rea Rustagi <[email protected]> (cherry picked from commit 12fc8ef)

github-actions bot mentioned this pull request Oct 30, 2024

[Backport v3.0] DOCSP-44422 - Bulk write API #282

Merged

mongoKart added a commit that referenced this pull request Oct 30, 2024

DOCSP-44422 - Bulk write API (#257) (#282)

87c3bff

Co-authored-by: Rea Rustagi <[email protected]> (cherry picked from commit 12fc8ef) Co-authored-by: Mike Woofter <[email protected]>

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCSP-44422 - Bulk write API #257

DOCSP-44422 - Bulk write API #257

mongoKart commented Oct 16, 2024 •

edited by github-actions bot

Loading

netlify bot commented Oct 16, 2024 •

edited

Loading

rustagir left a comment

rustagir Oct 17, 2024

rustagir Oct 17, 2024

mongoKart Oct 17, 2024

rustagir Oct 17, 2024

mongoKart Oct 17, 2024 •

edited

Loading

rustagir Oct 17, 2024

rustagir Oct 17, 2024

mongoKart Oct 17, 2024

rustagir Oct 18, 2024

mongoKart Oct 22, 2024 •

edited

Loading

rustagir Oct 17, 2024

mongoKart Oct 17, 2024 •

edited

Loading

rustagir Oct 17, 2024

mongoKart Oct 18, 2024

rustagir Oct 17, 2024

rustagir Oct 17, 2024

mongoKart Oct 18, 2024

rustagir Oct 18, 2024

mongoKart Oct 22, 2024

mongoKart commented Oct 18, 2024

rustagir left a comment

rustagir Oct 18, 2024

rustagir Oct 18, 2024

sanych-sun Oct 29, 2024

sanych-sun Oct 29, 2024

sanych-sun Oct 29, 2024 •

edited

Loading

sanych-sun Oct 29, 2024

sanych-sun Oct 29, 2024 •

edited

Loading

sanych-sun Oct 29, 2024

sanych-sun Oct 29, 2024

sanych-sun left a comment

		The examples in this guide use ``BsonDocument`` as the type for ``TDocument``.
		You can also use a Plain Old CLR Object (POCO) as the type for ``TDocument``.

		- Adds an API for bulk write operations. To learn more about bulk write operations, see
		:ref:`csharp-bulk-write`.

DOCSP-44422 - Bulk write API #257

DOCSP-44422 - Bulk write API #257

Conversation

mongoKart commented Oct 16, 2024 • edited by github-actions bot Loading

Pull Request Info

Staging Links

Self-Review Checklist

netlify bot commented Oct 16, 2024 • edited Loading

✅ Deploy Preview for mongodb-docs-csharp ready!

rustagir left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mongoKart Oct 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mongoKart Oct 22, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mongoKart Oct 17, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mongoKart commented Oct 18, 2024

rustagir left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sanych-sun Oct 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sanych-sun Oct 29, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sanych-sun left a comment

Choose a reason for hiding this comment

mongoKart commented Oct 16, 2024 •

edited by github-actions bot

Loading

netlify bot commented Oct 16, 2024 •

edited

Loading

mongoKart Oct 17, 2024 •

edited

Loading

mongoKart Oct 22, 2024 •

edited

Loading

mongoKart Oct 17, 2024 •

edited

Loading

sanych-sun Oct 29, 2024 •

edited

Loading

sanych-sun Oct 29, 2024 •

edited

Loading