diff --git a/source/includes/fact-id-field.rst b/source/includes/fact-id-field.rst index f9d7de64a92..c74e301ad54 100644 --- a/source/includes/fact-id-field.rst +++ b/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 -` 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 `) -:program:`mongod` will add the ``_id`` field that holds an ObjectId. +This also applies to documents inserted through update +operations with :ref:`upsert: true `. diff --git a/source/includes/fact-mws.rst b/source/includes/fact-mws.rst new file mode 100644 index 00000000000..4ee7ade5dd7 --- /dev/null +++ b/source/includes/fact-mws.rst @@ -0,0 +1,3 @@ +.. raw:: html + + diff --git a/source/reference/method/db.collection.insertMany.txt b/source/reference/method/db.collection.insertMany.txt index d1c902dea0c..37dbcac402f 100644 --- a/source/reference/method/db.collection.insertMany.txt +++ b/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,10 +35,10 @@ 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 @@ -46,7 +46,7 @@ Definition 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 @@ -54,9 +54,9 @@ 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,8 +288,8 @@ 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: @@ -295,13 +297,13 @@ failed to insert due to duplicate ``_id`` values, 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: diff --git a/source/reference/method/db.collection.insertOne.txt b/source/reference/method/db.collection.insertOne.txt index d25d504f102..895ecfb2306 100644 --- a/source/reference/method/db.collection.insertOne.txt +++ b/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 diff --git a/source/tutorial/insert-documents.txt b/source/tutorial/insert-documents.txt index c2f143c8a1c..af2bd2ec04f 100644 --- a/source/tutorial/insert-documents.txt +++ b/source/tutorial/insert-documents.txt @@ -71,27 +71,27 @@ document. See :ref:`write-op-insert-behavior`. db.users.insertOne( { name: "sue", - age: 19, + age: 19, status: "P" } ) -The method returns a document with the status of the operation: +.. only:: website -.. code-block:: javascript + You can run this method in the web shell below: + + .. include:: /includes/fact-mws.rst - { - "acknowledged" : true, - "insertedId" : ObjectId("5742045ecacf0ba0c3fa82b0") - } +:method:`~db.collection.insertOne()` will return a document providing the +inserted document's ``_id`` field. See the +:ref:`reference ` for an example. -To verify the inserted document, :ref:`query the collection -` by specifying a query filter on the -``_id`` field: +To retrieve the document that you just inserted, :ref:`query the collection +`: .. code-block:: javascript - db.users.find( { _id: ObjectId("5742045ecacf0ba0c3fa82b0") } ) + db.users.find( { "name": "sue" } ) For more information and examples, see :method:`db.collection.insertOne()`. @@ -114,7 +114,7 @@ See :ref:`write-op-insert-behavior`. .. code-block:: javascript - db.users.insertMany( + db.users.insertMany( [ { name: "bob", age: 42, status: "A", }, { name: "ahn", age: 22, status: "A", }, @@ -122,36 +122,22 @@ See :ref:`write-op-insert-behavior`. ] ) -The method returns a document with the status of the operation: +.. only:: website -.. code-block:: javascript + You can run this method in the web shell below: - { - "acknowledged" : true, - "insertedIds" : [ - ObjectId("57420d48cacf0ba0c3fa82b1"), - ObjectId("57420d48cacf0ba0c3fa82b2"), - ObjectId("57420d48cacf0ba0c3fa82b3") - ] - } + .. include:: /includes/fact-mws.rst + +:method:`~db.collection.insertMany()` will return a document providing +each inserted document's ``_id`` field. See the +:ref:`reference ` for an example. -To verify the inserted document, :ref:`query the collection -` by specifying a query filter on the -``_id`` field: +To retrieve the inserted documents, :ref:`query the collection +`: .. code-block:: javascript - db.users.find( - { _id: - { $in: - [ - ObjectId("57420d48cacf0ba0c3fa82b1"), - ObjectId("57420d48cacf0ba0c3fa82b2"), - ObjectId("57420d48cacf0ba0c3fa82b3") - ] - } - } - ) + db.users.find() For more information and examples, see :method:`db.collection.insertMany()`. @@ -177,16 +163,24 @@ See :ref:`write-op-insert-behavior`. db.users.insert( { name: "sue", - age: 19, + age: 19, status: "P" } ) -The operation returns a :method:`WriteResult` object with the status of -the operation. A successful insert of the document returns the -following :method:`WriteResult` object: +.. only:: website + + You can run this method in the web shell below: + + .. include:: /includes/fact-mws.rst -.. code-block:: javascript +:method:`db.collection.insert` returns a :method:`WriteResult` object +providing status information. + +For example, a successful insert returns the following +:method:`WriteResult` object: + +.. code-block:: javascript WriteResult({ "nInserted" : 1 })