Merge pull request #54 from steveren/DOCSP-2592

DOCSP-2592: Schema page revisions

Author: steveren

source/images/compass/collection-schema.png

@@ -1,16 +1,16 @@
 ref: query-bar-results
-content: |  
-   For large query result sets, the results are shown from a sampled set
-   of documents.  Otherwise, Compass shows the entire result set.
+content: |
+   For query result sets larger than 1000 documents, Compass
+   shows a sampling of the results.  Otherwise, Compass
+   shows the entire result set.
    
    For details on sampling, see the :ref:`FAQ <compass-faq-sampling>`. 
 ---
 ref: query-bar-type-schema
 content: |
    You can type MongoDB queries into the query bar. In the query
-   expression, you can use the various MongoDB :manual:`query operators
-   </reference/operator/query/>` except for the :query:`$text` query
-   operator.
+   expression, you can use any MongoDB :manual:`query operator
+   </reference/operator/query/>` except :query:`$text`.
 
    As you type, the :guilabel:`Analyze` button is disabled and the
    :guilabel:`Filter` label turns red until a valid query is entered.

source/images/compass/number-sample2.png

@@ -14,18 +14,55 @@ Schema
 
 .. _schema-tab:
 
-Schema Tab
-----------
-
-The :guilabel:`Schema` tab reports on the documents in the collections.
-The report is based on :ref:`sampling of the documents
-<compass-faq-sampling>` in the collection.
+Schema Tab Overview
+-------------------
+
+The :guilabel:`Schema` tab provides an overview of the data type
+and shape of the fields in a particular collection. Databases
+and collections are visible in the left-side navigation.
+
+The overview is based on :ref:`sampling <compass-faq-sampling>`
+the documents in the collection. The schema overview may include
+additional data about the contents of the fields, such as the
+minimum and maximum values of dates and integers, the frequency of
+occurrence of particular values, and the cardinality of the data.
+
+MongoDB has a :manual:`flexible schema model
+</core/data-modeling-introduction/>`, which means that some fields may
+contain different types of data from one document to the next. For
+example, a field named ``address`` may contain strings and integers
+in some documents, objects in others, or some combination of all three.
+In the case of heterogenous fields, the :guilabel:`Schema` tab shows a
+breakdown of the various data types contained within the field with the
+percentage of each data type represented.
+
+In the example below, the :guilabel:`Schema` tab shows size
+information about the ``test.restaurants`` collection at the top,
+including the total number of documents in the collection, the
+average document size, and the total disk space occupied by the
+collection.
+
+The following fields are shown with details:
+
+- The ``_id`` field is an :manual:`ObjectId
+  </reference/bson-types/index.html#objectid>`. Each ObjectId
+  contains a timestamp, so Compass displays the range of creation times
+  for the sampled documents.
+
+- The ``address`` field contains four nested fields. You
+  can expand the field panel to see analyses of each of the nested
+  fields.
+
+- The ``borough`` field contains a string indicating the borough in
+  which the restaurant is located. The cardinality is low enough
+  that Compass can provide a graded bar of the field contents, with the
+  most-frequently occurring string on the left.
+
+- The ``categories`` field contains arrays of strings. The analysis
+  shows the minimum, maximum, and average array lengths.
 
 .. figure:: /images/compass/collection-schema.png
-   :figwidth: 817px
-
-To access the :guilabel:`Schema` tab for a collection, click on a
-collection on the left hand pane and select the :guilabel:`Schema` tab.
+   :figwidth: 750px
 
 Query Bar
 ---------
@@ -34,9 +71,10 @@ Query Bar
 
    .. include:: /includes/extracts/query-bar-results.rst
 
-From the :doc:`query bar </query-bar>` in the :guilabel:`Schema` tab, you can specify the
-query, and if you click the :guilabel:`Options`, you can also specify
-query options.
+Using the :doc:`query bar </query-bar>` in the :guilabel:`Schema` tab,
+you can create a query filter to limit your result set. Click the
+:guilabel:`Options` button to specify query options, such as the
+particular fields to display and the number of results to return.
 
 .. figure:: /images/compass/query-bar-schema-view.png
    :figwidth: 730px
@@ -48,27 +86,30 @@ query options.
    In the :guilabel:`Schema` tab, you can also use the :ref:`build-query` to
    enter a query into the query bar.
 
-Charts
-------
+Field Descriptions
+------------------
 
-For a field, Compass displays the data types and values with various
-charts. The data type information is on the left hand side; the field
-value information is on the right.
+For each field, Compass displays summary information about the data
+type or types the field contains and the range of values. Depending
+on the data type and the level of cardinality, Compass displays
+histograms, graded bars, geographical maps, and sample data to provide
+a sense of the shape and scope of the data contained in each field.
 
-Field with Single Type Values
+Field with a Single Data Type
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Below is an example of a chart showing a field called ``last_login``
-which contains data of type ``date``.
+Below is an example of the data type summary for a field called
+``last_login`` which contains data of type ``date``.
 
 .. figure:: /images/compass/field-example.png
    :figwidth: 330px
 
-Field with Multiple Type Values
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Field with Multiple Data Types
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The charts also display a percentage breakdown for fields with varying
-data types across documents. In the example below,
+For fields that contain multiple data types,
+Compass displays a percentage breakdown of 
+the various data types across documents. In the example below,
 the chart shows the contents of a field called ``phone_no`` in which
 81% of documents are of type ``string``, and the remaining 19% are of
 type ``number``.
@@ -122,7 +163,7 @@ Numbers
 ~~~~~~~
 
 Numbers are similar to strings in their representation.
-Entirely unique numbers are shown in the following manner:
+Unique numbers are shown in the following manner:
 
 .. figure:: /images/compass/number-sample.png
    :figwidth: 764px
@@ -198,6 +239,9 @@ Query Builder
 
 In the :guilabel:`Schema` tab, you can type the filter manually into
 the query bar or generate the filter with the Compass query builder.
+The query builder allows you to select data elements from one or more
+fields in your schema and construct a query matching the selected
+elements.
 
 .. tip::
 
@@ -209,6 +253,9 @@ Composing ``$OR`` filter conditions is not yet possible with the
 clickable query builder, but you can manually enter them in the query
 bar.
 
+The following procedure describes the steps involved in
+building a complex query with the query bar.
+
 .. include:: /includes/steps/create-query-via-builder.rst
 
 .. note::