DOCSP-1376 - Integrating compass into insert docs page

Author: jeff-allen-mongo

source/images/compass-insert-button.png

@@ -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

source/images/compass-insert-document-inventory.png

@@ -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 <https://docs.mongodb.com/compass/master/query-bar/>`_
+         documentation.
+
      - id: python
        content: |
          .. class:: copyable-code

source/images/compass-query-collection.png

@@ -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 <compass-index>`:
+
+         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()<Collection.html#insert_one-instance_method>`
          inserts a *single* :ref:`document<bson-document-format>` 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()<insertOne(document:TResult,options:org.mongodb.scala.model.InsertOneOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
@@ -167,6 +201,20 @@ Insert a Single Document
          an example of a return document, see
          :ref:`db.collection.insertOne() reference<insertOne-examples>`.
 
+     - 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 <insert-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 <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#insertOne(TDocument)>`_ 
+         `com.mongodb.reactivestreams.client.MongoCollection.insertOne <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#insertOne(TDocument)>`_
          returns a `Publisher <http://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html>`_
          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()<Collection.html#insert_one-instance_method>`
          method returns an instance of
          :ruby-api:`Mongo::Operation::Result<Operation/Result.html>`, whose
@@ -219,7 +267,7 @@ Insert a Single Document
 
      - id: scala
        content: |
-         Upon successful insert, the 
+         Upon successful insert, the
          :scala-api:`collection.insertOne()<MongoCollection.html#insertOne(document:TResult,options:org.mongodb.scala.model.InsertOneOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
          method returns an instance of
          :scala-api:`collection.insertOne().results();<InsertOneResult>` 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 <bson-document-format>` 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 <bson-document-format>` 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 <bson-document-format>`
          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
          <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#insertMany(java.util.List)>`_
          inserts the following documents with the `Java Reactive Streams
-         Driver <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/>`_: 
+         Driver <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/>`_:
 
          .. code-block:: json
 
@@ -298,6 +356,8 @@ Insert Multiple Documents
 
      - id: nodejs
        content: |
+         .. versionadded:: 3.2
+
          :node-api:`Collection.insertMany() <Collection.html#insertMany>`
          can insert *multiple* :ref:`documents <bson-document-format>`
          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() <phpmethod.MongoDB\\Collection::insertMany>`
          can insert *multiple* :ref:`documents <bson-document-format>` 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()<Collection#insert_many>`
          can insert *multiple* :ref:`documents <bson-document-format>` 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()<Collection.html#insert_many-instance_method>`
          can insert *multiple* :ref:`documents <bson-document-format>` into a
          collection. Pass an array of documents to the method.
@@ -343,17 +409,21 @@ Insert Multiple Documents
 
      - id: scala
        content: |
+         .. versionadded:: 3.2
+
          :scala-api:`collection.insertMany()<insertMany(documents:Seq[_<:TResult],options:org.mongodb.scala.model.InsertManyOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
          can insert *multiple* :ref:`documents <bson-document-format>` 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
          an ObjectId value to each document. See :ref:`write-op-insert-behavior`.
 
      - id: csharp
        content: |
+         .. versionadded:: 3.2
+
          :csharp-api:`IMongoCollection.InsertMany()<M_MongoDB_Driver_IMongoCollection_1_InsertMany>`
          can insert *multiple* :ref:`documents <bson-document-format>`
          into a collection. Pass an enumerable collection of documents
@@ -375,31 +445,46 @@ Insert Multiple Documents
          the newly inserted documents ``_id`` field values. See the
          :ref:`reference <insertMany-examples>` for an example.
 
+         To retrieve the inserted documents, :ref:`query the collection
+         <read-operations-query-document>`:
+
      - id: python
        content: |
          :py:meth:`~pymongo.collection.Collection.insert_many` returns
          an instance of :py:class:`pymongo.results.InsertManyResult`
          whose ``inserted_ids`` field is a list containing the ``_id``
          of each newly inserted document.
 
+         To retrieve the inserted documents, :ref:`query the collection
+         <read-operations-query-document>`:
+
      - id: java-sync
        content: |
 
+         To retrieve the inserted documents, :ref:`query the collection
+         <read-operations-query-document>`:
+
      - id: java-async
        content: |
          `com.mongodb.reactivestreams.client.MongoCollection.html.insertMany
          <http://mongodb.github.io/mongo-java-driver-reactivestreams/1.6/javadoc/com/mongodb/reactivestreams/client/MongoCollection.html#insertMany(java.util.List)>`_
          returns a `Publisher <http://www.reactive-streams.org/reactive-streams-1.0.1-javadoc/org/reactivestreams/Publisher.html>`_
-         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
+         <read-operations-query-document>`:
+
      - id: nodejs
        content: |
          :node-api:`insertMany() <Collection.html#insertMany>` returns a
          promise that provides a ``result``. The ``result.insertedIds``
          field contains an array with the ``_id`` of each newly inserted
          document.
 
+         To retrieve the inserted documents, :ref:`query the collection
+         <read-operations-query-document>`:
+
      - id: php
        content: |
          Upon successful insert, the
@@ -411,6 +496,9 @@ Insert Multiple Documents
          :phpmethod:`getInsertedIds() <phpmethod.MongoDB\\InsertManyResult::getInsertedIds>`
          method returns the ``_id`` of each newly inserted document.
 
+         To retrieve the inserted documents, :ref:`query the collection
+         <read-operations-query-document>`:
+
      - 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
+         <read-operations-query-document>`:
+
      - 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
+         <read-operations-query-document>`:
+
      - id: scala
        content: |
          Upon successful insert, the
-         :scala-api:`insertMany()<insertMany(documents:Seq[_<:TResult],options:org.mongodb.scala.model.InsertManyOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>` 
+         :scala-api:`insertMany()<insertMany(documents:Seq[_<:TResult],options:org.mongodb.scala.model.InsertManyOptions):org.mongodb.scala.SingleObservable[org.mongodb.scala.Completed]>`
          method returns an `Observable <http://mongodb.github.io/mongo-scala-driver/2.1/reference/observables/>`_ 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
+         <read-operations-query-document>`:
+
      - id: csharp
        content: |
 
-To retrieve the inserted documents, :ref:`query the collection
-<read-operations-query-document>`:
+         To retrieve the inserted documents, :ref:`query the collection
+         <read-operations-query-document>`:
 
 .. 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
 ~~~~~~~~~~~~~