DOCSP-17524-warning-for-dot-dollar-import-export

Author: mungitoperrito

source/core/dot-dollar-considerations.txt

@@ -1,6 +1,6 @@
-====================================
-Field Names with (``.``) and (``$``) 
-====================================
+=========================================================
+Field Names with Periods (``.``) and Dollar Signs (``$``) 
+=========================================================
 
 .. default-domain:: mongodb
 
@@ -15,9 +15,9 @@ Field Names with (``.``) and (``$``)
 Overview 
 --------
 
-MongoDB 5.0 adds improved support for field names that are (``$``)
-prefixed or that contain (``.``) characters. The validation rules for
-storing data have been updated to make it easier to work with data
+MongoDB 5.0 adds improved support for field names that are dollar
+(``$``) prefixed or that contain periods (``.``). The validation rules
+for storing data have been updated to make it easier to work with data
 sources that use these characters. 
 
 In most cases data that has been stored using field names like these
@@ -27,13 +27,13 @@ is not directly accessible. You need to use helper methods like
 
 The field name validation rules are not the same for all types of
 storage operations. This page summarizes how different insert and
-update operations handle (``$``) prefixed field names. 
+update operations handle dollar (``$``) prefixed field names.
 
 Insert operations
 -----------------
 
-(``$``) prefixed fields are permitted as top level and nested field
-names for inserts.
+Dollar (``$``) prefixed fields are permitted as top level and nested
+field names for inserts.
 
 .. code-block:: javascript
    :emphasize-lines: 3
@@ -43,7 +43,7 @@ names for inserts.
       "quantity": 30
    } )
 
-(``$``) prefixed fields are permitted on inserts using otherwise
+Dollar (``$``) prefixed fields are permitted on inserts using otherwise
 reserved words. Operator names like :update:`$inc` can be used as
 field names as well as words like ``id``, ``db``, and ``ref``.
 
@@ -60,16 +60,16 @@ field names as well as words like ``id``, ``db``, and ``ref``.
 
 An update which creates a new document during an :term:`upsert` is
 treated as an ``insert`` rather than an ``update`` for field name
-validation. :term:`Upserts <upsert>` can accept (``$``) prefixed
+validation. :term:`Upserts <upsert>` can accept dollar (``$``) prefixed
 fields. However, :term:`upserts <upsert>` are a special case and
 similar update operations may cause an error if the ``match`` portion
 of the update selects an existing document.
 
 This code sample has ``upsert: true`` so it will insert a new document
 if the collection doesn't already contain a document that matches the
 query term, ``{ "date": "2021-07-07" }``. If this sample code matches
-an existing document, the update will fail since ``$hotel`` is (``$``)
-prefixed.
+an existing document, the update will fail since ``$hotel`` is dollar
+(``$``) prefixed.
 
 .. code-block:: javascript
    :emphasize-lines: 5
@@ -88,8 +88,8 @@ Document Replacing Updates
 
 Update operators either replace existing fields with new documents
 or else modify those fields. In cases where the update performs a
-replacement, (``$``) prefixed fields are not permitted as top level
-field names. 
+replacement, dollar (``$``) prefixed fields are not permitted as top
+level field names. 
 
 Consider a document like
 
@@ -119,14 +119,14 @@ modify the ``address.$street`` field but you could not update the
    )
 
 Use :expression:`$setField` as part of an aggregation pipeline to
-:ref:`update top level <dotDollar-aggregate-update>` (``$``) prefixed
-fields like ``$rooms``.
+:ref:`update top level <dotDollar-aggregate-update>` dollar (``$``)
+prefixed fields like ``$rooms``.
 
 Document Modifying Updates
 --------------------------
 
 When an update modifies, rather than replaces, existing document
-fields, (``$``) prefixed fields can be top level field names.
+fields, dollar (``$``) prefixed fields can be top level field names.
 Subfields can be accessed directly, but you need a helper method to
 access the top level fields. 
 
@@ -178,7 +178,7 @@ Updates Using Aggregation Pipelines
 
 Use :expression:`$setField`, :expression:`$getField`, and
 :expression:`$literal` in the :pipeline:`$replaceWith` stage to modify
-(``$``) prefixed fields in an aggregation :term:`pipeline`.
+dollar (``$``) prefixed fields in an aggregation :term:`pipeline`.
 
 Consider a collection of school records like:
 
@@ -193,7 +193,7 @@ Consider a collection of school records like:
    }
 
 Create a new collection for the spring semester using a 
-:term:`pipeline` to update the (``$``) prefixed ``$term`` field.
+:term:`pipeline` to update the dollar (``$``) prefixed ``$term`` field.
 
 .. code-block:: javascript
    :emphasize-lines: 3-5
@@ -213,8 +213,8 @@ General Restrictions
 --------------------
 
 In addition to the storage validation rules above, there are some
-general restrictions on using (``$``) prefixed field names. These
-fields cannot: 
+general restrictions on using dollar (``$``) prefixed field names.
+These fields cannot: 
 
 - Be indexed
 - Be used as part of a shard key
@@ -226,3 +226,5 @@ fields cannot:
 
 .. include:: /includes/warning-possible-data-loss.rst
 
+.. include:: /includes/warning-dot-dollar-import-export.rst
+

source/includes/extracts-projection.yaml

@@ -81,10 +81,6 @@ content: |
 
       db.inventory.find( {}, { "$instock.warehouse": 0, "$item": 0, "detail.$price": 1 } ) // Invalid starting in 4.4
 
-   MongoDB already has a :limit:`restriction <Restrictions on Field Names>`
-   where top-level field names cannot start with the dollar sign
-   (``$``). 
-
    In earlier version, MongoDB ignores the ``$``-prefixed field
    projections.
 ---
@@ -103,10 +99,6 @@ content: |
 
       db.inventory.find( { "instock.qty": { $gt: 25 } }, { "instock.$": { $slice: 1 } } ) // Invalid starting in 4.4
 
-   MongoDB already has a :limit:`restriction <Restrictions on Field
-   Names>` where top-level field names cannot start with the dollar sign
-   (``$``). 
-
    In previous versions, MongoDB returns the first element
    (``instock.$``) in the ``instock`` array that matches the query
    condition; i.e. the positional projection ``"instock.$"`` takes

source/includes/warning-document-duplicate-key-names-body.rst

@@ -0,0 +1,8 @@
+The MongoDB Query Language is undefined over documents with duplicate
+field names. BSON builders may support creating a BSON document with
+duplicate field names. While the BSON builder may not throw an error,
+inserting these documents into MongoDB is not supported *even if* the
+insert succeeds. For example, inserting a BSON document with duplicate
+field names through a MongoDB driver may result in the driver silently
+dropping the duplicate values prior to insertion.
+

source/includes/warning-document-duplicate-key-names.rst

@@ -0,0 +1,20 @@
+Starting in MongoDB 5.0, document field names can be dollar (``$``)
+prefixed and can contain periods (``.``). However,
+:binary:`~bin.mongoimport` and :binary:`~bin.mongoexport` may not work
+as expected in some situations with field names that make use of these
+characters.
+
+:ref:`MongoDB Extended JSON v2 <extended-json-high-level-ref-v2>`
+cannot differentiate between type wrappers and fields that happen to
+have the same name as type wrappers. Do not use Extended JSON
+formats in contexts where the corresponding BSON representations
+might include dollar (``$``) prefixed keys. The
+:ref:`DBRef <dbref-explanation>` mechanism is an exception to this
+general rule. 
+
+There are also restrictions on using :binary:`~bin.mongoimport` and
+:binary:`~bin.mongoexport` with periods (``.``) in field names. Since
+CSV files use the period (``.``) to represent data hierarchies, a
+period (``.``) in a field name will be misinterpreted as a level of
+nesting.
+

source/includes/warning-dot-dollar-import-export-body.rst

@@ -0,0 +1,4 @@
+.. warning:: Import and Export Concerns With Dollar Signs (``$``) and Periods (``.``)
+
+   .. include:: /includes/warning-dot-dollar-import-export-body.rst
+

source/includes/warning-dot-dollar-import-export.rst

@@ -0,0 +1,18 @@
+There is a small chance of data loss when using dollar (``$``) prefixed
+field names or field names that contain periods (``.``) if these
+field names are used in conjunction with unacknowledged writes
+(:doc:`write concern </reference/write-concern>` ``w=0``) on servers
+that are older than MongoDB 5.0.
+
+When running :doc:`insert </tutorial/insert-documents>`,
+:doc:`update </tutorial/insert-documents>`, and
+:doc:`findAndModify </reference/method/db.collection.findAndModify>`
+commands, drivers that are 5.0 compatible remove restrictions on
+using documents with field names that are dollar (``$``) prefixed or
+that contain periods (``.``). These field names generated a client-side
+error in earlier driver versions.
+
+The restrictions are removed regardless of the server version the
+driver is connected to. If a 5.0 driver sends a document to an older
+server, the document will be rejected without sending an error.
+

source/includes/warning-possible-data-loss-body.rst

@@ -1,20 +1,4 @@
-.. warning::
+.. warning:: Possible Data Loss With Dollar Signs (``$``) and Periods (``.``)
 
-   There is a small chance of data loss when using (``$``) prefixed
-   field names or field names with (``.``) characters when this type of
-   field name is used in conjunction with unacknowledged writes
-   (:doc:`write concern </reference/write-concern>` ``w=0``) on servers
-   that are older than MongoDB 5.0.
-
-   When running :doc:`insert </tutorial/insert-documents>`,
-   :doc:`update </tutorial/insert-documents>`, and
-   :doc:`findAndModify </reference/method/db.collection.findAndModify>`
-   commands, drivers that are 5.0 compatible remove restrictions on
-   using documents with field names that are (``$``) prefixed or that
-   contain (``.``) characters. These field names generated a
-   client-side error in earlier driver versions.
-
-   The restrictions are removed regardless of the server version the
-   driver is connected to. If a 5.0 driver sends a document to an older
-   server, the document will be rejected without sending an error.
+   .. include:: /includes/warning-possible-data-loss-body.rst
 

source/includes/warning-possible-data-loss.rst

@@ -93,13 +93,31 @@ Naming Restrictions
 
    .. include:: /includes/fact-document-field-name-restrictions.rst
 
-   .. include:: /includes/warning-possible-data-loss.rst
+.. limit:: Restrictions on _id
 
-   .. include:: /includes/warning-document-duplicate-key-names.rst
+   .. include:: /includes/fact-id-field-name-rules.rst
 
-.. limit:: Restrictions on ``_id``
+Naming Warnings
+---------------
 
-   .. include:: /includes/fact-id-field-name-rules.rst
+.. warning::
+
+   Use caution, the issues discussed in this section could lead to data
+   loss or corruption.  
+
+MongoDB does not support duplicate field names
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. include:: /includes/warning-document-duplicate-key-names-body.rst
+
+Import and Export Concerns With Dollar Signs (``$``) and Periods (``.``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/warning-dot-dollar-import-export-body.rst
+
+Possible Data Loss With Dollar Signs (``$``) and Periods (``.``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. include:: /includes/warning-possible-data-loss-body.rst
 
 .. _faq-dev-namespace:
 

source/reference/limits.txt

@@ -10,6 +10,8 @@ MongoDB Extended JSON (v2)
    :depth: 1
    :class: singlecol
 
+.. _extended-json-high-level-ref-v2:
+
 .. important:: Disambiguation
 
    The following page discusses MongoDB Extended JSON v2. For