(DOCSP-6955) Add "Convert Field Data Types" page directly to master (#263)

Review on https://github.com/10gen/docs-charts/pull/260

* Structure, WIP

* WIP

* WIP

* WIP

* WIP

* Ready for internal review

* Edit example

* Changes based on review

* Typo

* Table to simplified list

* Release notes date updated

* Changes based on reviews

* Word choice: higher to later

Author: zach-carr

source/build-charts.txt

@@ -27,6 +27,7 @@ Create a Chart
       :titlesonly:
 
       /view-export-chart-data
+      /convert-field-data-types
       /encoding-channels
       /multi-series-charts
       /filter-documents

source/convert-field-data-types.txt

@@ -0,0 +1,127 @@
+.. _convert-field-data-types:
+
+========================
+Convert Field Data Types
+========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+You can convert the data type of the fields returned from your data
+source in the Chart Builder to a different data type. For example, you
+can convert numbers stored as strings to numbers, convert dates stored
+as strings or Unix timestamps to dates, or treat ObjectId fields as
+dates.
+
+Requirements & Limitations
+--------------------------
+
+- Your deployment must use MongoDB 4.0 or later.
+
+- You cannot convert GeoJSON fields.
+
+- You cannot convert arrays nested more than one level deep.
+
+Convert a Field's Data Type
+---------------------------
+
+To convert a field's data type, click on that field and select
+:guilabel:`Convert type` from the :guilabel:`Ellipses (...)` menu.
+
+.. figure:: /images/charts/convert-field-data-type.png
+   :figwidth: 25%
+   :alt: To change a field's data type, click on that field and select "Convert type" from the ellipses menu.
+
+|charts| supports converting data into the following types:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 50 50
+
+   * - Label
+     - BSON Type
+
+   * - :guilabel:`String`
+     - :manual:`String </reference/operator/aggregation/convert/#convert-to-string>`
+
+   * - :guilabel:`Date`
+     - :manual:`Date </reference/operator/aggregation/convert/#convert-to-date>`
+
+   * - :guilabel:`Number`
+     - :manual:`Double </reference/operator/aggregation/convert/#convert-to-double>`
+
+   * - :guilabel:`Boolean`
+     - :manual:`Bool </reference/operator/aggregation/convert/#convert-to-bool>`
+
+Data types are converted by an 
+:manual:`aggregation pipeline </core/aggregation-pipeline>`.
+For each type conversion you select, you can find the underlying
+aggregation stage by
+:ref:`viewing your aggregation pipeline <view-aggregation-pipeline>`.
+
+To see the effects of your conversion on a sample document, 
+:ref:`view a sample source document <view-source-documents>`.
+
+Your conversions are saved with your chart definition.
+
+Convert Data Types in an Array
+------------------------------
+
+You can convert arrays of primitive data and fields of primitive data
+from arrays of documents. Each item in the array is converted to the
+new type. However, if the conversion is invalid or if the original
+value of the item is ``null``, the item converts to ``null``. You
+cannot convert arrays nested more than one level deep.
+
+.. example::
+
+   You have an array of strings:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      ["1", "fish", "42"]
+
+   Applying the :guilabel:`Number` data type conversion returns the
+   following array:
+      
+   .. code-block:: javascript
+      :copyable: false
+
+      [1, null, 45]
+
+.. example::
+
+   You have an array of documents with fields ``foo`` and ``bar``:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      [{foo: "1", bar: "2"}, {foo: "fish", bar: "tacos"}, {foo: "45",
+      bar: "46"}]
+
+   Applying the :guilabel:`Number` data type conversion to the ``foo``
+   field returns the following array of documents:
+
+   .. code-block:: javascript
+      :copyable: false
+
+      [{foo: 1, bar: "2"}, {foo: null, bar: "tacos"}, {foo: 45, bar:
+      "46"}]
+
+Revert a Field's Data Type Conversion
+-------------------------------------
+
+A converted field's icon reflects the new data type and turns green.
+To remove a conversion and return the field to its original data type,
+select :guilabel:`Auto Detect` from the :guilabel:`Ellipses (...)`
+:icon-fa5:`arrow-right` :guilabel:`Convert Type` menu.
+
+.. figure:: /images/charts/converted-field-icon-example.png
+   :figwidth: 70%
+   :alt: A field converted to a string will show a green "A" symbol to indicate its new status.

source/images/charts/convert-field-data-type.png

@@ -13,7 +13,7 @@ Release Notes
 |charts| on |service| v1.7.0
 ----------------------------
 
-*Released October 1, 2019*
+*Released October 2, 2019*
 
 Improvements in this release:
 
@@ -27,8 +27,9 @@ Improvements in this release:
   - :guilabel:`Get Chart Data` to see the data used on the chart and
     export to CSV or JSON.
 
-- Adds the ability to change the data type of fields while building a
-  chart, when using MongoDB 4.0 or higher.
+- Adds the ability to 
+  :ref:`change the data type of fields <convert-field-data-types>`
+  while building a chart, when using MongoDB 4.0 or later.
 
 - Charts can now be placed across the full width of a dashboard on a
   large monitor.