(DOCSP-5845): FLE-Encrypted Docs (#154)

Author: jeff-allen-mongo

source/documents.txt

@@ -29,79 +29,109 @@ Query Bar
 
    .. include:: /includes/extracts/query-bar-results.rst
 
-From the :doc:`query bar </query-bar>`, you can specify the query, and
-if you click the :guilabel:`Options`, you can also specify query
-options.
+From the :doc:`query bar </query-bar>`, you can specify a query to
+filter the displayed documents. Click :guilabel:`Options` to
+specify query options.
 
 .. figure:: /images/compass/query-bar-documents-view.png
-  :figwidth: 805px
+  :figwidth: 696px
 
 .. include:: /includes/extracts/query-bar-type-documents.rst
 
+.. seealso::
+
+   :doc:`query-bar`
+
 .. _compass-view-documents:
 
 View Documents
 --------------
 
 Use the Documents tab to view the documents inside of a collection.
-Two different views are available to access documents:
-:ref:`List View <documents-list-view>` and
-:ref:`Table View <documents-table-view>`.
+Two different views are available to access documents: List View and
+Table View.
+
+List View is the default document view. To switch to Table View, click
+the :guilabel:`Table` button to the right of the :guilabel:`List`
+button to access the document Table View.
+
+.. figure:: /images/compass/table-btn.png
+   :figwidth: 696px
+
+.. _docs-list-table-view:
+
+.. tabs::
+
+   .. tab:: List View
+      :tabid: list-view
+
+      List View shows documents as individual members in a list
+      format.
 
-.. _documents-list-view:
+      .. figure:: /images/compass/doc-view.png
 
-List View
-~~~~~~~~~
+      Expand Embedded Objects and Arrays
+      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When the Documents tab loads, Compass displays the List View, which
-shows all documents that match your query criteria
-(or all documents within the sample if no query criteria was
-specified). The documents are shown as individual members in a list format,
-as shown in the following example:
+      To toggle the expansion of embedded objects and array elements in
+      a document, hover over the target document and click the arrow in
+      the top-left corner.
 
-.. figure:: /images/compass/doc-view.png
+      Encrypted Fields
+      ~~~~~~~~~~~~~~~~
 
-To toggle the expansion of nested objects and array elements in a
-document, hover over the target document and click the arrow in the
-top-left corner.
+      .. include:: /includes/fact-fle-description.rst
 
-.. _documents-table-view:
+      .. figure:: /images/compass/encrypted-fields-list.png
+         :figwidth: 696px
+         :alt: Encrypted field in list view
 
-Table View
-~~~~~~~~~~
+   .. tab:: Table View
+      :tabid: table-view
 
-Compass also provides the ability to view your documents in a table,
-rather than as individual items in a list.
+      Table view shows documents as rows of a table. The document
+      fields are shown in the table columns.
 
-Click the :guilabel:`Table` button to the right of the
-:guilabel:`List` button to access the document Table View.
+      .. figure:: /images/compass/doc-table-view.png
+         :figwidth: 696px
 
-.. figure:: /images/compass/doc-table-view.png
-      :figwidth: 805px
+      You can reorder the table columns by clicking and dragging the
+      column headings. Reordering the columns is a strictly cosmetic
+      change and does not change the underlying data itself.
 
-You can reorder the table columns by clicking and dragging the column
-headings. Reordering the columns is a strictly cosmetic change and does
-not change the underlying data itself.
+      Expand Embedded Objects and Arrays
+      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To view nested object fields and array elements, hover your cursor over
-a field with a value type of ``Object`` or ``Array`` and click the
-button with outward-pointing arrows which appears on the right side of
-the field.
+      To view nested object fields and array elements, hover your
+      cursor over a field with a value type of ``Object`` or ``Array`` and click the
+      button with outward-pointing arrows which appears on the right side of
+      the field.
 
-This opens a new tab in the Table View corresponding to the nested
-element.
+      |compass-short| opens a new tab in the Table View corresponding
+      to the nested element.
 
-.. figure:: /images/compass/table-view-expand-nested-elem.png
+      .. figure:: /images/compass/table-view-expand-nested-elem.png
+         :figwidth: 696px
 
-The following example displays the ``delays``
-object nested within the ``flightStats`` collection documents. The
-new tab displays the two properties of the ``delay`` object:
-``arrivalRunwayDelayMinutes`` and ``departureRunwayDelayMinutes``.
+      The following example displays the ``delays``
+      object nested within the ``flightStats`` collection documents. The
+      new tab displays the two properties of the ``delay`` object:
+      ``arrivalRunwayDelayMinutes`` and ``departureRunwayDelayMinutes``.
 
-.. figure:: /images/compass/doc-table-view-nested.png
+      .. figure:: /images/compass/doc-table-view-nested.png
+         :figwidth: 696px
 
-To return to the original table display, click on the first tab
-in the Table View which displays the name of your collection.
+      To return to the original table display, click on the first tab
+      in the Table View which displays the name of your collection.
+
+      Encrypted Fields
+      ~~~~~~~~~~~~~~~~
+
+      .. include:: /includes/fact-fle-description.rst
+
+      .. figure:: /images/compass/encrypted-fields-table.png
+         :figwidth: 696px
+         :alt: Encrypted field in table view
 
 .. _insert-documents:
 
@@ -189,24 +219,36 @@ the data type from ``ObjectID`` to ``string`` and then overwrite the
 Clone Documents
 ---------------
 
-It is also possible to insert new documents by cloning
-the schema and values of an existing document in a collection.
+.. tabs::
 
-To clone a document, hover over the desired document
-and click the :guilabel:`Clone` button.
+   .. tab:: List View
+      :tabid: list-view
 
-.. figure:: /images/compass/clone-doc.png
-  :figwidth: 740px
+      You can insert new documents by cloning the schema and values of
+      an existing document in a collection.
+
+      To clone a document, hover over the desired document
+      and click the :guilabel:`Clone` button.
+
+      .. figure:: /images/compass/clone-doc.png
+        :figwidth: 740px
+
+   .. tab:: Table View
+      :tabid: table-view
 
-Cloning a document works the same way in the
-:ref:`Table View <documents-table-view>` as it does in the
-:ref:`List View <documents-list-view>`:
+      You can insert new documents by cloning the schema and values of an
+      existing document in a collection.
 
-.. figure:: /images/compass/table-view-clone.png
+      To clone a document, hover over the desired document
+      and click the :guilabel:`Clone` button.
 
-Clicking the :guilabel:`Clone` button creates a new insert dialog with
-the same schema and values. You can edit any of these fields and values
-before you insert the new document.
+      .. figure:: /images/compass/table-view-clone.png
+        :figwidth: 696px
+
+When you click the :guilabel:`Clone` button, |compass-short| opens the
+document insertion dialog with the same schema and values as the cloned
+document. You can edit any of these fields and values before you insert
+the new document.
 
 .. figure:: /images/compass/clone-doc2.png
   :figwidth: 702px
@@ -216,16 +258,25 @@ before you insert the new document.
 Modify Documents
 ----------------
 
-To edit a document, hover over the document and select the pencil icon:
+.. tabs::
+
+   .. tab:: List View
+      :tabid: list-view
+
+      To modify a document, hover over the document and click the pencil
+      icon:
+
+      .. figure:: /images/compass/edit-doc.png
+        :figwidth: 696px
 
-.. figure:: /images/compass/edit-doc.png
-  :figwidth: 765px
+   .. tab:: Table View
+      :tabid: table-view
 
-Modifying a document works the same way in the
-:ref:`Table View <documents-table-view>` as it does in the
-:ref:`List View <documents-list-view>`:
+      To modify a document, hover over the document and click the pencil
+      icon:
 
-.. figure:: /images/compass/table-view-modify.png
+      .. figure:: /images/compass/table-view-modify.png
+         :figwidth: 696px
 
 After you click the pencil icon, the document enters edit mode:
 
@@ -318,19 +369,26 @@ Reverting a Change
 While modifying a document, you have the option to revert changes made to a
 field prior to saving the modified document.
 
-To revert changes to a document in the
-:ref:`List View <documents-list-view>`, hover over the edited field
-and click the :guilabel:`revert icon` which appears to the left of the
-field's line number.
+.. tabs::
+
+   .. tab:: List View
+      :tabid: list-view
+
+      To revert changes to a document in the
+      List View, hover over the edited field
+      and click the :guilabel:`revert icon` which appears to the left of the
+      field's line number.
+
+      .. figure:: /images/compass/revert-doc-list-view.png
 
-.. figure:: /images/compass/revert-doc-list-view.png
+   .. tab:: Table View
+      :tabid: table-view
 
-To revert changes to a document in the
-:ref:`Table View <documents-list-view>`, click the
-:guilabel:`revert icon` which appears on the right side of the edited
-table element.
+      To revert changes to a document in the
+      Table View, click the :guilabel:`revert icon` which appears on the 
+      right side of the edited table element.
 
-.. figure:: /images/compass/revert-doc-table-view.png
+      .. figure:: /images/compass/revert-doc-table-view.png
 
 Cancel Changes
 ~~~~~~~~~~~~~~
@@ -341,23 +399,34 @@ click the ``Cancel`` button.
 Delete Documents
 ----------------
 
-From the :guilabel:`Documents` view, you can delete documents by
-hovering over the document and selecting the trash icon:
+.. tabs::
 
-.. figure:: /images/compass/delete-doc.png
-  :figwidth: 740px
+   .. tab:: List View
+      :tabid: list-view
 
-Deleting a document works the same way in the
-:ref:`Table View <documents-table-view>` as it does in the
-:ref:`List View <documents-list-view>`:
+      To delete a document, hover over the document and click the trash icon:
 
-.. figure:: /images/compass/table-view-delete.png
+      .. figure:: /images/compass/delete-doc.png
+        :figwidth: 696px
 
-After clicking the delete button, the document is flagged for deletion
-and Compass asks for confirmation that you want to remove the document:
+      After you click the delete button, the document is flagged for deletion.
+      |compass-short| asks for confirmation that you want to remove the document:
 
-.. figure:: /images/compass/delete-doc2.png
-  :figwidth: 740px
+      .. figure:: /images/compass/delete-doc2.png
+        :figwidth: 740px
+
+   .. tab:: Table View
+      :tabid: table-view
+
+      To delete a document, hover over the document and click the trash icon:
+
+      .. figure:: /images/compass/table-view-delete.png
+         :figwidth: 696px
+
+      After you click the delete button, the document is flagged for deletion.
+      |compass-short| asks for confirmation that you want to remove the document:
+
+      .. figure:: /images/compass/delete-flag-table-view.png
+        :figwidth: 696px
 
-After you confirm, Compass deletes the document
-from the collection.
+Once you confirm, Compass deletes the document from the collection.

source/images/compass/delete-flag-table-view.png

@@ -0,0 +1,4 @@
+|compass-short| obscures document fields encrypted with Field-Level
+Encryption (FLE). |compass-short| displays the values of these fields
+as a series of asterisks. You cannot modify the value of a field
+encrypted with :abbr:`FLE (Field-Level Encryption)`.

source/images/compass/encrypted-fields-list.png

@@ -4,5 +4,5 @@
 - Added support for :ref:`disconnecting <disconnect>` from the active
   MongoDB instance without restarting |compass|.
 
-- Added :ref:`Table View <documents-table-view>` for documents as a
+- Added :ref:`Table View <docs-list-table-view>` for documents as a
   method of viewing the contents of a collection in tabular format.

source/images/compass/encrypted-fields-table.png

@@ -1,4 +1,5 @@
 .. _compass-query-bar:
+.. _querying:
 
 =========
 Query Bar
@@ -61,9 +62,6 @@ options of the query.
 
      - Set the upper limit for the number of documents to return.
 
-.. _querying:
-
-
 Limitations
 -----------