Docsp 5829 - Updates for Views (#152)

* WIP

* WIP

* (DOCSP-5829): Updates for Views

* Updates per Nick's feedback

Author: jeff-allen-mongo

source/aggregation-pipeline-builder.txt

@@ -17,12 +17,12 @@ Aggregation Pipeline Builder
 The Aggregation Pipeline Builder in |compass| provides the ability to
 create :manual:`aggregation pipelines </core/aggregation-pipeline/>` to
 process data. With aggregation pipelines, documents in a collection
-pass through multiple stages where they are processed into a set of
-aggregated results. The particular stages and results can be modified
-depending on your application's needs.
+or view pass through multiple stages where they are processed into a
+set of aggregated results. The particular stages and results can be
+modified depending on your application's needs.
 
 To access the aggregation pipeline builder, navigate to the
-:doc:`collection </collections>` for which you wish to create an
+:doc:`collection or view </collections>` for which you wish to create an
 aggregation pipeline and click the :guilabel:`Aggregations` tab. You
 are presented with a blank aggregation pipeline. The
 :guilabel:`Preview of Documents in the Collection` section of the
@@ -69,9 +69,10 @@ The :pipeline:`$out` stage is not available if you are connected to a
 Save a Pipeline
 ---------------
 
-You can save your pipeline so it can be reloaded into
-the pipeline builder in the future. You can also create a
-:manual:`view </core/views/>` from the results of your pipeline.
+You can save a pipeline so that you can access it later. If you
+load a saved pipeline, you can modify it without
+changing the original saved copy. You can also create a :ref:`view
+<view-details>` from your pipeline results.
 
 To save your pipeline:
 
@@ -82,6 +83,8 @@ To save your pipeline:
 
 #. Click :guilabel:`Save`.
 
+.. _create-a-view:
+
 Create a View from Pipeline Results 
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -92,17 +95,7 @@ Create a View from Pipeline Results
 
 To create a view from your pipeline results:
 
-1. Click the arrow next to the :guilabel:`Save` button at the top
-   of the pipeline builder.
-
-#. Click :guilabel:`Create a View`.
-
-#. Enter a name for your view.
-
-#. Click :guilabel:`Create`.
-
-|compass-short| creates a view from your pipeline results in the same
-database where the pipeline was created.
+.. include:: /includes/fact-create-view-from-pipeline.rst
 
 .. _open-saved-pipeline:
 

source/collections.txt

@@ -1,8 +1,8 @@
 .. _collection-tab:
 
-================
-Collections View
-================
+=====================
+Collections and Views
+=====================
 
 .. default-domain:: mongodb
 
@@ -14,24 +14,34 @@ Collections View
 
 .. include:: /includes/extracts/readonly-not-permitted-collections.rst
 
-Collections View
-----------------
+.. _collections-screen:
 
-The :guilabel:`Collections` view lists the existing
-:manual:`collections </core/databases-and-collections/#collections>`
-in the selected database and general information for each collection.
-To access the :guilabel:`Collections` view for a database, from the
-:doc:`Databases tab </databases>` either:
+Collections Screen
+------------------
+
+The :guilabel:`Collections` screen lists the existing
+:ref:`collections <compass-collections>` and
+:ref:`views <compass-views>` in the selected database. Each
+list item includes the name and other general information for
+the specific collection/view.
+
+To access the :guilabel:`Collections` screen for a database, from the
+:doc:`Databases screen </databases>` either:
 
 - Click a :guilabel:`Database Name` in the main :guilabel:`Databases`
   view, or
 
-- Click a database in the left-hand pane.
+- Click a database in the left navigation.
 
 .. figure:: /images/compass/select-database.png
    :figwidth: 750px
 
-The :guilabel:`Collections` view displays the following
+.. _compass-collections:
+
+Collections
+~~~~~~~~~~~
+
+The :guilabel:`Collections` screen displays the following
 information for each collection in the selected database:
 
 - Collection name
@@ -44,20 +54,35 @@ information for each collection in the selected database:
   collection. Hover over a :guilabel:`Collation` banner to view
   the properties for that collection.
 
-.. figure:: /images/compass/collection-tab2.png
-   :figwidth: 720px
+.. _compass-views:
+
+Views
+~~~~~
 
-You can also :ref:`create <create-collection>` or
-:ref:`drop collections <drop-collection>` from this view.
+Views are read-only results of an aggregation run against a collection. 
+The :guilabel:`Collections` screen displays the following information
+for each view in the selected database:
+
+- View name
+- Collection from which the view was created
+- Total size of all documents in the view
+- Total size of all indexes on the collection
+
+|compass-short| explicitly marks views in the left navigation with
+a unique icon:
+
+.. figure:: /images/compass/view-icon.png
+   :scale: 50%
+   :alt: View icon
+
+For more information on views, see :ref:`view-details`.
 
 .. _create-collection:
 
 Create a Collection
 -------------------
 
-In addition to the initial collection created during the :ref:`database
-creation <create-database>`, you can create new collections in an
-existing database.
+You can create new collections in an existing database.
 
 .. include:: /includes/steps/create-collection.rst
 
@@ -70,34 +95,33 @@ Drop a Collection
 
 .. _collection-details:
 
-View Collection Details
------------------------
+Collection Details
+------------------
 
-The Collection Detail view shows detailed information for a
-collection, including the documents the collection contains. To view
+The Collection Detail screen shows detailed information for a
+collection, including the documents the collection contains. To see
 collection details, either:
 
 - Click a :guilabel:`Collection Name` in the main
-  :guilabel:`Collections` view, or
+  :guilabel:`Collections` screen, or
 
-- Click a collection in the left-hand pane.
+- Click a collection in the left navigation.
 
 .. figure:: /images/compass/select-collection.png
   :figwidth: 750px
 
-|compass| provides the following collection information in the
-detailed view:
+After you select a collection, |compass-short| shows you that
+collection's :doc:`Documents tab </documents>`. |compass-short| provides the following
+collection information and functionality in the detailed view:
 
 - :doc:`/documents`
-- :doc:`/schema` *Not Available in Compass Community Edition*
+- :doc:`Import and Export Data </import-export/>` to / from the collection
+- :ref:`compass-agg-builder`
+- :doc:`Schema Analysis </schema>` *Not Available in Compass Community Edition*
 - :doc:`/query-plan`
 - :doc:`/indexes`
 - :doc:`/validation` *Not Available in Compass Community Edition*
 
-You can also import and export documents to and from the selected
-collection from this view. For more information on this process,
-see :doc:`Import and Export Data </import-export/>`.
-
 .. class:: hidden
 
    .. toctree::
@@ -109,5 +133,6 @@ see :doc:`Import and Export Data </import-export/>`.
       /query-plan
       /indexes
       /validation
+      /views
 
 .. |home| unicode:: U+2302

source/documents.txt

@@ -20,7 +20,7 @@ Documents Tab
 -------------
 
 From the :guilabel:`Documents` tab, you can view, insert, clone,
-modify, and delete documents.
+modify, and delete documents in your selected collection or view.
 
 Query Bar
 ---------

source/images/compass/view-icon.png

@@ -0,0 +1,11 @@
+1. Click the arrow next to the :guilabel:`Save` button at the top
+   of the pipeline builder.
+
+#. Click :guilabel:`Create a View`.
+
+#. Enter a name for your view.
+
+#. Click :guilabel:`Create`.
+
+|compass-short| creates a view from your pipeline results in the same
+database where the pipeline was created.

source/images/compass/view-list.png

@@ -2,7 +2,7 @@ title: Click the :guilabel:`Create Collection` button.
 level: 4
 ref: create-collection
 content: |
-    From the :guilabel:`Collections` view, click the
+    From the :guilabel:`Collections` screen, click the
     :guilabel:`Create Collection` button.
 ---
 title: Enter the collection information.

source/includes/fact-create-view-from-pipeline.rst

@@ -2,7 +2,7 @@ title: Click the trash can icon to delete a collection.
 level: 4
 ref: drop-collection
 content: |
-    From the :guilabel:`Collections` view, click on the trash can for
+    From the :guilabel:`Collections` screen, click on the trash can for
     the collection to delete. A confirmation dialog appears.
 ---
 title: Confirm the collection to delete.

source/includes/steps-create-collection.yaml

@@ -0,0 +1,106 @@
+.. _view-details:
+
+=====
+Views
+=====
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+Views are read-only results of an
+:ref:`aggregation <compass-agg-builder>` run against a collection.
+Views provide easy access to the results of an aggregation
+without requiring the reader of the view to execute the pipeline.
+Views can also help keep your data secure by only giving users
+access to a predefined result set,
+as opposed to having access to the underlying collection.
+
+|compass-short| displays views in the :ref:`Collections Screen <collection-tab>` with
+a special icon, and indicates the collection from which
+the view was created.
+
+.. figure:: /images/compass/view-list.png
+   :figwidth: 720px
+   :alt: View list
+
+Create a View
+-------------
+
+To create a view, you must use the :ref:`compass-agg-builder`.
+The output of your pipeline's final stage becomes the content of
+the view.
+
+To create a view from your pipeline results:
+
+1. Create an aggregation pipeline in the pipeline builder.
+
+#. Click the arrow next to the :guilabel:`Save` button at the top
+   of the pipeline builder.
+
+#. Click :guilabel:`Create a View`.
+
+#. Enter a name for your view.
+
+#. Click :guilabel:`Create`.
+
+|compass-short| creates a view from your pipeline results in the same
+database where the pipeline was created.
+
+Open a View
+-----------
+
+To open a view, either:
+
+- Click the desired view from the
+  :ref:`Collections screen <collections-screen>`, or
+
+- Click the desired view in the left-hand navigation.
+
+After you open a view, |compass-short| shows you that
+view's :doc:`Documents Tab </documents>`. |compass-short| provides the following
+information and functionality for the view:
+
+- :doc:`/documents`
+- :ref:`compass-agg-builder` to aggregate based on your view
+- :doc:`/schema` *Not Available in Compass Community Edition*
+- :doc:`/query-plan`
+- :doc:`/indexes`
+- :doc:`/validation` *Not Available in Compass Community Edition*
+
+Duplicate a View
+----------------
+
+You can duplicate a view to modify an existing view while retaining the
+original.
+
+To duplicate a view:
+
+1. Hover over the desired view in the left navigation.
+
+#. Click the appearing :guilabel:`Ellipses (...)` button.
+
+#. In the dropdown, click :guilabel:`Duplicate View`.
+
+#. Enter a name for the new view.
+
+#. Click :guilabel:`Duplicate`.
+
+Drop a View
+-----------
+
+To drop a view from the database:
+
+1. Hover over the desired view in the left navigation.
+
+#. Click the appearing :guilabel:`Ellipses (...)` button.
+
+#. In the dropdown, click :guilabel:`Drop View`.
+
+#. In the modal, enter the name of the view.
+
+#. Click :guilabel:`Drop Collection`.