diff --git a/source/images/compass-insert-button.png b/source/images/compass-insert-button.png new file mode 100644 index 00000000000..bd42ff3780f Binary files /dev/null and b/source/images/compass-insert-button.png differ diff --git a/source/images/compass-insert-document-inventory.png b/source/images/compass-insert-document-inventory.png new file mode 100644 index 00000000000..a8fd9cc70e3 Binary files /dev/null and b/source/images/compass-insert-document-inventory.png differ diff --git a/source/images/compass-query-collection.png b/source/images/compass-query-collection.png new file mode 100644 index 00000000000..2fd51ddf9e4 Binary files /dev/null and b/source/images/compass-query-collection.png differ diff --git a/source/includes/driver-example-insert-1.rst b/source/includes/driver-example-insert-1.rst index 033c5c204b0..fb956db9e9a 100644 --- a/source/includes/driver-example-insert-1.rst +++ b/source/includes/driver-example-insert-1.rst @@ -9,13 +9,17 @@ db.inventory.insertOne( { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } ) - + .. only:: website You can run the operation in the web shell below: .. include:: /includes/fact-mws.rst + - id: compass + content: | + .. figure:: /images/compass-insert-document-inventory.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-insert-2.rst b/source/includes/driver-example-insert-2.rst index 117571a0559..afa4b42a785 100644 --- a/source/includes/driver-example-insert-2.rst +++ b/source/includes/driver-example-insert-2.rst @@ -8,6 +8,21 @@ db.inventory.find( { item: "canvas" } ) + - id: compass + content: | + .. figure:: /images/compass-query-collection.png + + Specify a filter in the MongoDB Compass query bar and click + :guilabel:`Find` to execute the query. + + The above filter specifies that MongoDB Compass only return + documents where the ``item`` field is equal to ``canvas``. + + For more information on the MongoDB Compass Query Bar, see the + Compass + `Query Bar `_ + documentation. + - id: python content: | .. class:: copyable-code diff --git a/source/tutorial/insert-documents.txt b/source/tutorial/insert-documents.txt index 4de43bde9bb..3f69c56bbd5 100644 --- a/source/tutorial/insert-documents.txt +++ b/source/tutorial/insert-documents.txt @@ -42,6 +42,40 @@ Insert a Single Document ObjectId value to the new document. See :ref:`write-op-insert-behavior`. + - id: compass + content: | + To insert a single document using :ref:`MongoDB Compass `: + + 1. Navigate to the collection you wish to insert the document + into: + + a. In the left-hand MongoDB Compass navigation pane, click + the database to which your target collection belongs. + + b. From the database view, click the target collection name. + + 2. Click the :guilabel:`Insert Document` button: + + .. figure:: /images/compass-insert-button.png + + 3. For each field in the document, select the field type and + fill in the field name and value. Add fields by clicking + the last line number, then clicking + :guilabel:`Add Field After ...` + + - For ``Object`` types, add nested fields by clicking the + last field's number and selecting + :guilabel:`Add Field After ...` + + - For ``Array`` types, add additional elements to the array + by clicking the last element's line number and selecting + :guilabel:`Add Array Element After ...` + + 4. Once all fields have been filled out, click :guilabel:`Insert`. + + The following example inserts a new document into the + ``test.inventory`` collection: + - id: python content: | :py:meth:`pymongo.collection.Collection.insert_one` inserts a @@ -75,7 +109,7 @@ Insert a Single Document .. code-block:: json - { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } + { item: "canvas", qty: 100, tags: ["cotton"], size: { h: 28, w: 35.5, uom: "cm" } } The following example inserts the document above into the ``inventory`` collection. If the document does not specify @@ -124,13 +158,13 @@ Insert a Single Document :ruby-api:`Mongo::Collection#insert_one()` inserts a *single* :ref:`document` into a collection. - + The following example inserts a new document into the ``inventory`` collection. If the document does not specify an ``_id`` field, the Ruby driver adds the ``_id`` field with an ObjectId value to the new document. See :ref:`write-op-insert-behavior`. - + - id: scala content: | :scala-api:`collection.insertOne()` @@ -167,6 +201,20 @@ Insert a Single Document an example of a return document, see :ref:`db.collection.insertOne() reference`. + - id: compass + content: | + .. note:: + + MongoDB Compass generates the ``_id`` field and its value + automatically. The generated + :term:`ObjectId` consists of a + unique randomly generated hexadecimal value. + + You can change this value prior to inserting your document + so long as it remains unique and is a valid ``ObjectId``. + For more information on the ``_id`` field, see + :ref:`_id Field `. + - id: python content: | :py:meth:`~pymongo.collection.Collection.insert_one` returns an @@ -179,7 +227,7 @@ Insert a Single Document - id: java-async content: | - `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ + `com.mongodb.reactivestreams.client.MongoCollection.insertOne `_ returns a `Publisher `_ object. The ``Publisher`` inserts the document into a collection when subscribers request data. @@ -210,7 +258,7 @@ Insert a Single Document - id: ruby content: | - Upon successful insert, the + Upon successful insert, the :ruby-api:`insert_one()` method returns an instance of :ruby-api:`Mongo::Operation::Result`, whose @@ -219,7 +267,7 @@ Insert a Single Document - id: scala content: | - Upon successful insert, the + Upon successful insert, the :scala-api:`collection.insertOne()` method returns an instance of :scala-api:`collection.insertOne().results();` whose @@ -239,13 +287,13 @@ To retrieve the document that you just inserted, :ref:`query the collection Insert Multiple Documents ------------------------- -.. versionadded:: 3.2 - .. tabs-drivers:: tabs: - id: shell content: | + .. versionadded:: 3.2 + :method:`db.collection.insertMany()` can insert *multiple* :ref:`documents ` into a collection. Pass an array of documents to the method. @@ -255,8 +303,15 @@ Insert Multiple Documents ``_id`` field, MongoDB adds the ``_id`` field with an ObjectId value to each document. See :ref:`write-op-insert-behavior`. + - id: compass + content: | + Currently, MongoDB Compass does not support inserting multiple + documents in a single operation. + - id: python content: | + .. versionadded:: 3.2 + :py:meth:`pymongo.collection.Collection.insert_many` can insert *multiple* :ref:`documents ` into a collection. Pass an iterable of documents to the method. @@ -268,6 +323,8 @@ Insert Multiple Documents - id: java-sync content: | + .. versionadded:: 3.2 + com.mongodb.client.MongoCollection.insertMany_ can insert *multiple* :ref:`documents ` into a collection. Pass a list of documents to the method. @@ -279,11 +336,12 @@ Insert Multiple Documents - id: java-async content: | + .. versionadded:: 3.2 `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany `_ inserts the following documents with the `Java Reactive Streams - Driver `_: + Driver `_: .. code-block:: json @@ -298,6 +356,8 @@ Insert Multiple Documents - id: nodejs content: | + .. versionadded:: 3.2 + :node-api:`Collection.insertMany() ` can insert *multiple* :ref:`documents ` into a collection. Pass an array of documents to the method. @@ -310,6 +370,8 @@ Insert Multiple Documents - id: php content: | + .. versionadded:: 3.2 + :phpmethod:`MongoDB\\Collection::insertMany() ` can insert *multiple* :ref:`documents ` into a collection. Pass an array of documents to the method. @@ -321,6 +383,8 @@ Insert Multiple Documents - id: perl content: | + .. versionadded:: 3.2 + :perl-api:`MongoDB::Collection::insert_many()` can insert *multiple* :ref:`documents ` into a collection. Pass an array reference of documents to the method. @@ -332,6 +396,8 @@ Insert Multiple Documents - id: ruby content: | + .. versionadded:: 3.2 + :ruby-api:`Mongo::Collection#insert_many()` can insert *multiple* :ref:`documents ` into a collection. Pass an array of documents to the method. @@ -343,10 +409,12 @@ Insert Multiple Documents - id: scala content: | + .. versionadded:: 3.2 + :scala-api:`collection.insertMany()` can insert *multiple* :ref:`documents ` into a collection. - + The following example inserts three new documents into the ``inventory`` collection. If the documents do not specify an ``_id`` field, the Scala driver adds the ``_id`` field with @@ -354,6 +422,8 @@ Insert Multiple Documents - id: csharp content: | + .. versionadded:: 3.2 + :csharp-api:`IMongoCollection.InsertMany()` can insert *multiple* :ref:`documents ` into a collection. Pass an enumerable collection of documents @@ -375,6 +445,9 @@ Insert Multiple Documents the newly inserted documents ``_id`` field values. See the :ref:`reference ` for an example. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: python content: | :py:meth:`~pymongo.collection.Collection.insert_many` returns @@ -382,17 +455,26 @@ Insert Multiple Documents whose ``inserted_ids`` field is a list containing the ``_id`` of each newly inserted document. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: java-sync content: | + To retrieve the inserted documents, :ref:`query the collection + `: + - id: java-async content: | `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany `_ returns a `Publisher `_ - object. The ``Publisher`` inserts the document into a collection + object. The ``Publisher`` inserts the document into a collection when subscribers request data. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: nodejs content: | :node-api:`insertMany() ` returns a @@ -400,6 +482,9 @@ Insert Multiple Documents field contains an array with the ``_id`` of each newly inserted document. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: php content: | Upon successful insert, the @@ -411,6 +496,9 @@ Insert Multiple Documents :phpmethod:`getInsertedIds() ` method returns the ``_id`` of each newly inserted document. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: perl content: | Upon successful insert, the @@ -420,6 +508,9 @@ Insert Multiple Documents whose ``inserted_ids`` attribute is a list containing the ``_id`` of each newly inserted document. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: ruby content: | Upon successful insert, the @@ -429,20 +520,26 @@ Insert Multiple Documents whose ``inserted_ids`` attribute is a list containing the ``_id`` of each newly inserted document. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: scala content: | Upon successful insert, the - :scala-api:`insertMany()` + :scala-api:`insertMany()` method returns an `Observable `_ with a type parameter indicating when the operation has completed or with either a - ``com.mongodb.DuplicateKeyException`` or + ``com.mongodb.DuplicateKeyException`` or ``com.mongodb.MongoException``. + To retrieve the inserted documents, :ref:`query the collection + `: + - id: csharp content: | -To retrieve the inserted documents, :ref:`query the collection -`: + To retrieve the inserted documents, :ref:`query the collection + `: .. include:: /includes/driver-example-query-7.rst @@ -457,6 +554,8 @@ Collection Creation If the collection does not currently exist, insert operations will create the collection. +.. _insert-id-field: + ``_id`` Field ~~~~~~~~~~~~~