DOCSP-42002-prefix-limitation (#170)

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

* DOCSP-42002-prefix-limitation

---------

Co-authored-by: jason-price-mongodb <[email protected]>

Author: jason-price-mongodb

source/includes/warning-tools-dollar-dump-restore-restriction.rst

@@ -0,0 +1,14 @@
+.. warning:: Data Dump and Restore Conflicts with $ Prefix in Fields
+
+   Starting in MongoDB 5.0, document field names can be prefixed with a
+   dollar character (``$``). However, :binary:`~bin.mongodump` and
+   :binary:`~bin.mongorestore` won't work with field names that are
+   prefixed with a dollar character in a collection's options.
+
+   :manual:`MongoDB Extended JSON
+   (v2)</reference/mongodb-extended-json>` cannot differentiate between
+   type wrappers and fields that have the same name as type
+   wrappers. Don't use extended JSON formats if the
+   corresponding BSON representation might include ``$`` prefixed keys.
+   The :ref:`DBRefs <dbref-explanation>` mechanism is an exception to
+   this general rule.

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

@@ -1,9 +1,9 @@
 .. warning:: Data Import and Export Conflicts With (``$``) and (``.``)
 
-   Starting in MongoDB 5.0, document field names can be (``$``)
-   prefixed and can contain a (``.``). However,
-   :binary:`~bin.mongoimport` and :binary:`~bin.mongoexport` should not
-   be used with field names that make use of these characters.
+   Starting in MongoDB 5.0, document field names can be prefixed with a
+   dollar character (``$``) and can contain a period character (``.``).
+   However, :binary:`~bin.mongoimport` and :binary:`~bin.mongoexport`
+   won't work with field names that use those characters.
 
    :ref:`MongoDB Extended JSON v2 <extended-json-high-level-ref-v2>`
    cannot differentiate between type wrappers and fields that happen to

source/mongodump/mongodump-behavior.txt

@@ -32,6 +32,8 @@ mongodump Behavior, Access, and Usage
    the :dbtools:`--archive </mongodump/#std-option-mongodump.--archive>` 
    option.  
 
+.. include:: /includes/warning-tools-dollar-dump-restore-restriction.rst
+
 Behavior
 --------
 
@@ -173,7 +175,7 @@ folders or files.
 Data Compression Handling
 ~~~~~~~~~~~~~~~~~~~~~~~~~
 
-When run against a ``mongod`` instance that uses the
+When run on a ``mongod`` instance that uses the
 :manual:`WiredTiger </core/wiredtiger>` storage engine,
 ``mongodump`` outputs uncompressed data.
 
@@ -188,7 +190,7 @@ FIPS
 ~~~~
 
 ``mongodump`` automatically creates FIPS-compliant
-connections to a ``mongod``/``mongos`` that is
+connections to a ``mongod`` or ``mongos`` that are
 :manual:`configured to use FIPS mode </tutorial/configure-fips>`.
 
 Using ``mongodump`` on Atlas Free and Shared Tier Clusters 

source/mongorestore/mongorestore-behavior-access-usage.txt

@@ -19,6 +19,8 @@ mongorestore Behavior, Access, and Usage
 .. |arrow| unicode:: U+27A4
 .. |tool-binary| replace:: ``mongorestore``
 
+.. include:: /includes/warning-tools-dollar-dump-restore-restriction.rst
+
 Behavior
 --------
 
@@ -32,9 +34,9 @@ Insert Only
 
 ``mongorestore`` can create a new database or add data to an
 existing database. However, ``mongorestore`` performs inserts
-only and does not perform updates. That is, if restoring documents to
+only and does not perform updates. If you restore documents to
 an existing database and collection and existing documents have the
-same value ``_id`` field as the to-be-restored documents,
+same value ``_id`` field as the documents to restore,
 ``mongorestore`` will *not* overwrite those documents.
 
 Document Order
@@ -58,7 +60,7 @@ Rebuild Indexes
    limit. 
 
    To avoid this issue, consider using hashed indexes or indexing a
-   computed value instead. If you want to resolve the index issue after
+   computed value instead. To resolve the index issue after
    restoring the data, you can disable the default index key length
    validation on the target database by setting the :binary:`~bin.mongod`
    instance's ``failIndexKeyTooLong`` parameter to false.