DOCSP-10482: rearrange CRUD landing page content (#111)

* DOCSP-10482: rearrange CRUD landing page content

Author: Chris Cho

source/fundamentals/crud.txt

@@ -12,210 +12,16 @@ CRUD Operations
    /fundamentals/crud/query-document
    /fundamentals/crud/compound-operations
 
-Overview
---------
-
 CRUD (Create, Read, Update, Delete) operations allow you to work with
-the data stored inside of MongoDB. We categorized the CRUD operations into
-two sections: :ref:`crud-read-operations` and :ref:`crud-write-operations`.
-
-.. note::
-
-   CRUD operations execute **asynchronously** because the driver
-   communicates with MongoDB over the network, which is subject to
-   latency, timeouts, and other complications that can delay execution
-   during synchronous communication. You can specify a callback in the
-   CRUD method call to capture the response. If you do not specify a
-   callback, the operation returns a
-   :mdn:`Promise <Web/JavaScript/Reference/Global_Objects/Promise>` that
-   resolves to the output of the operation. We use the ``async``/``await``
-   syntax for Promise resolution in our examples.
-
-.. _crud-read-operations:
-
-Read Operations
----------------
-
-Read operations find and return documents stored within MongoDB.
-There are multiple types of read operation that allow you to
-access data in different ways. While some read operations focus on
-allowing you to view data that exists in the database, other operations
-let you monitor the database for new data that matches certain criteria,
-and still other read operations let you apply a series of
-transformations and filters to all documents in a collection before
-returning a result set. The driver offers methods for each variant of
-read operation:
-
-Find
-~~~~
-
-If you want to view documents already in a collection, you can use
-:doc:`find() </usage-examples/find>` and
-:doc:`findOne() </usage-examples/findOne>`. These methods accept a
-query document that describes the documents you would like to view.
-While ``findOne()`` returns a single document, ``find()`` returns a
-:doc:`cursor </fundamentals/crud/read-operations/cursor>` that you can
-use to navigate matched documents.
-
-.. example::
-
-   A pizza restaurant wants to find all pizzas ordered by Lemony Snicket
-   yesterday. They run the following ``find()`` query on the
-   ``orders`` collection:
-
-   .. literalinclude:: /code-snippets/crud/pizza.js
-      :language: javascript
-      :start-after: start find crud example
-      :end-before: end find crud example
-      :dedent: 4
-
-Aggregate
-~~~~~~~~~
-
-If you want to create custom processing pipelines for documents in a
-collection, you can use ``aggregate()``. This method accepts a
-pipeline of aggregation commands to run in sequence. These commands let
-you filter, summarize, and augment documents in a collection into a result
-set for viewing.
-
-.. example::
-
-   A pizza restaurant wants to run a status report on-demand to
-   summarize pizza orders over the past week. They run the following
-   ``aggregate()`` query on the ``orders`` collection:
-
-   .. literalinclude:: /code-snippets/crud/pizza.js
-      :language: javascript
-      :start-after: start aggregate crud example
-      :end-before: end aggregate crud example
-      :dedent: 4
-
-.. _watch-subscribe:
-
-Watch / Subscribe
-~~~~~~~~~~~~~~~~~
-
-You can use the ``watch()`` method if you want to monitor a collection for
-new, update, replace, and deleted documents that match a certain criteria.
-You can pass this method a pipeline of aggregation commands that
-sequentially run on new data whenever write operations run on the collection.
-
-.. example::
-
-   A pizza restaurant wants to get a notification whenever a new pizza
-   order comes in. They run the following ``watch()`` query on the
-   ``orders`` collection:
-
-   .. literalinclude:: /code-snippets/crud/pizza.js
-      :language: javascript
-      :start-after: start watch crud example
-      :end-before: end watch crud example
-      :dedent: 4
-
-.. note::
-
-   You can customize read operations to
-   :doc:`skip </fundamentals/crud/read-operations/skip>` a certain
-   number of documents at the beginning of the collection of matched
-   documents, :doc:`limit </fundamentals/crud/read-operations/limit>`
-   the number of returned documents, and :doc:`sort
-   </fundamentals/crud/read-operations/sort>` returned documents in a
-   particular order.
-
-.. _crud-write-operations:
-
-Write Operations
-----------------
-
-CRUD write operations add, modify, and remove data in MongoDB. Sometimes
-this means putting entirely new data into a collection, but other times
-it involves changing data that already exists, or even removing it
-entirely. There are three distinct write operations: create, update, and
-delete. The driver offers methods for each variant of write operation:
-
-Insert
-~~~~~~
-
-If you want to add new documents to a collection, you can use
-:doc:`insertOne() </usage-examples/insertOne>` or
-:doc:`insertMany() </usage-examples/insertMany>`. These methods accept a
-single document or a collection of documents respectively. Note that the
-driver will generate a unique ``_id`` field automatically for any
-inserted documents that lack such a field.
-
-.. example::
-
-   A pizza restaurant creates an order every time a customer requests
-   a pizza. They run the following ``insertOne()`` query on the
-   ``orders`` collection:
-
-   .. literalinclude:: /code-snippets/crud/pizza.js
-      :language: javascript
-      :start-after: start insert crud example
-      :end-before: end insert crud example
-      :dedent: 4
-
-Update / Replace
-~~~~~~~~~~~~~~~~
-
-If you want to alter existing documents in a collection, you can use
-:doc:`updateOne() </usage-examples/updateOne>`,
-:doc:`replaceOne() </usage-examples/replaceOne>`, or
-:doc:`updateMany() </usage-examples/updateMany>`. These methods
-accept a query document that describes the documents you would like to
-change and an `update document <updateDocument>`_ that describes
-the changes you would like to apply to matched documents.
-``replaceOne()`` uses a `replacement document
-<replacementDocument>`_ that describes an entirely new document instead
-of an update document. You can configure any update operation to behave
-as an :doc:`upsert </fundamentals/crud/write-operations/upsert>` instead
-of an update.
-
-.. example::
-
-   A pizza restaurant wants to modify the delivery address for an order
-   that already exists. They run the following ``updateOne()`` query on
-   the ``orders`` collection:
-
-   .. literalinclude:: /code-snippets/crud/pizza.js
-      :language: javascript
-      :start-after: start update crud example
-      :end-before: end update crud example
-      :dedent: 4
-
-Delete
-~~~~~~
-
-If you want to remove existing documents from a collection, you can
-use :doc:`deleteOne() </usage-examples/deleteOne>` or
-:doc:`deleteMany() </usage-examples/deleteMany>`. These methods accept a
-query document that describes the documents you would like to delete.
-Delete operations will delete either one (in the case of
-``deleteOne()``) or all (in the case of ``deleteMany()``) documents that
-match the query.
-
-.. example::
-
-   A pizza restaurant wants to delete a cancelled order. They run the
-   following ``deleteOne()`` query on the ``orders`` collection:
-
-   .. literalinclude:: /code-snippets/crud/pizza.js
-      :language: javascript
-      :start-after: start delete crud example
-      :end-before: end delete crud example
-      :dedent: 4
-
-.. note::
+the data stored in MongoDB.
 
-   You can customize write operations to
-   :doc:`upsert </fundamentals/crud/write-operations/upsert>` instead of
-   update, time out if the method fails to complete within a certain
-   period of time, and write with varying levels of resilience in a
-   replica set.
+The CRUD operation documentation is categorized in two sections:
 
-Compound operations
--------------------
+- :doc:`Read Operations </fundamentals/crud/read-operations>` find and return 
+  documents stored within your MongoDB database.
+- :doc:`Write Operations </fundamentals/crud/write-operations>` insert, modify,
+  or delete documents in your MongoDB database.
 
-Some operations combine aspects of read and write operations. Consult
-:doc:`compound operations </fundamentals/crud/compound-operations>` to
-learn more about these hybrid methods.
+Some operations combine aspects of read and write operations. See our
+guide on :doc:`compound operations </fundamentals/crud/compound-operations>`
+to learn more about these hybrid methods.

source/fundamentals/crud/read-operations.txt

@@ -7,10 +7,11 @@ Read Operations
 .. toctree::
    :caption: Read Operations
 
+   /fundamentals/crud/read-operations/retrieve
+   /fundamentals/crud/read-operations/cursor
    /fundamentals/crud/read-operations/sort
    /fundamentals/crud/read-operations/skip
    /fundamentals/crud/read-operations/limit
    /fundamentals/crud/read-operations/project
-   /fundamentals/crud/read-operations/cursor
    /fundamentals/crud/read-operations/geo
    /fundamentals/crud/read-operations/text

source/fundamentals/crud/read-operations/retrieve.txt

@@ -0,0 +1,161 @@
+=============
+Retrieve Data
+=============
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+You can use read operations to retrieve data from your MongoDB database.
+There are multiple types of read operations that access the data in
+different ways. If you want to request results based on a set of criteria
+from the existing set of data, you can use a find operation such as the 
+``find()`` or ``findOne()`` methods.
+
+You can also further specify the information you are requesting by
+including additional parameters or by chaining other methods such as:
+
+- :doc:`Sort Results </fundamentals/crud/read-operations/sort>`
+- :doc:`Skip Returned Results </fundamentals/crud/read-operations/skip>`
+- :doc:`Limit the Number of Returned Results </fundamentals/crud/read-operations/limit>`
+- :doc:`Specify Which Fields to Return </fundamentals/crud/read-operations/project>`
+
+You can also use an aggregation operation to retrieve data. This type of 
+operation allows you to apply an ordered pipeline of transformations to the 
+matched data.
+
+If you want to monitor the database for incoming data that matches a set of
+criteria, you can use the watch operation to be notified in real-time when 
+matching data is inserted.
+
+Find
+----
+
+The ``find()`` method is called on the ``Collection`` object that
+references the collection you want to query. The method accepts a query
+document that describes the documents you want to retrieve. For more
+information on how to specify your query document, see our guide on
+how to :doc:`Specify a Query </fundamentals/crud/query-document>`.
+
+To access the results, you can optionally pass a callback in the method
+call or resolve the returned ``Promise`` object. See our guide on
+:doc:`Promises and Callbacks </fundamentals/promises>` for more
+information.
+
+If you resolve the ``Promise`` returned by ``find()``, you receive
+a reference to a ``Cursor`` with which you can navigate matched documents.
+If you resolve the ``Promise`` returned by ``findOne()``, you receive the
+matching document or ``null`` if there are no matches.
+
+.. example::
+
+   A pizza restaurant wants to find all pizzas ordered by Lemony Snicket
+   yesterday. They run the following ``find()`` query on the
+   ``orders`` collection:
+
+   .. literalinclude:: /code-snippets/crud/pizza.js
+      :language: javascript
+      :start-after: start find crud example
+      :end-before: end find crud example
+      :dedent: 4
+
+
+   Once the operation returns, the ``findResult`` variable references a 
+   ``Cursor``. You can print the documents retrieved using the ``forEach()``
+   method as shown below:
+
+   .. code-block:: javascript
+      
+      await cursor.forEach(console.dir);
+
+
+   The output might resemble the following:
+
+   .. code-block:: none
+
+      [
+        { name: "Lemony Snicket", type: "horseradish pizza", qty: 1, status: "delivered", date: ... },
+        { name: "Lemony Snicket", type: "coal-fired oven pizza", qty: 3, status: "canceled", date: ...},
+        ...
+      ]
+
+See the :doc:`find() </usage-examples/find>` and :doc:`findOne()
+</usage-examples/findOne>` for fully-runnable examples.
+
+Aggregate
+---------
+
+If you want to run a custom processing pipeline to retrieve data from your
+database, you can use the ``aggregate()`` method. This method accepts
+aggregation expressions to run in sequence. These expressions let you filter,
+group, and arrange the result data from a collection.
+
+.. example::
+
+   A pizza restaurant wants to run a status report on-demand to
+   summarize pizza orders over the past week. They run the following
+   ``aggregate()`` query on the ``orders`` collection to fetch the
+   totals for each distinct "status" field:
+
+   .. literalinclude:: /code-snippets/crud/pizza.js
+      :language: javascript
+      :start-after: start aggregate crud example
+      :end-before: end aggregate crud example
+      :dedent: 4
+
+
+   Once the operation returns, the ``aggregateResult`` variable references a 
+   ``Cursor``. You can print the documents retrieved using the ``forEach()``
+   method as shown below:
+
+   .. code-block:: javascript
+      
+      await cursor.forEach(console.dir);
+
+
+   The output might resemble the following:
+
+   .. code-block:: none
+
+      [
+        { _id: 'delivering', count: 5 },
+        { _id: 'delivered', count: 37 },
+        { _id: 'created', count: 9 },
+      ]
+
+See the MongoDB server manual pages on :manual:`aggregation </aggregation>`
+for more information on how to construct an aggregation pipeline.
+
+Watch / Subscribe
+-----------------
+
+You can use the ``watch()`` method to monitor a collection for changes to
+a collection that match certain criteria. These changes include inserted,
+updated, replaced, and deleted documents. You can pass this method
+a pipeline of aggregation comands that sequentially runs on the changed
+data whenever write operations are executed on the collection.
+
+.. example::
+
+   A pizza restaurant wants to receive a notification whenever a new pizza
+   order comes in. To accomplish this, they create an aggregation pipeline
+   to filter on insert operations and return specific fields. They pass
+   this pipeline to the ``watch()`` method called on the ``orders``
+   collection as shown below:
+
+   .. literalinclude:: /code-snippets/crud/pizza.js
+      :language: javascript
+      :start-after: start watch crud example
+      :end-before: end watch crud example
+      :dedent: 4
+
+
+For a runnable example of the ``watch()`` method using the NodeJS driver, see
+the :doc:`change streams </usage-examples/changeStream>` usage example.