diff --git a/source/images/compass-project-all-fields.png b/source/images/compass-project-all-fields.png new file mode 100644 index 00000000000..f0c68082ad8 Binary files /dev/null and b/source/images/compass-project-all-fields.png differ diff --git a/source/images/compass-project-embedded-array-docs.png b/source/images/compass-project-embedded-array-docs.png new file mode 100644 index 00000000000..803ebebbc8a Binary files /dev/null and b/source/images/compass-project-embedded-array-docs.png differ diff --git a/source/images/compass-project-embedded-fields.png b/source/images/compass-project-embedded-fields.png new file mode 100644 index 00000000000..85335d840c5 Binary files /dev/null and b/source/images/compass-project-embedded-fields.png differ diff --git a/source/images/compass-project-exclude-fields.png b/source/images/compass-project-exclude-fields.png new file mode 100644 index 00000000000..eb9e69d3f5f Binary files /dev/null and b/source/images/compass-project-exclude-fields.png differ diff --git a/source/images/compass-project-specified-plus-id.png b/source/images/compass-project-specified-plus-id.png new file mode 100644 index 00000000000..cc50a8c4466 Binary files /dev/null and b/source/images/compass-project-specified-plus-id.png differ diff --git a/source/images/compass-project-suppress-embedded-field.png b/source/images/compass-project-suppress-embedded-field.png new file mode 100644 index 00000000000..7f66456b11a Binary files /dev/null and b/source/images/compass-project-suppress-embedded-field.png differ diff --git a/source/images/compass-project-suppress-id.png b/source/images/compass-project-suppress-id.png new file mode 100644 index 00000000000..fd7a7a5d5d9 Binary files /dev/null and b/source/images/compass-project-suppress-id.png differ diff --git a/source/includes/driver-example-query-42.rst b/source/includes/driver-example-query-42.rst index 38ae4fabb97..91c31f9a6f4 100644 --- a/source/includes/driver-example-query-42.rst +++ b/source/includes/driver-example-query-42.rst @@ -20,6 +20,22 @@ .. include:: /includes/fact-mws.rst + - id: compass + content: | + .. code-block:: javascript + + [ + { item: "journal", status: "A", size: { h: 14, w: 21, uom: "cm" }, instock: [ { warehouse: "A", qty: 5 } ] }, + { item: "notebook", status: "A", size: { h: 8.5, w: 11, uom: "in" }, instock: [ { warehouse: "C", qty: 5 } ] }, + { item: "paper", status: "D", size: { h: 8.5, w: 11, uom: "in" }, instock: [ { warehouse: "A", qty: 60 } ] }, + { item: "planner", status: "D", size: { h: 22.85, w: 30, uom: "cm" }, instock: [ { warehouse: "A", qty: 40 } ] }, + { item: "postcard", status: "A", size: { h: 10, w: 15.25, uom: "cm" }, instock: [ { warehouse: "B", qty: 15 }, { warehouse: "C", qty: 35 } ] } + ] + + For instructions on inserting documents in MongoDB Compass, + see :doc:`Insert Documents `. + + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-43.rst b/source/includes/driver-example-query-43.rst index a270b207245..5c3a658a2f2 100644 --- a/source/includes/driver-example-query-43.rst +++ b/source/includes/driver-example-query-43.rst @@ -8,6 +8,19 @@ db.inventory.find( { status: "A" } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar + and click :guilabel:`Find`: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + + .. figure:: /images/compass-project-all-fields.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-44.rst b/source/includes/driver-example-query-44.rst index 24a70fb3453..88db5e974b5 100644 --- a/source/includes/driver-example-query-44.rst +++ b/source/includes/driver-example-query-44.rst @@ -8,6 +8,27 @@ db.inventory.find( { status: "A" }, { item: 1, status: 1 } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + Copy the following expression into the :guilabel:`Project` + bar: + + .. class:: copyable-code + .. code-block:: javascript + + { item: 1, status: 1 } + + Click :guilabel:`Find`. + + .. figure:: /images/compass-project-specified-plus-id.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-45.rst b/source/includes/driver-example-query-45.rst index e5308fc4d90..f1108145961 100644 --- a/source/includes/driver-example-query-45.rst +++ b/source/includes/driver-example-query-45.rst @@ -8,6 +8,27 @@ db.inventory.find( { status: "A" }, { item: 1, status: 1, _id: 0 } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + Copy the following expression into the :guilabel:`Project` + bar: + + .. class:: copyable-code + .. code-block:: javascript + + { item: 1, status: 1, _id: 0 } + + Click :guilabel:`Find`. + + .. figure:: /images/compass-project-suppress-id.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-46.rst b/source/includes/driver-example-query-46.rst index c83a8c67196..53567cbf505 100644 --- a/source/includes/driver-example-query-46.rst +++ b/source/includes/driver-example-query-46.rst @@ -8,6 +8,27 @@ db.inventory.find( { status: "A" }, { status: 0, instock: 0 } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + Copy the following expression into the :guilabel:`Project` + bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: 0, instock: 0 } + + Click :guilabel:`Find`. + + .. figure:: /images/compass-project-exclude-fields.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-47.rst b/source/includes/driver-example-query-47.rst index 78dcb15e1a9..0d04a7eb6e7 100644 --- a/source/includes/driver-example-query-47.rst +++ b/source/includes/driver-example-query-47.rst @@ -11,6 +11,27 @@ { item: 1, status: 1, "size.uom": 1 } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + Copy the following expression into the :guilabel:`Project` + bar: + + .. class:: copyable-code + .. code-block:: javascript + + { item: 1, status: 1, "size.uom": 1 } + + Click :guilabel:`Find`. + + .. figure:: /images/compass-project-embedded-fields.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-48.rst b/source/includes/driver-example-query-48.rst index 4f92a5ced18..a04e1e20a32 100644 --- a/source/includes/driver-example-query-48.rst +++ b/source/includes/driver-example-query-48.rst @@ -11,6 +11,27 @@ { "size.uom": 0 } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + Copy the following expression into the :guilabel:`Project` + bar: + + .. class:: copyable-code + .. code-block:: javascript + + { "size.uom": 0 } + + Click :guilabel:`Find`. + + .. figure:: /images/compass-project-suppress-embedded-field.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-49.rst b/source/includes/driver-example-query-49.rst index 6ced67cccfb..5b9a2619740 100644 --- a/source/includes/driver-example-query-49.rst +++ b/source/includes/driver-example-query-49.rst @@ -8,6 +8,27 @@ db.inventory.find( { status: "A" }, { item: 1, status: 1, "instock.qty": 1 } ) + - id: compass + content: | + Copy the following expression into the :guilabel:`Filter` bar: + + .. class:: copyable-code + .. code-block:: javascript + + { status: "A" } + + Copy the following expression into the :guilabel:`Project` + bar: + + .. class:: copyable-code + .. code-block:: javascript + + { item: 1, status: 1, "instock.qty": 1 } + + Click :guilabel:`Find`. + + .. figure:: /images/compass-project-embedded-array-docs.png + - id: python content: | .. class:: copyable-code diff --git a/source/includes/driver-example-query-50.rst b/source/includes/driver-example-query-50.rst index 3cbafdecc43..0b331525dc3 100644 --- a/source/includes/driver-example-query-50.rst +++ b/source/includes/driver-example-query-50.rst @@ -6,7 +6,7 @@ .. class:: copyable-code .. code-block:: javascript - db.inventory.find( { status: "A" }, { name: 1, status: 1, instock: { $slice: -1 } } ) + db.inventory.find( { status: "A" }, { item: 1, status: 1, instock: { $slice: -1 } } ) - id: python content: | diff --git a/source/includes/driver-example-query-intro.rst b/source/includes/driver-example-query-intro.rst index 3d7b5639918..48c56c6cf2a 100644 --- a/source/includes/driver-example-query-intro.rst +++ b/source/includes/driver-example-query-intro.rst @@ -9,6 +9,13 @@ ``inventory`` collection. To populate the ``inventory`` collection, run the following: + - id: compass + content: | + This page provides examples of |query_operations| in + :ref:`MongoDB Compass `. The examples on this + page use the ``inventory`` collection. Populate the + ``inventory`` collection with the following documents: + - id: python content: | This page provides examples of |query_operations| using the diff --git a/source/includes/fact-projection-ops.rst b/source/includes/fact-projection-ops.rst new file mode 100644 index 00000000000..38fc1ba6037 --- /dev/null +++ b/source/includes/fact-projection-ops.rst @@ -0,0 +1,3 @@ +For fields that contain arrays, MongoDB provides the following +projection operators for manipulating arrays: :projection:`$elemMatch`, +:projection:`$slice`, and :projection:`$`. \ No newline at end of file diff --git a/source/includes/fact-projection-slice-example.rst b/source/includes/fact-projection-slice-example.rst new file mode 100644 index 00000000000..b8403f7476c --- /dev/null +++ b/source/includes/fact-projection-slice-example.rst @@ -0,0 +1,2 @@ +The following example uses the :projection:`$slice` projection operator +to return the last element in the ``instock`` array: \ No newline at end of file diff --git a/source/tutorial/project-fields-from-query-results.txt b/source/tutorial/project-fields-from-query-results.txt index 035e0e125f0..65ef88654e2 100644 --- a/source/tutorial/project-fields-from-query-results.txt +++ b/source/tutorial/project-fields-from-query-results.txt @@ -34,6 +34,11 @@ Return All Fields in Matching Documents :method:`db.collection.find()` method returns all fields in the matching documents. + - id: compass + content: | + If you do not specify a :term:`projection` document, Compass + returns all fields in the matching documents. + - id: python content: | If you do not specify a :term:`projection` document, the @@ -79,7 +84,7 @@ Return All Fields in Matching Documents - id: scala content: | If you do not specify a :term:`projection`, the - :scala-api:`collection.find()` + :scala-api:`collection.find()` method returns all fields in the matching documents. - id: csharp @@ -141,8 +146,10 @@ fields in the matching documents: .. include:: /includes/driver-example-query-46.rst -With the exception of the ``_id`` field, you cannot combine inclusion -and exclusion statements in projection documents. +.. note:: + + With the exception of the ``_id`` field, you cannot combine inclusion + and exclusion statements in projection documents. Return Specific Fields in Embedded Documents -------------------------------------------- @@ -151,9 +158,14 @@ You can return specific fields in an embedded document. Use the :ref:`dot notation ` to refer to the embedded field and set to ``1`` in the projection document. -The following example returns: the ``_id`` field (returned by default), -``item`` field, ``status`` field, and the ``uom`` field in the ``size`` -document; the ``uom`` field remains embedded in the ``size`` document. +The following example returns: + +- The ``_id`` field (returned by default), +- The ``item`` field, +- The ``status`` field, +- The ``uom`` field in the ``size`` document. + +The ``uom`` field remains embedded in the ``size`` document. .. include:: /includes/driver-example-query-47.rst @@ -176,30 +188,29 @@ Projection on Embedded Documents in an Array Use :ref:`dot notation ` to project specific fields inside documents embedded in an array. -The following example specifies a projection to return the ``item`` -field, the ``status`` field, and the ``qty`` field in the documents -embedded in the ``instock`` array. The ``_id`` field is returned by -default. +The following example specifies a projection to return: + +- The ``_id`` field (returned by default), +- The ``item`` field, +- The ``status`` field, +- The ``qty`` field in the documents embedded in the ``instock`` array. .. include:: /includes/driver-example-query-49.rst Project Specific Array Elements in the Returned Array ----------------------------------------------------- -For fields that contain arrays, MongoDB provides the following -projection operators: :projection:`$elemMatch`, :projection:`$slice`, -and :projection:`$`. - -The following example uses the :projection:`$slice` projection operator -to return just the last element in the ``instock`` array. - -.. include:: /includes/driver-example-query-50.rst - .. tabs-drivers:: tabs: - id: shell content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -207,8 +218,23 @@ to return just the last element in the ``instock`` array. ``{ "instock.0": 1 }`` projection will *not* project the array with the first element. + - id: compass + content: | + Currently, MongoDB Compass does not support any methods for + projecting specific array elements in a returned array. + + For additional details and examples on projection in MongoDB + Compass, refer to the Compass + :ref:`Query Bar ` documentation. + - id: python content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -218,6 +244,12 @@ to return just the last element in the ``instock`` array. - id: java-sync content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -227,6 +259,12 @@ to return just the last element in the ``instock`` array. - id: java-async content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -236,6 +274,12 @@ to return just the last element in the ``instock`` array. - id: nodejs content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -245,6 +289,12 @@ to return just the last element in the ``instock`` array. - id: php content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -254,6 +304,12 @@ to return just the last element in the ``instock`` array. - id: perl content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -263,6 +319,12 @@ to return just the last element in the ``instock`` array. - id: ruby content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -272,6 +334,12 @@ to return just the last element in the ``instock`` array. - id: scala content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. For instance, you *cannot* @@ -281,6 +349,12 @@ to return just the last element in the ``instock`` array. - id: csharp content: | + .. include:: /includes/fact-projection-ops.rst + + .. include:: /includes/fact-projection-slice-example.rst + + .. include:: /includes/driver-example-query-50.rst + :projection:`$elemMatch`, :projection:`$slice`, and :projection:`$` are the *only* way to project specific elements to include in the returned array. @@ -300,3 +374,4 @@ to return just the last element in the ``instock`` array. - id: shell content: | .. include:: /includes/footnote-set-shell-batch-size.rst +