(DOCSP-22450): Add clearer disambiguation between standard / on-demand views (#1355)

* WIP

* wip

* (DOCSP-22450): Add clearer disambiguation between standard / on-demand views

* remove broken include

* add indexing behavior

* more clarifications

* wording

* add sub-sections

* add links

* mild refactoring

* wording

* typo and wording

* more wording

* wording and formatting

* updates per review feedback

* clarify that ODM views can use out

* wording

Author: jeff-allen-mongo

source/core/materialized-views.txt

@@ -6,23 +6,35 @@ On-Demand Materialized Views
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 .. meta::
    :description: MongoDB on-demand materialized view
    :keywords: MongoDB, materialized view
 
 .. note:: Disambiguation
 
-   This page discusses on-demand materialized views, which are stored on
-   and read from disk. For discussion of standard views, which are
-   computed on-demand and not stored to disk, see
-   :ref:`views-landing-page`.
-
-Starting in version 4.2, MongoDB adds the :pipeline:`$merge` stage for
-the :doc:`aggregation pipeline </core/aggregation-pipeline>`. This
-stage can merge the pipeline results to an existing collection instead
-of completely replacing the collection. This functionality allows users
-to create on-demand materialized views, where the content of the output
-collection can be updated each time the pipeline is run.
+   This page discusses on-demand materialized views. For discussion of
+   standard views, see :ref:`views-landing-page`.
+
+   To understand the differences between the view types, see
+   :ref:`materialized-view-compare`.
+
+An on-demand materialized view is a pre-computed aggregation pipeline
+result that is stored on and read from disk. On-demand materialized
+views are typically the results of a :pipeline:`$merge` or
+:pipeline:`$out` stage.
+
+.. _materialized-view-compare:
+
+Comparison with Standard Views
+------------------------------
+
+.. include:: /includes/views/fact-compare-view-and-materialized-view.rst
 
 Example
 -------

source/core/views.txt

@@ -39,6 +39,13 @@ You can use views to:
   order history. Your application can query the view without managing or
   understanding the underlying pipeline.
 
+.. _view-materialized-view-compare:
+
+Comparison with On-Demand Materialized Views
+--------------------------------------------
+
+.. include:: /includes/views/fact-compare-view-and-materialized-view.rst
+
 .. _manual-views-behavior:
 
 Behavior
@@ -51,13 +58,6 @@ Read Only
 
 Views are read-only. Write operations on views return an error.
 
-Index Use
-~~~~~~~~~
-
-Views use the indexes of the underlying collection. As a result, you
-cannot create, drop or re-build indexes on the view directly, nor get
-a list of indexes on the view.
-
 View Pipelines
 ~~~~~~~~~~~~~~
 

source/includes/views/disambiguate-standard-materialized.rst

@@ -1,6 +1,7 @@
 .. note:: Disambiguation
 
-   This page discusses standard views, which are computed on-demand and
-   not stored to disk. For discussion of on-demand materialized views,
-   which are stored on and read from disk, see
-   :ref:`manual-materialized-views`.
+   This page discusses standard views. For discussion of on-demand
+   materialized views, see :ref:`manual-materialized-views`.
+
+   To understand the differences between the view types, see
+   :ref:`view-materialized-view-compare`.

source/includes/views/fact-compare-view-and-materialized-view.rst

@@ -0,0 +1,28 @@
+MongoDB provides two different view types: **standard views** and
+**on-demand materialized views**. Both view types return the results
+from an aggregation pipeline.
+
+- Standard views are computed when you read the view, and are not stored
+  to disk.
+
+- On-demand materialized views are stored on and read from disk. They
+  use a :pipeline:`$merge` or :pipeline:`$out` stage to update the saved
+  data.
+
+Indexes
+~~~~~~~
+
+Standard views use the indexes of the underlying collection. As a
+result, you cannot create, drop or re-build indexes on a standard view
+directly, nor get a list of indexes on the view.
+
+You can create indexes directly on on-demand materialized views because
+they are stored on disk.
+
+Performance
+~~~~~~~~~~~
+
+On-demand materialized views provide better read performance than
+standard views because they are read from disk instead of computed as
+part of the query. This performance benefit increases based on the
+complexity of the pipeline and size of the data being aggregated.