(DOCSP-8265-fix) Compass Import/Export improvements (#236)

* (DOCSP-8265) Update Compass import/export procedures

* Updated from copy review

* Add sampling note

* Updates from copy review

* Final copy review

Author: zach-carr

source/images/compass/export-data-dialog-1.png

@@ -49,32 +49,46 @@ that it is formatted correctly.
        name: JSON
        content: |
 
-         When importing data from a **JSON** file, each document must exist on
-         its own line in the file. Do not use commas at the end of lines to
-         separate documents.
+         When importing data from a **JSON** file, you can format your 
+         data as:
+
+         - Newline-delimited documents, or
+
+         - Comma-separated documents in an array
 
          .. example::
 
-            The following ``.json`` file imports three documents:
+            The following newline-delimited ``.json`` file is formatted 
+            correctly:
 
             .. code-block:: javascript
 
                { "type": "home", "number": "212-555-1234" }
                { "type": "cell", "number": "646-555-4567" }
                { "type": "office", "number": "202-555-0182"}
 
-            |compass| automatically generates :manual:`ObjectIDs
+            The following comma-separated ``.json`` array file is also 
+            formatted correctly:
+
+            .. code-block:: javascript
+
+               [{ "type": "home", "number": "212-555-1234" }, { "type": "cell", "number": "646-555-4567" }, { "type": "office", "number": "202-555-0182"}]
+
+            |compass-short| ignores line breaks in JSON arrays.
+
+            |compass-short| automatically generates :manual:`ObjectIDs
             </reference/method/ObjectId/>` for these objects on import
             since no ObjectIDs were specified in the initial JSON.
 
      - id: csv
        name: CSV
        content: |
 
-         When importing data from a **CSV** file, the first line of the file
-         must be a comma-separated list of your document field names. Subsequent
-         lines in the file must be comma-separated field values in the order
-         corresponding with the field order in the first line.
+         When importing data from a **CSV** file, the first line of the 
+         file must be a comma-separated list of your document field 
+         names. Subsequent lines in the file must be comma-separated 
+         field values in the order corresponding with the field order 
+         in the first line.
 
          .. example::
 
@@ -109,9 +123,8 @@ Export Data from a Collection
 
 |compass| can export data from a collection as either a
 **JSON** or **CSV** file. If you specify a
-:ref:`filter <query-bar-filter>` in the
-:ref:`query bar <compass-query-bar>` prior to export, |compass-short|
-can optionally only export documents which match the specified query.
+:ref:`filter <query-bar-filter>`, |compass-short| only exports 
+documents which match the specified query.
 
 Behavior
 ~~~~~~~~
@@ -136,20 +149,6 @@ Procedure
 
       .. include:: /includes/fact-export-progress-bar.rst
 
-      Example
-      ```````
-
-      The following example exports the entire ``test.people``
-      collection as a ``.json`` file called ``test-export.json``:
-
-      .. figure:: /images/compass/export-data-example.png
-         :alt: Export data example
-         :figwidth: 600px
-
-      The specified ``{ age: 24 }`` query is ignored and the entire
-      collection is exported because the
-      :guilabel:`Export Full Collection` toggle is enabled.
-
    .. tab:: Export Filtered Subset of a Collection
       :tabid: export-filter
 
@@ -158,15 +157,3 @@ Procedure
       .. include:: /includes/steps/export-filter.rst
 
       .. include:: /includes/fact-export-progress-bar.rst
-
-      Example
-      ```````
-
-      The following example a filtered subset of the
-      ``test.flightStats`` collection as a CSV file called
-      ``cvg-msp.csv``. Only documents with an ``arrivalAirportFsCode``
-      of either ``CVG`` or ``MSP`` are included in hte export.
-
-      .. figure:: /images/compass/export-data-filter-example.png
-         :alt: Export data with filter example
-         :figwidth: 600px

source/images/compass/export-data-dialog-2.png

@@ -1,46 +1,78 @@
-title: Navigate to the :doc:`collection </collections>` you wish to export data from.
+title: Navigate to the :doc:`collection </collections>` you wish to 
+       export data from.
 level: 4
 ref: select-collection
 content: |
   You can either select the collection from the
   :doc:`Collections </collections>` tab or click the collection in the
   left-hand pane.
+
 ---
 title: "Specify a filter in the Query Bar"
 level: 4
 ref: export-specify-filter
 content: |
-  Specify a :ref:`filter <query-bar-filter>` in the :ref:`query bar <compass-query-bar>` to export only the documents which match
-  the filter.
+  Specify a :ref:`filter <query-bar-filter>` in the 
+  :ref:`query bar <compass-query-bar>` to export only the documents 
+  which match the filter.
+
 ---
-title: Click :guilabel:`Collection` in the top-level menu and select :guilabel:`Export Collection`
+title: Click :guilabel:`Collection` in the top-level menu and select 
+       :guilabel:`Export Collection`
 level: 4
 ref: export-collection
 content: |
-
-  |
-
   .. figure:: /images/compass/export-data-filter-option-select.png
      :alt: Export data select menu
 
   |compass-short| displays the following dialog:
 
   .. figure:: /images/compass/export-data-dialog-filter.png
      :alt: Export data dialog
-     :figwidth: 600px
+     :width: 70%
 
   The top section of the export dialog displays the query
-  entered in the query bar.
+  entered in the query bar. If you did not specify a query in the query 
+  bar, you can specify a query here.
+
 ---
-title: Choose the appropriate file type.
+title: Select document fields to include in your exported file.
 level: 4
-ref: click-file-type
+ref: select-export-fields
 content: |
-    Under :guilabel:`Select Output File Type`, select either JSON or CSV.
+  Only fields that are checked are included in the exported file.
+
+  You can add document fields to include with the :guilabel:`Add Field` 
+  button if the field you want to include is not automatically detected.
+
+  .. figure:: /images/compass/export-data-dialog-2.png
+     :alt: Export data dialog, step 2
+     :width: 70%
+
+  .. note::
+     
+     |compass-short| samples your collection to pre-populate a list of 
+     fields. Fields which only appear in a small percentage of 
+     documents may not be automatically detected.
+
+     For details on sampling, see the :ref:`FAQ <compass-faq-sampling>`.
+
 ---
-title: Under :guilabel:`Select File`, choose where to export the file.
+title: Choose the appropriate file type.
 level: 4
-ref: click-file-location
+ref: click-file-type
+content: |
+  Under :guilabel:`Select Export File Type`, select either 
+  :guilabel:`JSON` or :guilabel:`CSV`. If you select :guilabel:`JSON`,
+  your data is exported to the target file as a comma-separated 
+  array of JSON objects.
+
+  Then, under :guilabel:`Output`, choose where to export the file to.
+
+  .. figure:: /images/compass/export-data-dialog-3.png
+     :alt: Export data dialog, step 3
+     :width: 70%
+
 ---
 title: Click :guilabel:`Export`.
 level: 4

source/images/compass/export-data-dialog-3.png

@@ -1,4 +1,5 @@
-title: Navigate to the :doc:`collection </collections>` you wish to export data from.
+title: Navigate to the :doc:`collection </collections>` you wish to 
+       export data from.
 level: 4
 ref: select-collection
 content: |
@@ -7,36 +8,59 @@ content: |
   left-hand pane.
 
 ---
-title: Click :guilabel:`Collection` in the top-level menu and select :guilabel:`Export Collection`
+title: Click :guilabel:`Collection` in the top-level menu and select 
+       :guilabel:`Export Collection`.
 level: 4
 ref: export-collection
 content: |
-
-  |
-
   .. figure:: /images/compass/export-data-option-select.png
      :alt: Export data select menu
 
   |compass-short| displays the following dialog:
 
-  .. figure:: /images/compass/export-data-dialog.png
-     :alt: Export data dialog
-     :figwidth: 600px
+  .. figure:: /images/compass/export-data-dialog-1.png
+     :alt: Export data dialog, step 1
+     :width: 70%
+
+  The export dialog initially displays the query entered in the query 
+  bar prior to export, if applicable. If no query was specified, this 
+  section displays a ``find`` operation with no parameters, which 
+  returns all documents in the collection.
+
+  To ignore the query filter and export your entire collection, select 
+  :guilabel:`Export Full Collection` and click 
+  :guilabel:`Select Fields`.
 
-  The top section of the export dialog displays the query entered in the
-  query bar prior to export, if applicable. Use this query to filter
-  which collection documents are exported. If no query was specified,
-  this section displays ``undefined``.
 ---
-title: Choose the appropriate file type.
+title: Select document fields to include in your exported file.
 level: 4
-ref: click-file-type
+ref: select-export-fields
 content: |
-    Under :guilabel:`Select Output File Type`, select either JSON or CSV.
+  Only fields that are checked are included in the exported file.
+
+  You can add document fields to include with the :guilabel:`Add Field` 
+  button if the field you want to include is not automatically detected.
+
+  .. figure:: /images/compass/export-data-dialog-2.png
+     :alt: Export data dialog, step 2
+     :width: 70%
+
 ---
-title: Under :guilabel:`Select File`, choose where to export the file.
+title: Choose a file type and export location.
 level: 4
-ref: click-file-location
+ref: click-file-type
+content: |
+  Under :guilabel:`Select Export File Type`, select either 
+  :guilabel:`JSON` or :guilabel:`CSV`. If you select :guilabel:`JSON`, 
+  your data is exported to the target file as a comma-separated 
+  array.
+
+  Then, under :guilabel:`Output`, choose where to export the file to.
+
+  .. figure:: /images/compass/export-data-dialog-3.png
+     :alt: Export data dialog, step 3
+     :width: 70%
+
 ---
 title: Click :guilabel:`Export`.
 level: 4

source/images/compass/export-data-dialog-filter.png

@@ -1,4 +1,5 @@
-title: Navigate to the :doc:`collection </collections>` you wish to import data into.
+title: Navigate to the :doc:`collection </collections>` you wish to 
+       import data into.
 level: 4
 ref: select-collection
 content: |
@@ -7,7 +8,8 @@ content: |
   left-hand pane.
 
 ---
-title: Click the :guilabel:`Add Data` dropdown and select :guilabel:`Import File`.
+title: Click the :guilabel:`Add Data` dropdown and select 
+       :guilabel:`Import File`.
 level: 4
 ref: import-data
 content: |
@@ -19,25 +21,63 @@ content: |
 
   .. figure:: /images/compass/import-data-dialog.png
      :alt: Import data dialog
+     :width: 70%
 
 ---
-title: Choose the appropriate file type of the source data file. 
+title: Select the location of the source data file under 
+       :guilabel:`Select File`.
+level: 4
+ref: click-file-location
+content: ""
+
+---
+title: Choose the appropriate file type.
 level: 4
 ref: choose-file-type
 content: |
-  Under :guilabel:`Select Input File Type`, select either JSON or CSV. 
+
+  Under :guilabel:`Select Input File Type`, select either 
+  :guilabel:`JSON` or :guilabel:`CSV`. 
+
+  If you are importing a CSV file, you may specify fields to import and 
+  the types of those fields under :guilabel:`Specify Fields and Types`. 
+  The default data type for all fields is string.
+
+  .. figure:: /images/compass/import-csv-options.png
+     :alt: Select fields to import from a CSV file
+     :width: 70%
+
+  To exclude a field from a CSV file you are importing, uncheck the 
+  checkbox next to that field name. To select a type for a field, use 
+  the dropdown menu below that field name.
 
 ---
-title: Select the location of the source data file under :guilabel:`Select File`.
+title: Configure import options.
 level: 4
-ref: click-file-location
+ref: import-options
 content: |
-  .. raw:: html
+  Under :guilabel:`Options`, configure the import options for your use 
+  case.
+  
+  If you are importing a CSV file, you may select how your data 
+  is delimited.
+
+  For both JSON and CSV file imports, you can toggle 
+  :guilabel:`Ignore empty strings` and :guilabel:`Stop on errors`:
+
+  - If checked, :guilabel:`Ignore empty strings` drops fields with 
+    empty string values from your imported documents. The document is 
+    still imported with all other fields.
+
+  - If checked, :guilabel:`Stop on errors` prevents any data from being 
+    imported in the event of an error. If unchecked, data is inserted 
+    until an error is encountered and successful inserts are not rolled 
+    back. The import operation will not continue after encountering an 
+    error in either case.
 
-     <br>
 ---
 title: Click :guilabel:`Import`. 
 level: 4
 ref: click-import
-
+content: ""
 ...