Merge branch 'master' into DOCSP-48094-bom

Author: rustagir

source/crud/bulk.txt

@@ -358,6 +358,35 @@ see the following API documentation:
 - `BulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html>`__
 - `ordered() <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html#ordered(boolean)>`__
 
+.. _java-usage-bulkwrite:
+
+Bulk Write Example: Full File
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/crud/example-intro.rst
+
+The following code is a complete, standalone file that performs the following
+actions:
+
+#. Creates a list of instances of the ``InsertOneModel``, ``UpdateOneModel``,
+   ``DeleteOneModel``, and ``ReplaceOneModel`` classes.
+#. Runs an ordered ``bulkWrite()`` operation that performs the writes specified in the model list.
+
+.. io-code-block::
+
+   .. input:: /includes/crud/BulkWrite.java
+      :language: java
+      :dedent:
+
+   .. output:: 
+      :language: none
+      :visible: false
+
+      Result statistics:
+      inserted: 3
+      updated: 2
+      deleted: 1
+
 .. _java-sync-client-bulk-write:
 
 Client Bulk Write
@@ -594,55 +623,31 @@ Even though the write operation inserting a document with a duplicate key result
 in an error, the other operations are executed because the write operation is
 unordered.
 
-To learn more about the methods and classes mentioned in this section,
-see the following API documentation:
+Additional Information
+----------------------
 
-- `ClientBulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientBulkWriteOptions.html>`__
-- `ClientBulkWriteResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientBulkWriteResult.html>`__
-
-Summary
--------
-
-``MongoCollection.bulkWrite()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To perform a bulk operation, you create and pass a list of
-``WriteModel`` instances to the ``bulkWrite()`` method. 
-
-There are 6 different ``WriteModel`` subtypes: ``InsertOneModel``,
-``ReplaceOneModel``, ``UpdateOneModel``, ``UpdateManyModel``,
-``DeleteOneModel`` and ``DeleteManyModel``. 
-
-There are two ways to execute the ``bulkWrite()`` method: 
-
-- Ordered, which performs the bulk operations in order until an error occurs, if any
-- Unordered, which performs all the bulk operations in any order and reports errors
-  at the end, if any
+API Documentation
+~~~~~~~~~~~~~~~~~
 
-To learn more about the collection ``bulkWrite`` command, see the 
-:manual:`db.collection.bulkWrite() </reference/method/db.collection.bulkWrite/>`
-method reference in the {+mdb-server+} Manual.
+To learn more about the methods and classes used to perform bulk write
+operations in this section, see the following API documentation:
 
-``MongoClient.bulkWrite()``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+MongoCollection
+```````````````
 
-When connecting to a deployment running {+mdb-server+} version 8.0 or later, you 
-can use the ``MongoClient.bulkWrite()`` method to perform bulk operations on multiple 
-databases and collections at once.
+- `bulkWrite() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__
+- `BulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/BulkWriteOptions.html>`__
+- `MongoBulkWriteException <{+api+}/apidocs/mongodb-driver-core/com/mongodb/MongoBulkWriteException.html>`__
 
-To perform a client bulk operation, you create an pass a list of 
-``ClientNamespacedWriteModel`` instances to this method.
+MongoClient
+```````````
 
-There are six subtypes of ``ClientNamespacedWriteModel`` that are used to
-represent write operations. To construct these write models, you can use the
-corresponding ``ClientNamespacedWriteModel`` methods ``insertOne()``, ``updateOne()``, 
-``updateMany()``, ``replaceOne()``, ``deleteOne()``, and ``deleteMany()``. These 
-methods take a ``MongoNamespace`` object that defines which
-database and collection to write to.
+- `bulkWrite() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCluster.html#bulkWrite(com.mongodb.client.ClientSession,java.util.List)>`__
+- `ClientBulkWriteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientBulkWriteOptions.html>`__
+- `ClientBulkWriteResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/bulk/ClientBulkWriteResult.html>`__
 
-The ``MongoClient.bulkWrite()`` method can also take a ``ClientBulkWriteOptions``
-object to specify different options for how the command is executed.
+Server Manual Entries
+~~~~~~~~~~~~~~~~~~~~~
 
-To learn more about the client ``bulkWrite`` command, see the 
-:manual:`bulkWrite() </reference/command/bulkWrite/>` method reference in the {+mdb-server+}
-Manual.
+- :manual:`MongoCollection.bulkWrite() </reference/method/db.collection.bulkWrite/>`
+- :manual:`MongoClient.bulkWrite() </reference/command/bulkWrite/>`

source/crud/delete.txt

@@ -4,6 +4,14 @@
 Delete Documents
 ================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: remove, clear, reset, code example
+   :description: Learn about how to delete documents in the {+driver-long+}.
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -147,14 +155,54 @@ collection:
     { "_id": 1, "color": "red", "qty": 5 }
     { "_id": 8, "color": "black", "qty": 8 }
 
-For more information about the methods and classes mentioned in this guide,
-see the following resources:
-
-- `deleteOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteOne(org.bson.conversions.Bson)>`__ API Documentation 
-- `deleteMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteMany(org.bson.conversions.Bson)>`__ API Documentation
-- `findOneAndDelete() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#findOneAndDelete(org.bson.conversions.Bson)>`__ API Documentation
-- `DeleteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteOptions.html>`__ API Documentation
-- `FindOneAndDeleteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/FindOneAndDeleteOptions.html>`__ API Documentation
-- :manual:`db.collection.deleteOne() </reference/method/db.collection.deleteMany/>` Server Manual Entry
-- :manual:`db.collection.deleteMany() </reference/method/db.collection.deleteOne/>` Server Manual Entry
-- :manual:`db.collection.findOneAndDelete() </reference/method/db.collection.findOneAndDelete/>` Server Manual Entry
+.. _java-usage-deletemany:
+.. _java-usage-deleteone:
+
+Delete Example: Full File
+-------------------------
+
+.. include:: /includes/crud/example-intro.rst
+
+The following code is a complete, standalone file that performs a delete one
+operation and a delete many operation: 
+
+.. io-code-block::
+
+   .. input:: /includes/crud/Delete.java
+      :language: java
+      :dedent:
+
+   .. output:: 
+      :language: none
+      :visible: false
+
+      Deleted document count - query for one: 1
+      Deleted document count - unlimited query: 4
+
+
+The queries in these examples use the ``eq()`` and ``lt()`` filters to query documents. For more
+information about filters, see the `Filters Class
+<{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/Filters.html>`__
+API documentation.
+
+Additional Information
+----------------------
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information about the methods and classes used to delete documents, see the following API documentation: 
+
+- `deleteOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteOne(org.bson.conversions.Bson)>`__  
+- `deleteMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#deleteMany(org.bson.conversions.Bson)>`__ 
+- `findOneAndDelete() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#findOneAndDelete(org.bson.conversions.Bson)>`__ 
+- `DeleteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/DeleteOptions.html>`__ 
+- `FindOneAndDeleteOptions <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/model/FindOneAndDeleteOptions.html>`__ 
+- `DeleteResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/DeleteResult.html>`__ 
+
+Server Manual Entries
+~~~~~~~~~~~~~~~~~~~~~
+
+- :manual:`db.collection.deleteOne() </reference/method/db.collection.deleteOne/>`
+- :manual:`db.collection.deleteMany() </reference/method/db.collection.deleteMany/>`
+- :manual:`db.collection.findOneAndDelete() </reference/method/db.collection.findOneAndDelete/>`

source/crud/insert.txt

@@ -4,6 +4,14 @@
 Insert Operations
 =================
 
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: add, save, code example
+   :description: Learn about how to insert documents in the {+driver-long+}.
+
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -30,28 +38,23 @@ The following sections focus on ``insertOne()`` and
 method, see our
 :ref:`guide on Bulk Operations <java-fundamentals-bulkwrite>`. 
 
-A Note About ``_id``
---------------------
-
-When inserting a document, MongoDB enforces one constraint on your
-documents by default: each document *must* contain a unique ``_id``
-field. 
+.. note:: The ``id_`` Field in Insert Operations
 
-There are two ways to manage this field:
+   When inserting a document, MongoDB enforces one constraint on your
+   documents by default: each document *must* contain a unique ``_id`` value.
+   Duplicate ``_id`` values violate unique index constraints, resulting in a
+   ``WriteError``. 
 
-- You can manage this field yourself, ensuring each value you use is unique.
-- You can let the driver automatically generate unique ObjectId values.
+   There are two ways to manage this field:
 
-Unless you have provided strong guarantees for uniqueness, we recommend
-you let the driver automatically generate ``_id`` values. 
+   - You can manage this field yourself, ensuring each value you use is unique.
+   - You can let the driver automatically generate unique ObjectId values.
 
-.. note::
-
-   Duplicate ``_id`` values violate unique index constraints, resulting
-   in a ``WriteError``. 
- 
-For additional information on unique indexes, see the manual entry on 
-:manual:`Unique Indexes </core/index-unique/>`.
+   Unless you have provided strong guarantees for uniqueness, we recommend
+   you let the driver automatically generate ``_id`` values.  
+   
+   For more information about unique indexes, see the manual entry on 
+   :manual:`Unique Indexes </core/index-unique/>`.
 
 .. _java-insertone:
 
@@ -159,26 +162,48 @@ The output of the preceding code resembles the following:
 .. code-block::
    :copyable: false
 
-   Inserted documents with the following ids: [60930c3aa982931c20ef6cd7, 60930c3aa982931c20ef6cd8] 
+   Inserted documents with the following ids: [60930c3aa982931c20ef6cd7,
+   60930c3aa982931c20ef6cd8] 
 
-For more information about the methods and classes mentioned in this section,
-see the following resources: 
+.. _java-usage-insertmany:
+.. _java-usage-insertone:
+
+Insert Example: Full File
+-------------------------
+
+.. include:: /includes/crud/example-intro.rst
+
+The following code is a complete, standalone file that performs an insert one
+operation and an insert many operation: 
+
+.. io-code-block::
+
+   .. input:: /includes/crud/Insert.java
+      :language: java
+      :dedent:
+
+   .. output:: 
+      :language: none
+      :visible: false
+
+      insertOne() document id: BsonObjectId{value=...}
+      insertMany() document ids: {0=BsonObjectId{value=...}, 1=BsonObjectId{value=...}}
 
-- `insertMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertMany(java.util.List)>`__ API Documentation
-- `InsertManyResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertManyResult.html>`__ API Documentation
-- Manual Explanation on :manual:`insertMany() </reference/method/db.collection.insertMany/>`
-- Runnable :ref:`Insert Multiple Documents Example <java-usage-insertmany>`
+Additional Information
+----------------------
 
-Summary
--------
+API Documentation
+~~~~~~~~~~~~~~~~~
 
-There are three ways to perform an insert operation, but we focused on two:
+For more information about the methods and classes used to insert documents, see the following API documentation: 
 
-- The ``insertOne()`` method inserts a single document.
-- The ``insertMany()`` method inserts multiple documents.
+- `insertOne() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertOne(TDocument)>`__
+- `InsertOneResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertOneResult.html>`__
+- `insertMany() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#insertMany(java.util.List)>`__
+- `InsertManyResult <{+api+}/apidocs/mongodb-driver-core/com/mongodb/client/result/InsertManyResult.html>`__ 
 
-Both methods automatically generate an ``_id`` if you omit the field in
-your document. 
+Server Manual Entries
+~~~~~~~~~~~~~~~~~~~~~
 
-If the insertion is successful, both methods return an instance
-representing the ``_id`` of each new document.
+- :manual:`db.collection.insertOne() </reference/method/db.collection.insertOne/>`
+- :manual:`db.collection.insertMany() </reference/method/db.collection.insertMany/>`