DOCSP-41769: Improved bulk write API #590
Conversation
✅ Deploy Preview for docs-java ready!
To edit notification comments on pull requests, go to your Netlify site configuration. |
…CSP-41769-improved-bulk-write
mayaraman19
requested review from
a team and
katcharov
and removed request for
a team
|
Note that I have neither compiled nor run the examples. |
|
@mayaraman19 could you please not resolve discussions started by a reviewer, as it complicates the review process: the list of unresolved discussions represent the items the reviewer has to re-review, and by resolving them the PR author hides those items from the reviewer. It should be up to the reviewer to decide whether a concern raised by him is resolved. |
|
@stIncMale Thanks for the feedback. I have unresolved comments that I initially resolved, if you want to take another look at those. |
|
😭 This resulted in even more confusion, because I have reviewed all of them, including the resolved ones. But now I will have to re-review them again.
| document, you can use the ``insertOne()`` and ``replaceOne()`` methods. In this | ||
| case, the ``MongoClient`` makes a call to the database for each operation. |
There was a problem hiding this comment.
S: clarify
| document, you can use the ``insertOne()`` and ``replaceOne()`` methods. In this | |
| case, the ``MongoClient`` makes a call to the database for each operation. | |
| document, you can use the ``insertOne()`` and ``replaceOne()`` methods. When you | |
| use these methods, the ``MongoClient`` makes one call to the database for each operation. |
| Generally, you can reduce the number of calls to the database by using bulk write | ||
| operations. You can perform bulk write operations at the following levels: |
There was a problem hiding this comment.
S: 'generally' is a little vague. we can just state a fact instead
| Generally, you can reduce the number of calls to the database by using bulk write | |
| operations. You can perform bulk write operations at the following levels: | |
| By using a bulk write operation, you can perform multiple write operations | |
| in a single database call. You can perform bulk write operations at the following levels: |
| Generally, you can reduce the number of calls to the database by using bulk write | ||
| operations. You can perform bulk write operations at the following levels: | ||
|
|
||
| - :ref:`Collection Level <java-sync-coll-bulk-write>`: You can use the |
There was a problem hiding this comment.
| - :ref:`Collection Level <java-sync-coll-bulk-write>`: You can use the | |
| - :ref:`Collection <java-sync-coll-bulk-write>`: You can use the |
| operations in the same call, but makes two calls to the database for an insert | ||
| operation and a replace operation. | ||
|
|
||
| - :ref:`Client Level <java-sync-client-bulk-write>`: When running {+mdb-server+} |
There was a problem hiding this comment.
| - :ref:`Client Level <java-sync-client-bulk-write>`: When running {+mdb-server+} | |
| - :ref:`Client <java-sync-client-bulk-write>`: When running {+mdb-server+} |
| single collection. This method groups write operations together by the kind | ||
| of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple update |
There was a problem hiding this comment.
S:
| single collection. This method groups write operations together by the kind | |
| of operation. For example, ``MongoCollection.bulkWrite()`` puts multiple update | |
| single collection. In this method, each kind of write operation requires one | |
| database call. For example, ``MongoCollection.bulkWrite()`` puts multiple update |
| to multiple databases and collections in the same cluster. The ``MongoClient.bulkWrite()`` | ||
| method does not split different kinds of operations into different batches. |
There was a problem hiding this comment.
S: if someone jumps straight to this section, they might not see that this line is intended to compare client bulk writes to collection bulk writes.
| to multiple databases and collections in the same cluster. The ``MongoClient.bulkWrite()`` | |
| method does not split different kinds of operations into different batches. | |
| to multiple databases and collections in the same cluster. The ``MongoClient.bulkWrite()`` | |
| method performs all write operation in a single batch. |
| In the examples in preceding sections of this page, the ``MongoCollection.bulkWrite()`` method | ||
| takes a list of ``WriteModel`` instances in which the specified subclass of | ||
| ``WriteModel`` represents the corresponding write operation. For example, an | ||
| instance of ``InsertOneModel`` represents an operation to insert one document. | ||
|
|
||
| Similarly, the ``MongoClient.bulkWrite()`` method takes a |
There was a problem hiding this comment.
S: unfortunately, i think it's worth repeating the info from earlier in the page just to users don't have to read earlier sections if they don't need to. if you have a lot of repeated content, you can always put it in an includes directive 😎
There was a problem hiding this comment.
honestly, I'm not sure how much this information is relevant so I will remove it 👍
| For example, an instance of ``ClientNamespacedInsertOneModel`` represents an | ||
| operation to insert one document. | ||
|
|
||
| You can construct instances of ``ClientNamespacedWriteModel`` using the following |
There was a problem hiding this comment.
| You can construct instances of ``ClientNamespacedWriteModel`` using the following | |
| You can construct instances of the ``ClientNamespacedWriteModel`` class by using the following |
| You can construct instances of ``ClientNamespacedWriteModel`` using the following | ||
| methods: | ||
|
|
||
| - ``insertOne()`` |
There was a problem hiding this comment.
S: would use this pattern for each method and delete the following paragraph
| - ``insertOne()`` | |
| - ``ClientNamespacedWriteModel.insertOne()``: Constructs a ``ClientNamespacedInsertOneModel`` instance. |
| database and collection to write to. Some, such as ``insertOne()``, can take a | ||
| ``Document`` instance that defines information about the write operation. | ||
| Some other methods, such as ``updateOne()`` and ``replaceOne()``, take a filter | ||
| object that defines the subset of documents to be updated or replaced. |
There was a problem hiding this comment.
for comprehensiveness and clarity, we probably want to specify which methods take what. you could give each method its own subsection, or add a parameter list/table for each one
| The ``MongoCollection.bulkWrite()`` method performs each kind of write | ||
| operations in a separate call. For example, when you pass ``DeleteOneModel``, |
There was a problem hiding this comment.
| The ``MongoCollection.bulkWrite()`` method performs each kind of write | |
| operations in a separate call. For example, when you pass ``DeleteOneModel``, | |
| The ``MongoCollection.bulkWrite()`` method performs each kind of write | |
| operation in a separate database call. For example, when you pass ``DeleteOneModel``, |
| ``DeleteManyModel``, and ``ReplaceOneModel`` objects to the method, it creates | ||
| two calls: one for the delete operations and one for the replace operation. |
There was a problem hiding this comment.
You could probably say 'creates two batches' or 'performs two calls', but 'creates two calls' is confusing
| ``DeleteManyModel``, and ``ReplaceOneModel`` objects to the method, it creates | |
| two calls: one for the delete operations and one for the replace operation. | |
| ``DeleteManyModel``, and ``ReplaceOneModel`` objects to the method, it performs | |
| two calls: one for the delete operations and one for the replace operation. |
|
|
||
| .. note:: | ||
|
|
||
| When the client splits operations into calls, it might reorder operations for |
There was a problem hiding this comment.
| When the client splits operations into calls, it might reorder operations for | |
| When the client splits operations into separate database calls, it might reorder operations for |
| - ``namespace``: defines which database and collection to write to | ||
|
|
||
| ``document``: defines the document to insert |
There was a problem hiding this comment.
For all of these parameters, removes 'defines which' or 'defines a' and then capitalize the first letter (e.g., 'Database and collection to write to')
https://www.mongodb.com/docs/meta/style-guide/style/lists/#list-items
|
|
||
| * - ``ClientNamespacedUpdateOneModel`` | ||
| - ``updateOne()`` | ||
| - Creates a model to update at most one document in the ``namespace`` |
There was a problem hiding this comment.
| - Creates a model to update at most one document in the ``namespace`` | |
| - Creates a model to update the first document in the ``namespace`` |
|
|
||
| ``options``: (optional) defines options to apply when updating document | ||
|
|
||
| One of ``update`` or ``updatePipeline`` must be specified. |
There was a problem hiding this comment.
| One of ``update`` or ``updatePipeline`` must be specified. | |
| You must pass a value for either the ``update`` or ``updatePipeline`` parameter. |
|
|
||
| ``options``: (optional) defines options to apply when updating documents | ||
|
|
||
| One of ``update`` or ``updatePipeline`` must be specified. |
There was a problem hiding this comment.
| One of ``update`` or ``updatePipeline`` must be specified. | |
| You must pass a value for either the ``update`` or ``updatePipeline`` parameter. |
|
|
||
| * - ``ClientNamespacedReplaceOneModel`` | ||
| - ``replaceOne()`` | ||
| - Creates a model to replace at most one document in the ``namespace`` that |
There was a problem hiding this comment.
| - Creates a model to replace at most one document in the ``namespace`` that | |
| - Creates a model to replace the first document in the ``namespace`` that |
| - ``updateMany()`` | ||
| * - ``ClientNamespacedDeleteOneModel`` | ||
| - ``deleteOne()`` | ||
| - Creates a model to delete at most one document in the ``namespace`` that |
There was a problem hiding this comment.
| - Creates a model to delete at most one document in the ``namespace`` that | |
| - Creates a model to delete the first document in the ``namespace`` that |
Pull Request Info
PR Reviewing Guidelines
JIRA - DOCSP-41769
Staging:
Self-Review Checklist