Read with Query Guide - Update (#174)

Author: biniona-mongodb

source/crud/read.txt

@@ -37,32 +37,7 @@ Procedure
 .. procedure::
    :style: normal
 
-   .. step::  Connect to your MongoDB instance.
-
-      .. include:: /includes/drivers_connect.rst
-
-   .. step::  Switch to the ``test`` database.
-   
-      Switch to the database you wish to query. In this case we will be
-      using ``test``.
-   
-      .. include:: /includes/bind_db.rst
-
-   .. step::  Retrieve all documents in the ``inventory`` collection.
-
-      .. include:: /includes/find_all.rst
-
-   .. step::  Iterate over the results.
-
-      .. include:: /includes/iterate_all_noshellcursor.rst
-
-   .. step::  Check your results.
-
-      If you loaded the data from :doc:`/server/insert`, you should
-      see output that resembles the following:
-      
-      .. include:: /includes/results_read1.rst
-      .. include:: /includes/drivers_close_connection.rst
+   .. include:: /includes/read_server.rst
 
 Summary
 -------

source/crud/read_queries.txt

@@ -0,0 +1,143 @@
+:template: guide
+
+===================================
+Read Data from MongoDB With Queries
+===================================
+
+.. default-domain:: mongodb
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+Overview
+--------
+
+In the first :doc:`/server/read` guide, you retrieved a
+document from the ``inventory`` collection. In this guide, you
+will:
+
+- use the ``insertMany`` command to insert more documents into the collection
+- query the documents
+
+.. time:: 30
+
+What You'll Need
+----------------
+
+.. include:: /includes/prereqs_read_CRUD.rst
+
+Check Your Environment
+----------------------
+
+.. include:: /includes/check_for_drivers_install.rst
+
+Procedure
+---------
+
+.. tabs-selector:: drivers
+
+Import Data and Query It
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the first part of this guide, you will insert more documents and
+retrieve some of these documents from MongoDB using a simple query.
+
+.. procedure::
+   :style: normal
+
+   .. include:: /includes/read_server_query.rst
+
+Query Data Using Embedded Documents as Criteria
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now that you have an understanding of how to retrieve data using
+query documents, you will now query against embedded documents.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Retrieve specific documents in a collection based on the contents of an embedded document.
+
+      If you wish to select documents that match all of the fields in an
+      embedded JSON object, specify an exact match of the embedded document,
+      including all of the fields and values in that embedded document in the
+      order in which they appear in the collection.
+
+      For example, the following query selects all documents where the
+      ``size`` field equals the document ``{ "h" : 14, "w" : 21, "uom" : "cm"}``:
+    
+      .. include:: /includes/driver-example-query-15.rst
+
+   .. step:: Iterate over the results.
+    
+      .. include:: /includes/iterate_all_noshellcursor.rst
+
+   .. step:: Check your results.
+    
+      If you have loaded data into your test database, you will see one or
+      more JSON documents returned. Note that the record matches the selection
+      criteria exactly.
+
+      .. include:: /includes/results_read3.rst
+
+Query Data Using Embedded Documents With Dot Notation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Now you will explore how to query embedded documents using ``dot notation``.
+
+.. procedure::
+   :style: normal
+
+   .. step:: Retrieve specific documents in a collection with dot notation.
+  
+      If you wish to select documents that exactly match just one of the
+      fields in an embedded JSON object, use  :ref:`dot notation <document-dot-notation>`.
+      (``"field.nestedField"``).
+  
+      When querying using :ref:`dot notation <document-dot-notation>`., the field and nested field names must be inside quotation marks.
+
+      The following example selects all documents where the field ``uom``
+      nested in the ``size`` field equals ``"in"``:
+
+      .. include:: /includes/driver-example-query-17.rst
+
+   .. step:: Iterate over the results.
+
+      .. include:: /includes/iterate_all.rst
+
+   .. step:: Check your results.
+  
+      If you have loaded data into your test database, you will see one or
+      more JSON documents returned. Note that the result record has a ``uom`` of ``in``.
+
+      .. include:: /includes/results_read4.rst
+  
+      .. include:: /includes/drivers_close_connection.rst
+
+Summary
+-------
+
+If you have successfully completed this guide, you have retrieved data from MongoDB
+using specific criteria as expressed in MongoDB's query syntax. You have also used
+the embedded document query syntax to retrieve documents based on embedded fields.
+
+What's Next
+-----------
+
+In the next guide, you'll learn how to read data from MongoDB using operators and compound queries.
+
+- :doc:`Read Data using Operators and Compound Queries </server/read_operators>`
+
+See Also
+--------
+
+- :doc:`/server/insert`
+- :doc:`/server/read`
+- :doc:`/server/read_operators`
+- :doc:`/server/update`
+- :doc:`/server/delete`
+
+.. guide-next::

source/includes/driver-example-query-14.rst

@@ -31,7 +31,7 @@
      - id: python
        content: |
          .. class:: copyable-code
-         .. literalinclude:: /driver-examples/test_examples.py
+         .. literalinclude:: /includes/examples/curl_examples/test_examples.py
             :language: python
             :dedent: 8
             :start-after: Start Example 14
@@ -40,7 +40,7 @@
      - id: go
        content: |
          .. class:: copyable-code
-         .. literalinclude:: /driver-examples/examples.go
+         .. literalinclude:: /includes/examples/curl_examples/examples.go
             :language: go
             :dedent: 2
             :start-after: Start Example 14
@@ -49,7 +49,7 @@
      - id: motor
        content: |
          .. class:: copyable-code
-         .. literalinclude:: /driver-examples/test_examples_motor.py
+         .. literalinclude:: /includes/examples/curl_examples/test_examples_motor.py
             :language: python
             :dedent: 8
             :start-after: Start Example 14
@@ -101,7 +101,7 @@
          Now add the ``insertMany`` call.
 
          .. class:: copyable-code
-         .. literalinclude:: /driver-examples/DocumentationSamples.java
+         .. literalinclude:: /includes/examples/curl_examples/DocumentationSamples.java
             :language: java
             :dedent: 8
             :start-after: Start Example 14
@@ -110,7 +110,7 @@
      - id: nodejs
        content: |
          .. class:: copyable-code
-         .. literalinclude:: /driver-examples/examples_tests.js
+         .. literalinclude:: /includes/examples/curl_examples/examples_tests.js
             :language: javascript
             :dedent: 8
             :start-after: Start Example 14
@@ -119,7 +119,7 @@
      #- id: php
      #  content: |
      #    .. class:: copyable-code
-     #    .. literalinclude:: /driver-examples/DocumentationExamplesTest.php
+     #    .. literalinclude:: /includes/examples/curl_examples/DocumentationExamplesTest.php
      #       :language: php
      #       :dedent: 8
      #       :start-after: Start Example 14
@@ -128,7 +128,7 @@
      #- id: perl
      #  content: |
      #    .. class:: copyable-code
-     #    .. literalinclude:: /driver-examples/driver-examples.t
+     #    .. literalinclude:: /includes/examples/curl_examples/driver-examples.t
      #       :language: perl
      #       :dedent: 4
      #       :start-after: Start Example 14
@@ -137,7 +137,7 @@
      #- id: ruby
      #  content: |
      #    .. class:: copyable-code
-     #    .. literalinclude:: /driver-examples/shell_examples_spec.rb
+     #    .. literalinclude:: /includes/examples/curl_examples/shell_examples_spec.rb
      #       :language: ruby
      #       :dedent: 6
      #       :start-after: Start Example 14
@@ -146,7 +146,7 @@
      #- id: scala
      #  content: |
      #    .. class:: copyable-code
-     #    .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala
+     #    .. literalinclude:: /includes/examples/curl_examples/DocumentationExampleSpec.scala
      #       :language: scala
      #       :dedent: 4
      #       :start-after: Start Example 14
@@ -164,7 +164,7 @@
          Next create the array of BsonDocuments and pass it to the ``insertMany`` call on ``collection``.
 
          .. class:: copyable-code
-         .. literalinclude:: /driver-examples/DocumentationExamples.cs
+         .. literalinclude:: /includes/examples/curl_examples/DocumentationExamples.cs
             :language: c#
             :dedent: 12
             :start-after: Start Example 14

source/includes/driver-example-query-15.rst

@@ -18,7 +18,7 @@
 
      - id: python
        content: |
-         .. literalinclude:: /driver-examples/test_examples.py
+         .. literalinclude:: /includes/examples/curl_examples/test_examples.py
             :language: python
             :dedent: 8
             :start-after: Start Example 15
@@ -27,15 +27,15 @@
 
      - id: go
        content: |
-         .. literalinclude:: /driver-examples/examples.go
+         .. literalinclude:: /includes/examples/curl_examples/examples.go
             :language: go
             :dedent: 2
             :start-after: Start Example 15
             :end-before: End Example 15
 
      - id: motor
        content: |
-         .. literalinclude:: /driver-examples/test_examples_motor.py
+         .. literalinclude:: /includes/examples/curl_examples/test_examples_motor.py
             :language: python
             :dedent: 8
             :start-after: Start Example 15
@@ -66,55 +66,55 @@
 
          Now add the query.
 
-         .. literalinclude:: /driver-examples/DocumentationSamples.java
+         .. literalinclude:: /includes/examples/curl_examples/DocumentationSamples.java
             :language: java
             :dedent: 8
             :start-after: Start Example 15
             :end-before: End Example 15
 
      - id: nodejs
        content: |
-         .. literalinclude:: /driver-examples/examples_tests.js
+         .. literalinclude:: /includes/examples/curl_examples/examples_tests.js
             :language: javascript
             :dedent: 8
             :start-after: Start Example 15
             :end-before: End Example 15
 
      #- id: php
      #  content: |
-     #    .. literalinclude:: /driver-examples/DocumentationExamplesTest.php
+     #    .. literalinclude:: /includes/examples/curl_examples/DocumentationExamplesTest.php
      #       :language: php
      #       :dedent: 8
      #       :start-after: Start Example 15
      #       :end-before: End Example 15
 
      #- id: perl
      #  content: |
-     #    .. literalinclude:: /driver-examples/driver-examples.t
+     #    .. literalinclude:: /includes/examples/curl_examples/driver-examples.t
      #       :language: perl
      #       :dedent: 4
      #       :start-after: Start Example 15
      #       :end-before: End Example 15
 
      #- id: ruby
      #  content: |
-     #    .. literalinclude:: /driver-examples/shell_examples_spec.rb
+     #    .. literalinclude:: /includes/examples/curl_examples/shell_examples_spec.rb
      #       :language: ruby
      #       :dedent: 8
      #       :start-after: Start Example 15
      #       :end-before: End Example 15
 
      #- id: scala
      #  content: |
-     #    .. literalinclude:: /driver-examples/DocumentationExampleSpec.scala
+     #    .. literalinclude:: /includes/examples/curl_examples/DocumentationExampleSpec.scala
      #       :language: scala
      #       :dedent: 4
      #       :start-after: Start Example 15
      #       :end-before: End Example 15
 
      - id: csharp
        content: |
-         .. literalinclude:: /driver-examples/DocumentationExamples.cs
+         .. literalinclude:: /includes/examples/curl_examples/DocumentationExamples.cs
             :language: c#
             :dedent: 12
             :start-after: Start Example 15