WRITING-1600: MWS integration

Author: i80and

source/includes/fact-id-field.rst

@@ -1,11 +1,7 @@
-In MongoDB, documents stored in a collection require a unique
-:term:`_id` field that acts as a :term:`primary key`. If the ``_id``
-field is unspecified in the documents, MongoDB uses :ref:`ObjectIds
-<objectid>` as the default value for the ``_id`` field; i.e. if a
-document does not contain a top-level ``_id`` field during an insert,
-the MongoDB driver adds the ``_id`` field that holds an :ref:`objectid`.
+In MongoDB, each document stored in a collection requires a unique
+:term:`_id` field that acts as a :term:`primary key`. If an inserted
+document omits the ``_id`` field, the MongoDB driver automatically
+generates an :ref:`objectid` for the ``_id`` field.
 
-In addition, if the :program:`mongod` receives a document to insert
-that does not contain an ``_id`` field (e.g. through an update
-operation with an :ref:`upsert option <upsert-parameter>`)
-:program:`mongod` will add the ``_id`` field that holds an ObjectId.
+This also applies to documents inserted through update
+operations with :ref:`upsert: true <upsert-parameter>`.

source/includes/fact-mws.rst

@@ -0,0 +1,3 @@
+.. raw:: html
+
+   <iframe class="mws-root" allowfullscreen sandbox="allow-scripts allow-same-origin" width=600 height=280 src="https://mws.mongodb.com/"></iframe>

source/reference/method/db.collection.insertMany.txt

@@ -16,7 +16,7 @@ Definition
 .. method:: db.collection.insertMany()
 
    .. versionadded:: 3.2
-	
+
    Inserts multiple documents into a collection.
 
    The :method:`~db.collection.insertMany()` method has the following
@@ -35,28 +35,28 @@ Definition
    .. include:: /includes/apiargs/method-db.collection.insertMany-param.rst
 
    :returns:
-      
+
       A document containing:
 
-      - A boolean ``acknowledged`` as ``true`` if the operation ran with 
+      - A boolean ``acknowledged`` as ``true`` if the operation ran with
         :term:`write concern` or ``false`` if write concern was disabled
 
       - An array of ``_id`` for each successfully inserted documents
 
 Behaviors
 ---------
 
-Given an array of documents, :method:`~db.collection.insertMany()` 
+Given an array of documents, :method:`~db.collection.insertMany()`
 inserts each document in the array into the collection.
 
 Execution of Operations
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 By default documents are inserted in order.
 
-If ``ordered`` is set to false, documents are inserted in an unordered 
-format and may be reordered by :program:`mongod` to increase performance. 
-Applications should not depend on ordering of inserts if using an unordered 
+If ``ordered`` is set to false, documents are inserted in an unordered
+format and may be reordered by :program:`mongod` to increase performance.
+Applications should not depend on ordering of inserts if using an unordered
 :method:`~db.collection.insertMany()`.
 
 .. include:: /includes/fact-bulkwrite-operation-batches.rst
@@ -67,13 +67,13 @@ Applications should not depend on ordering of inserts if using an unordered
 Collection Creation
 ~~~~~~~~~~~~~~~~~~~
 
-If the collection does not exist, then :method:`~db.collection.insertMany()` 
+If the collection does not exist, then :method:`~db.collection.insertMany()`
 creates the collection on successful write.
 
 ``_id`` Field
 ~~~~~~~~~~~~~
 
-If the document does not specify an :term:`_id` field, then :program:`mongod` 
+If the document does not specify an :term:`_id` field, then :program:`mongod`
 adds the ``_id`` field and assign a unique
 :method:`ObjectId` for the document. Most
 drivers create an ObjectId and insert the ``_id`` field, but the
@@ -100,16 +100,18 @@ Error Handling
 
 Inserts throw a ``BulkWriteError`` exception.
 
-Excluding :doc:`/reference/write-concern` errors, ordered operations stop 
-after an error, while unordered operations continue to process any 
+Excluding :doc:`/reference/write-concern` errors, ordered operations stop
+after an error, while unordered operations continue to process any
 remaining write operations in the queue.
 
-Write concern errors are displayed in the ``writeConcernErrors`` field, while 
-all other errors are displayed in the ``writeErrors`` field. If an error is 
-encountered, the number of successful write operations are displayed instead 
-of a list of inserted _ids. Ordered operations display the single error 
+Write concern errors are displayed in the ``writeConcernErrors`` field, while
+all other errors are displayed in the ``writeErrors`` field. If an error is
+encountered, the number of successful write operations are displayed instead
+of a list of inserted _ids. Ordered operations display the single error
 encountered while unordered operations display each error in an array.
 
+.. _insertMany-examples:
+
 Examples
 --------
 
@@ -119,13 +121,13 @@ collection.
 Insert Several Document without Specifying an ``_id`` Field
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example uses :method:`db.collection.insertMany()` to insert 
+The following example uses :method:`db.collection.insertMany()` to insert
 documents that do not contain the ``_id`` field:
 
 .. code-block:: javascript
 
    try {
-      db.products.insertMany( [ 
+      db.products.insertMany( [
          { item: "card", qty: 15 },
          { item: "envelope", qty: 20 },
          { item: "stamps" , qty: 30 }
@@ -147,7 +149,7 @@ The operation returns the following document:
       ]
    }
 
-Because the documents did not include ``_id``, 
+Because the documents did not include ``_id``,
 :program:`mongod` creates and adds the ``_id`` field for each document and
 assigns it a unique :method:`ObjectId` value.
 
@@ -156,8 +158,8 @@ assigns it a unique :method:`ObjectId` value.
 Insert Several Document Specifying an ``_id`` Field
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The following example/operation uses :method:`~db.collection.insertMany()` to 
-insert documents that include the ``_id`` field. The value of ``_id`` must be 
+The following example/operation uses :method:`~db.collection.insertMany()` to
+insert documents that include the ``_id`` field. The value of ``_id`` must be
 unique within the collection to avoid a duplicate key error.
 
 .. code-block:: javascript
@@ -178,8 +180,8 @@ The operation returns the following document:
 
    { "acknowledged" : true, "insertedIds" : [ 10, 11, 12 ] }
 
-Inserting a duplicate value for any key that is part of a :term:`unique 
-index`, such as ``_id``, throws an exception. The following attempts to insert 
+Inserting a duplicate value for any key that is part of a :term:`unique
+index`, such as ``_id``, throws an exception. The following attempts to insert
 a document with a ``_id`` value that already exists:
 
 .. code-block:: javascript
@@ -193,11 +195,11 @@ a document with a ``_id`` value that already exists:
    } catch (e) {
       print (e);
    }
-   
+
 Since ``_id: 13`` already exists, the following exception is thrown:
-	
+
 .. code-block:: javascript
-	
+
    BulkWriteError({
       "writeErrors" : [
          {
@@ -220,19 +222,19 @@ Since ``_id: 13`` already exists, the following exception is thrown:
       "upserted" : [ ]
    })
 
-Note that one document was inserted: The first document of ``_id: 13`` will 
-insert successfully, but the second insert will fail. This will also stop 
+Note that one document was inserted: The first document of ``_id: 13`` will
+insert successfully, but the second insert will fail. This will also stop
 additional documents left in the queue from being inserted.
 
-With ``ordered`` to ``false``, the insert operation would continue with any 
+With ``ordered`` to ``false``, the insert operation would continue with any
 remaining documents.
 
 Unordered Inserts
 ~~~~~~~~~~~~~~~~~
 
-The following attempts to insert multiple documents with ``_id`` field and 
-``ordered: false``. The array of documents contains two documents with 
-duplicate ``_id`` fields. 
+The following attempts to insert multiple documents with ``_id`` field and
+``ordered: false``. The array of documents contains two documents with
+duplicate ``_id`` fields.
 
 .. code-block:: javascript
 
@@ -253,7 +255,7 @@ duplicate ``_id`` fields.
 The operation throws the following exception:
 
 .. code-block:: javascript
-	
+
    BulkWriteError({
       "writeErrors" : [
          {
@@ -286,22 +288,22 @@ The operation throws the following exception:
       "upserted" : [ ]
    })
 
-While the document with ``item: "medium box"`` and ``item: "tape"`` 
-failed to insert due to duplicate ``_id`` values, 
+While the document with ``item: "medium box"`` and ``item: "tape"``
+failed to insert due to duplicate ``_id`` values,
 ``nInserted`` shows that the remaining 5 documents were inserted.
 
 .. _insertMany-using-write-concern:
 
 Using Write Concern
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Given a three member replica set, the following operation specifies a 
+Given a three member replica set, the following operation specifies a
 ``w`` of ``majority`` and ``wtimeout`` of ``100``:
 
 .. code-block:: javascript
 
    try {
-      db.products.insertMany( 
+      db.products.insertMany(
          [
             { _id: 10, item: "large box", qty: 20 },
             { _id: 11, item: "small box", qty: 55 },
@@ -313,7 +315,7 @@ Given a three member replica set, the following operation specifies a
       print (e);
    }
 
-If the primary and at least one secondary acknowledge each write operation 
+If the primary and at least one secondary acknowledge each write operation
 within 100 milliseconds, it returns:
 
 .. code-block:: javascript
@@ -327,9 +329,9 @@ within 100 milliseconds, it returns:
      ]
    }
 
-If the total time required for all required nodes in the replica set to 
-acknowledge the write operation is greater than ``wtimeout``, 
-the following ``writeConcernError`` is displayed when the ``wtimeout`` period 
+If the total time required for all required nodes in the replica set to
+acknowledge the write operation is greater than ``wtimeout``,
+the following ``writeConcernError`` is displayed when the ``wtimeout`` period
 has passed.
 
 This operation returns:

source/reference/method/db.collection.insertOne.txt

@@ -37,10 +37,10 @@ Definition
 
       A document containing:
 
-      - A boolean ``acknowledged`` as ``true`` if the operation ran with 
+      - A boolean ``acknowledged`` as ``true`` if the operation ran with
         :term:`write concern` or ``false`` if write concern was disabled.
 
-      - A field ``insertedId`` with the ``_id`` value of the 
+      - A field ``insertedId`` with the ``_id`` value of the
         inserted document.
 
 Behaviors
@@ -55,7 +55,7 @@ If the collection does not exist, then the
 ``_id`` Field
 ~~~~~~~~~~~~~
 
-If the document does not specify an :term:`_id` field, then :program:`mongod` 
+If the document does not specify an :term:`_id` field, then :program:`mongod`
 will add the ``_id`` field and assign a unique
 :method:`ObjectId` for the document before inserting. Most
 drivers create an ObjectId and insert the ``_id`` field, but the
@@ -77,13 +77,14 @@ Explainability
 Error Handling
 ~~~~~~~~~~~~~~
 
-On error, :method:`~db.collection.insertOne()` throws either a ``writeError`` 
+On error, :method:`~db.collection.insertOne()` throws either a ``writeError``
 or ``writeConcernError`` exception.
 
+.. _insertOne-examples:
+
 Examples
 --------
 
-
 Insert a Document without Specifying an ``_id`` Field
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -107,9 +108,9 @@ The operation returns the following document:
       "acknowledged" : true,
       "insertedId" : ObjectId("56fc40f9d735c28df206d078")
    }
-   
 
-Because the documents did not include ``_id``, 
+
+Because the documents did not include ``_id``,
 :program:`mongod` creates and adds the ``_id`` field and
 assigns it a unique :method:`ObjectId` value.
 
@@ -136,9 +137,9 @@ The operation returns the following:
 .. code-block:: javascript
 
    { "acknowledged" : true, "insertedId" : 10 }
-   
-Inserting an duplicate value for any key that is part of a :term:`unique 
-index`, such as ``_id``, throws an exception. The following attempts to insert 
+
+Inserting an duplicate value for any key that is part of a :term:`unique
+index`, such as ``_id``, throws an exception. The following attempts to insert
 a document with a ``_id`` value that already exists:
 
 .. code-block:: javascript
@@ -150,9 +151,9 @@ a document with a ``_id`` value that already exists:
    }
 
 Since ``_id: 10`` already exists, the following exception is thrown:
-   
+
 .. code-block:: javascript
-   
+
    WriteError({
       "index" : 0,
       "code" : 11000,
@@ -169,7 +170,7 @@ Since ``_id: 10`` already exists, the following exception is thrown:
 Increase Write Concern
 ~~~~~~~~~~~~~~~~~~~~~~
 
-Given a three member replica set, the following operation specifies a 
+Given a three member replica set, the following operation specifies a
 ``w`` of ``majority``, ``wtimeout`` of ``100``:
 
 .. code-block:: javascript
@@ -183,7 +184,7 @@ Given a three member replica set, the following operation specifies a
       print (e);
    }
 
-If the acknowledgement takes longer than the ``wtimeout`` limit, the following 
+If the acknowledgement takes longer than the ``wtimeout`` limit, the following
 exception is thrown:
 
 .. code-block:: javascript