(DOCSP-12214): Add Data Types page (#42)

Author: jeff-allen-mongo

source/reference.txt

@@ -11,4 +11,5 @@ Reference
 
       /reference/options
       /reference/methods
+      /reference/data-types
       /reference/access-mdb-shell-help

source/reference/access-mdb-shell-help.txt

@@ -1,8 +1,8 @@
 .. _mdb-shell-help:
 
-===========================
-Access the |mdb-shell| Help
-===========================
+==========================
+Access Help in ``mongosh``
+==========================
 
 .. default-domain:: mongodb
 

source/reference/data-types.txt

@@ -0,0 +1,360 @@
+=========================
+Data Types in ``mongosh``
+=========================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 1
+   :class: singlecol
+
+MongoDB :term:`BSON` provides support for additional data types than
+:term:`JSON`. :ecosystem:`Drivers </drivers>` provide native support for
+these data types in host languages and ``mongosh`` also provides several
+helper classes to support the use of these data types. See the
+:manual:`Extended JSON </reference/mongodb-extended-json>` reference for
+additional information.
+
+.. _mongo-shell-data-type:
+
+Types
+-----
+
+.. _mongo-shell-date-type:
+
+Date
+~~~~
+
+``mongosh`` provides various methods to return the date, either as a
+string or as a ``Date`` object:
+
+- ``Date()`` method which returns the current date as a string.
+
+- ``new Date()`` constructor which returns a ``Date`` object using the
+  ``ISODate()`` wrapper.
+
+- ``ISODate()`` constructor which returns a ``Date`` object using the
+  ``ISODate()`` wrapper.
+
+Return Date as a String
+```````````````````````
+
+To return the date as a string, use the ``Date()`` method, as in the
+following example:
+
+.. code-block:: javascript
+
+   var myDateString = Date();
+
+To print the value of the variable, type the variable name in the
+shell, as in the following:
+
+.. code-block:: javascript
+
+   myDateString
+
+The result is the value of ``myDateString``:
+
+.. code-block:: javascript
+
+   Wed Dec 19 2012 01:03:25 GMT-0500 (EST)
+
+To verify the type, use the ``typeof`` operator, as in the following:
+
+.. code-block:: javascript
+
+   typeof myDateString
+
+The operation returns ``string``.
+
+Return ``Date``
+```````````````
+
+``mongosh`` wraps objects of ``Date`` type with the
+``ISODate`` helper; however, the objects remain of type ``Date``.
+
+The following example uses both the ``new Date()`` constructor and the
+``ISODate()`` constructor to return ``Date`` objects.
+
+.. code-block:: javascript
+
+   var myDate = new Date();
+   var myDateInitUsingISODateWrapper = ISODate();
+
+You can use the ``new`` operator with the ``ISODate()`` constructor as
+well.
+
+To print the value of the variable, type the variable name in the
+shell, as in the following:
+
+.. code-block:: javascript
+
+   myDate
+
+The result is the ``Date`` value of ``myDate`` wrapped in the
+``ISODate()`` helper:
+
+.. code-block:: javascript
+
+   ISODate("2012-12-19T06:01:17.171Z")
+
+To verify the type, use the ``instanceof`` operator, as in the
+following:
+
+.. code-block:: javascript
+
+   myDate instanceof Date
+   myDateInitUsingISODateWrapper instanceof Date
+
+The operation returns ``true`` for both.
+
+ObjectId
+~~~~~~~~
+
+``mongosh`` provides the ``ObjectId()`` wrapper class around the
+:ref:`objectid` data type. To generate a new ObjectId, use the following
+operation in ``mongosh``:
+
+.. code-block:: javascript
+
+   new ObjectId
+
+.. seealso::
+
+   :method:`ObjectId`
+
+.. _shell-type-long:
+
+NumberLong
+~~~~~~~~~~
+
+``mongosh`` treats all numbers as floating-point values by default.
+``mongosh`` provides the ``NumberLong()`` wrapper to handle 64-bit
+integers.
+
+The ``NumberLong()`` wrapper accepts the long as a string:
+
+.. code-block:: javascript
+
+   NumberLong("2090845886852")
+
+The following examples use the ``NumberLong()`` wrapper to write to the
+collection:
+
+.. code-block:: javascript
+
+   db.collection.insertOne( { _id: 10, calc: NumberLong("2090845886852") } )
+   db.collection.updateOne( { _id: 10 },
+                         { $set:  { calc: NumberLong("2555555000000") } } )
+   db.collection.updateOne( { _id: 10 },
+                         { $inc: { calc: NumberLong("5") } } )
+
+Retrieve the document to verify:
+
+.. code-block:: javascript
+
+   db.collection.findOne( { _id: 10 } )
+
+In the returned document, the ``calc`` field contains a
+``NumberLong`` object:
+
+.. code-block:: sh
+
+   { "_id" : 10, "calc" : NumberLong("2555555000005") }
+
+If you use the :update:`$inc` to increment the value of a field that
+contains a ``NumberLong`` object by a **float**, the data type changes
+to a floating point value, as in the following example:
+
+#. Use :update:`$inc` to increment the ``calc`` field by ``5``, which
+   ``mongosh`` treats as a float:
+
+   .. code-block:: javascript
+
+      db.collection.updateOne( { _id: 10 },
+                            { $inc: { calc: 5 } } )
+
+#. Retrieve the updated document:
+
+   .. code-block:: javascript
+
+      db.collection.findOne( { _id: 10 } )
+
+   In the updated document, the ``calc`` field contains a floating
+   point value:
+
+   .. code-block:: sh
+
+      { "_id" : 10, "calc" : 2555555000010 }
+
+.. note::
+
+   In the legacy :binary:`~bin.mongo` shell, ``NumberLong`` can accept
+   either a string or integer value. In ``mongosh``, ``NumberLong`` can
+   only accept a string value.
+
+.. _shell-type-int:
+
+NumberInt
+~~~~~~~~~
+
+``mongosh`` treats all numbers as floating-point values by default.
+``mongosh`` provides the ``NumberInt()`` constructor to explicitly
+specify 32-bit integers.
+
+.. _shell-type-decimal:
+
+NumberDecimal
+~~~~~~~~~~~~~
+
+.. versionadded:: 3.4
+
+``mongosh`` treats all numbers as 64-bit floating-point ``double``
+values by default. ``mongosh`` provides the ``NumberDecimal()``
+constructor to explicitly specify 128-bit decimal-based floating-point
+values capable of emulating decimal rounding with exact precision. This
+functionality is intended for applications that handle :manual:`monetary
+data </tutorial/model-monetary-data>`, such as financial, tax, and
+scientific computations. 
+
+The ``decimal`` :manual:`BSON type </reference/bson-types>`
+uses the IEEE 754 decimal128 floating-point numbering format which
+supports 34 decimal digits (i.e. significant digits) and an exponent
+range of −6143 to +6144.
+
+The ``NumberDecimal()`` constructor accepts the ``decimal`` value as a
+string:
+
+.. code-block:: javascript
+
+   NumberDecimal("1000.55")
+   
+The value is stored in the database as follows:
+
+.. code-block:: javascript
+
+   NumberDecimal("1000.55")
+
+.. note::
+
+   In the legacy :binary:`~bin.mongo` shell, ``NumberLong`` can accept
+   either a string or double value. In ``mongosh``, ``NumberLong`` can
+   only accept a string value.
+
+.. note:: To use the ``decimal`` data type with a
+   :ecosystem:`MongoDB driver </drivers/>`, be sure to use a driver
+   version that supports it.
+
+Equality and Sort Order
+```````````````````````
+
+Values of the ``decimal`` type are compared and sorted with other
+numeric types based on their actual numeric value.  Numeric values
+of the binary-based ``double`` type generally have approximate
+representations of decimal-based values and may not be exactly
+equal to their ``decimal`` representations, so use the
+``NumberDecimal()`` constructor when checking the equality of
+``decimal`` values. Consider the following examples with the following
+documents in the ``numbers`` collection:
+
+.. code-block:: javascript
+
+   { "_id" : 1, "val" : NumberDecimal( "9.99" ), "description" : "Decimal" }
+   { "_id" : 2, "val" : 9.99, "description" : "Double" }
+   { "_id" : 3, "val" : 10, "description" : "Double" }
+   { "_id" : 4, "val" : NumberLong("10"), "description" : "Long" }
+   { "_id" : 5, "val" : NumberDecimal( "10.0" ), "description" : "Decimal" }
+
+When the queries from the table below are plugged into the
+``db.numbers.find(<query>)`` method, the following results are
+returned:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 30 70
+
+   * - Query
+     - Results
+
+   * - **{ "val": 9.99 }**
+     - **{ "_id": 2, "val": 9.99, "description": "Double" }**
+     
+   * - **{ "val": NumberDecimal( "9.99" ) }**
+     - **{ "_id": 1, "val": NumberDecimal( "9.99" ), "description": "Decimal" }**
+
+   * - **{ val: 10 }**
+     - | **{ "_id": 3, "val": 10, "description": "Double" }**
+       | **{ "_id": 4, "val": NumberLong(10), "description": "Long" }**
+       | **{ "_id": 5, "val": NumberDecimal( "10.0" ), "description": "Decimal" }**
+
+   * - **{ val: NumberDecimal( "10" ) }**
+     - | **{ "_id": 3, "val": 10, "description": "Double" }**
+       | **{ "_id": 4, "val": NumberLong(10), "description": "Long" }**
+       | **{ "_id": 5, "val": NumberDecimal( "10.0" ), "description": "Decimal" }**
+
+
+The first query, ``{ "val": 9.99 }``, implicitly searches for the
+``double`` representation of ``9.99`` which is not equal to the
+``decimal`` representation of the value.
+
+The ``NumberDecimal()`` constructor is used to query for the document
+with the ``decimal`` representation of ``9.99``. Values of the
+``double`` type are excluded because they do not match the exact value
+of the ``decimal`` representation of ``9.99``.
+
+Matching values of all numeric types are returned when querying for
+whole numbers. For example, querying for a ``double`` representation of
+``10`` will include a ``decimal`` representation of ``10.0`` in the
+results and vice versa.
+
+Checking for ``decimal`` Type
+`````````````````````````````
+
+To test for ``decimal`` type, use the :query:`$type` operator with the
+string alias ``"decimal"`` or ``19``, the numeric code for the
+``decimal`` type.
+ 
+.. code-block:: javascript
+
+   db.inventory.find( { price: { $type: "decimal" } } )
+
+.. _check-types-in-shell:
+      
+Check Types in the ``mongo`` Shell
+----------------------------------
+
+To determine the type of fields, ``mongosh`` provides the ``instanceof``
+and ``typeof`` operators.
+
+
+``instanceof``
+~~~~~~~~~~~~~~
+
+``instanceof`` returns a boolean to test if a value is an instance of
+some type.
+
+For example, the following operation tests whether the ``_id`` field is
+an instance of type ``ObjectId``:
+
+.. code-block:: javascript
+
+   mydoc._id instanceof ObjectId
+
+The operation returns ``true``.
+
+``typeof``
+~~~~~~~~~~
+
+``typeof`` returns the type of a field.
+
+For example, the following operation returns the type of the ``_id``
+field:
+
+.. code-block:: javascript
+
+   typeof mydoc._id
+
+In this case ``typeof`` will return the more generic ``object`` type
+rather than ``ObjectId`` type.

source/reference/methods.txt

@@ -1,8 +1,8 @@
 .. _mdb-shell-methods:
 
-=====================
-MongoDB Shell Methods
-=====================
+===================
+``mongosh`` Methods
+===================
 
 .. default-domain:: mongodb