P1: CRUD usage examples moved to appropriate pages

source/crud/read-operations/retrieve.txt

@@ -4,12 +4,18 @@
 Retrieve Data
 ==============
 
+.. facet::
+   :name: genre
+   :values: reference
 
+.. meta::
+   :keywords: find, findOne, findMany, get, lookup, code example
+   :description: Learn about how to retrieve documents in the {+driver-long+}.
 
 .. contents:: On this page
    :local:
    :backlinks: none
-   :depth: 1
+   :depth: 2
    :class: singlecol
 
 Overview
@@ -46,15 +52,24 @@ track of the color and quantity, which corresponds to the ``color`` and
 Find Operation
 --------------
 
-Use the find operation to retrieve a subset of your existing data in
-MongoDB. You can specify what data to return including which documents
-to retrieve, in what order to retrieve them, and how many to retrieve.
-
-To perform a find operation, call the ``find()`` method on an instance
-of a ``MongoCollection``. This method searches a collection for documents that
-match the query filter you provide. For more information about how to
-specify a query, see our :ref:`Specify a Query
-<java-query>` guide.
+Use the find operation to retrieve your documents from MongoDB. You can specify
+which documents to retrieve, in what order to retrieve them, and how many to
+retrieve. 
+
+Call the ``find()`` method on an instance of a ``MongoCollection`` to filter for
+documents that match the provided query. For more information about how to
+specify a query, see our :doc:`Specify a Query </crud/query-document>` guide.
+You can then use methods such as ``forEach()``  or ``cursor()`` to retrieve
+matching documents. For more information, see the `FindIterable
+<{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html>`__
+API documentation.
+
+To retrieve a single document, you can add the ``first()`` method to your
+``find()`` call. To choose a specific document, you can use the ``sort()``
+operation before selecting the first document. You may also want to use the
+``limit()`` method to optimize memory usage. For more information, see the
+server manual for more information about :manual:`memory optimization when using
+the sort operation </reference/operator/aggregation/sort/#-sort----limit-memory-optimization>`. 
 
 Example
 ~~~~~~~
@@ -84,8 +99,34 @@ The following shows the output of the preceding query:
 After the owner runs this query, they find two orders that matched the
 criteria.
 
-For a runnable ``find()`` example, see our :ref:`Find Multiple
-Documents <retrieve-find>` page.
+.. _java-usage-find:
+
+Find Example: Full File
+~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/crud/example-intro.rst
+
+This example is a complete, standalone file that performs the following actions:
+
+- Calls the ``find()`` method to retrieve 10 documents that has a ``runtime``
+  value less than ``15`` minutes, applying a projection and sort to the results  
+- Calls the ``find()`` and ``first()`` methods to retrieve the document with the
+  highest ``imdb.rating`` that is has a ``runtime`` value less than ``15``
+  minutes, applying a projection to the result
+
+.. io-code-block::
+
+   .. input:: /includes/crud/Find.java
+      :language: java
+      :dedent:
+
+   .. output:: 
+      :language: none
+      :visible: false
+
+      10 movies under 15 minutes: 10 Minutes, 3x3, 7:35 in the Morning, 8, 9, A Chairy Tale, A Corner in Wheat, A Gentle Spirit, A Is for Autism, A Movie, 
+
+      The highest rated movie under 15 minutes: {"title": "Andrè and Wally B.", "imdb": {"rating": 5.4, "votes": 3294, "id": 86855}}
 
 .. _retrieve-aggregate:
 
@@ -101,7 +142,8 @@ instance of a ``MongoCollection``. This method accepts aggregation
 expressions to run in sequence. To perform aggregations, you can
 define aggregation stages that specify how to match documents, rename
 fields, and group values. For more information, see our
-:ref:`Aggregation <java-aggregation>` guide.
+:ref:`Aggregation <java-aggregation>` guide and the :ref:`Aggregation Expression
+Operations <java-aggregation-expression-operations>` page.
 
 Example
 ~~~~~~~
@@ -136,8 +178,27 @@ purchased color.
 For more information about how to construct an aggregation pipeline, see
 the {+mdb-server+} manual page on :manual:`Aggregation </aggregation>`.
 
-For additional information on the methods mentioned on this page, see
-the following API Documentation:
+Additional Information
+----------------------
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+For more information about the methods and classes used to retrieve documents
+on this page, see the following API documentation:
+
+- `find() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#find()>`__
+- `first() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#first()>`__
+- `limit() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#limit(int)>`__
+- `FindIterable <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html>`__
+- `aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__
+
+Server Manual Entries
+~~~~~~~~~~~~~~~~~~~~~
 
-- `MongoCollection.find() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#find()>`__
-- `MongoCollection.aggregate() <{+api+}/apidocs/mongodb-driver-sync/com/mongodb/client/MongoCollection.html#aggregate(java.util.List)>`__
+- :manual:`Collections </core/databases-and-collections/#collections>`
+- :manual:`Query Documents </tutorial/query-documents>`
+- :manual:`Aggregation </aggregation>`
+   - :manual:`$sort </aggregation/sort>`
+   - :manual:`$limit </aggregation/limit>`
+- :manual:`Aggregation stages </meta/aggregation-quick-reference/#stages>`

source/crud/write-operations/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/write-operations/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/>`