From 92de41485b3bf82f2c387ba2966dcd7731e0ae72 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Fri, 13 Dec 2024 10:21:43 -0500
Subject: [PATCH 1/5] DOCSP-45193: Specify queries

---
 source/includes/read/specify-queries.rb |  79 +++++++
 source/read.txt                         |   3 +-
 source/read/specify-a-query.txt         | 271 ++++++++++++++++++++++++
 3 files changed, 352 insertions(+), 1 deletion(-)
 create mode 100644 source/includes/read/specify-queries.rb
 create mode 100644 source/read/specify-a-query.txt

diff --git a/source/includes/read/specify-queries.rb b/source/includes/read/specify-queries.rb
new file mode 100644
index 00000000..43680d46
--- /dev/null
+++ b/source/includes/read/specify-queries.rb
@@ -0,0 +1,79 @@
+require 'bundler/inline'
+
+gemfile do
+  source 'https://rubygems.org'
+  gem 'mongo'
+end
+
+uri = '<connection string>'
+
+Mongo::Client.new(uri) do |client|
+    # start-setup
+    database = client.use('db')
+    collection = database[:fruits]
+
+    # Inserts documents representing fruits
+    fruits = [
+    { _id: 1, name: 'apples', qty: 5, rating: 3, color: 'red', type: ['fuji', 'honeycrisp'] },
+    { _id: 2, name: 'bananas', qty: 7, rating: 4, color: 'yellow', type: ['cavendish'] },
+    { _id: 3, name: 'oranges', qty: 6, rating: 2, type: ['naval', 'mandarin'] },
+    { _id: 4, name: 'pineapples', qty: 3, rating: 5, color: 'yellow' }
+    ]
+
+    collection.insert_many(fruits)
+    # end-setup
+
+    # Retrieves documents in which the "color" value is "yellow"
+    # start-find-exact
+    filter = { color: 'yellow' }
+    results = collection.find(filter)
+    results.each do |doc|
+      puts doc
+    end
+    # end-find-exact
+
+    # Retrieves and prints documents in which the "rating" value is greater than 2
+    # start-find-comparison
+    filter = { rating: { '$gt' => 2 } }
+    results = collection.find(filter)
+    results.each do |doc|
+      puts doc
+    end
+    # end-find-comparison
+
+    # Retrieves and prints documents that match one or both query filters
+    # start-find-logical
+    filter = { '$or' => [{ qty: { '$gt' => 5 } }, { color: 'yellow' }] }
+    results = collection.find(filter)
+    results.each do |doc|
+      puts doc
+    end
+    # end-find-logical
+
+    # Retrieves and prints documents in which the "type" array has 2 elements
+    # start-find-array
+    filter = { type: { '$size' => 2 } }
+    results = collection.find(filter)
+    results.each do |doc|
+      puts doc
+    end
+    # end-find-array
+
+    # Retrieves and prints documents that have a "color" field
+    # start-find-element
+    filter = { color: { '$exists' => true } }
+    results = collection.find(filter)
+    results.each do |doc|
+      puts doc
+    end
+    # end-find-element
+
+    # Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters
+    # start-find-evaluation
+    filter = { name: /p{2,}/ }
+    results = collection.find(filter)
+    results.each do |doc|
+      puts doc
+    end
+    # end-find-evaluation
+end
diff --git a/source/read.txt b/source/read.txt
index e9822bf6..5dbdc8fb 100644
--- a/source/read.txt
+++ b/source/read.txt
@@ -22,4 +22,5 @@ Read Data from MongoDB
    :titlesonly:
    :maxdepth: 1
 
-   Retrieve Data </read/retrieve>
\ No newline at end of file
+   Retrieve Data </read/retrieve>
+   Specify a Query </read/specify-a-query>
\ No newline at end of file
diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt
new file mode 100644
index 00000000..cfbc761e
--- /dev/null
+++ b/source/read/specify-a-query.txt
@@ -0,0 +1,271 @@
+.. _ruby-specify-query:
+
+===============
+Specify a Query
+===============
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+.. facet::
+   :name: genre
+   :values: reference
+
+.. meta::
+   :keywords: expressions, operations, read, filter, code example
+
+Overview
+--------
+
+In this guide, you can learn how to specify a query by using the {+driver-short+}.
+
+You can refine the set of documents that a query returns by creating a
+**query filter**. A query filter is an expression that specifies the search
+criteria that MongoDB uses to match documents in a read or write operation.
+In a query filter, you can prompt the driver to search for documents that have
+an exact match to your query, or you can compose query filters to express more
+complex matching criteria.
+
+Sample Data
+~~~~~~~~~~~
+
+The examples in this guide run operations on the ``fruits`` collection,
+which contains documents representing fruits. The following
+code example shows how to create a database and collection, then
+insert the sample documents into your collection:
+
+.. literalinclude:: /includes/read/specify-queries.rb
+   :start-after: start-setup
+   :end-before: end-setup
+   :language: ruby
+   :dedent:
+   :copyable:
+
+Exact Match
+-----------
+
+Literal value queries return documents that have an exact match to your query filter.
+
+The following example specifies a query filter as a parameter to the ``find``
+method. The code returns all documents in which the value of the ``color`` field
+is ``"yellow"``:
+
+.. io-code-block::
+   :copyable: 
+
+   .. input:: /includes/read/specify-queries.rb
+      :start-after: start-find-exact
+      :end-before: end-find-exact
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false    
+
+      {"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
+      {"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
+
+.. note:: Find All Documents
+
+   To find all documents in a collection, call the ``find`` method
+   without passing any parameters:
+
+   .. code-block:: ruby
+
+      results = collection.find
+
+Comparison Operators
+--------------------
+
+Comparison operators evaluate a document field value against a specified value
+in your query filter. The following list describes common comparison operators:
+
+- ``$gt``: Greater than
+- ``$lte``: Less than or Equal
+- ``$ne``: Not equal
+
+.. tip::
+
+   To view a full list of comparison operators, see the :manual:`Comparison Query Operators
+   </reference/operator/query-comparison/>` guide in the {+mdb-server+} manual. 
+
+The following example specifies a comparison operator in a query filter as a
+parameter to the ``find`` method. The code returns all documents that have a
+``rating`` field value greater than ``2``:
+
+.. io-code-block::
+   :copyable: 
+
+   .. input:: /includes/read/specify-queries.rb
+      :start-after: start-find-comparison
+      :end-before: end-find-comparison
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
+      {"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
+      {"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
+
+Logical Operators
+-----------------
+
+Logical operators match documents by using logic applied to the results of two or
+more sets of expressions. The following list describes each logical operator: 
+
+- ``$and``: Returns all documents that match the conditions of *all* clauses
+- ``$or``: Returns all documents that match the conditions of *one* clause
+- ``$nor``: Returns all documents that *do not* match the conditions of any clause
+- ``$not``: Returns all documents that *do not* match the expression
+
+.. tip::
+
+   To learn more about logical operators, see the :manual:`Logical Query Operators
+   </reference/operator/query-logical/>` guide in the {+mdb-server+} manual.
+
+The following example specifies a logical operator in a query filter as a
+parameter to the ``find`` method. The code returns all documents that have a
+``qty`` field value greater than ``5`` **or** a ``color`` field value of
+``"yellow"``:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/specify-queries.rb
+      :start-after: start-find-logical
+      :end-before: end-find-logical
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
+      {"_id"=>3, "name"=>"oranges", "qty"=>6, "rating"=>2, "type"=>["naval", "mandarin"]}
+      {"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
+
+Array Operators
+---------------
+
+Array operators match documents based on the value or quantity of elements in an
+array field. The following list describes each array operator:
+
+- ``$all``: Returns documents with arrays that contain all elements in the query
+- ``$elemMatch``: Returns documents if an element in their array field matches
+   all conditions in the query
+- ``$size``: Returns all documents with arrays of a specified size
+
+.. tip::
+
+    To learn more about array operators, see the :manual:`Array Query Operators
+    </reference/operator/query-array/>` guide in the {+mdb-server+} manual.
+
+The following example specifies an array operator in a query filter as a
+parameter to the ``find`` method. The code returns all documents in which the
+``type`` array field contains ``2`` elements:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/specify-queries.rb
+      :start-after: start-find-array
+      :end-before: end-find-array
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
+      {"_id"=>3, "name"=>"oranges", "qty"=>6, "rating"=>2, "type"=>["naval", "mandarin"]}
+
+Element Operators
+-----------------
+
+Element operators query data based on the presence or type of a field. The following
+list describes each element operator: 
+
+- ``$exists``: Returns documents that contain the specified field
+- ``$type``: Returns documents that contain a field of the specified type
+
+.. tip::
+
+    To learn more about element operators, see the :manual:`Element Query Operators
+    </reference/operator/query-element/>` guide in the {+mdb-server+} manual.
+
+The following example specifies an element operator in a query filter as a
+parameter to the ``find`` method. The code returns all documents that have a
+``color`` field:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/specify-queries.rb
+      :start-after: start-find-element
+      :end-before: end-find-element
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
+      {"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
+      {"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
+
+Evaluation Operators
+--------------------
+
+Evaluation operators return data based on evaluations of either individual
+fields or the entire collection's documents. The following list describes
+common element operators: 
+
+- ``$text``: Performs a text search on the documents
+- ``$regex``: Returns documents that match a specified regular expression
+- ``$mod``: Performs a modulo operation on the value of a field and
+  returns documents where the remainder is a specified value
+
+.. tip::
+
+    To view a full list of evaluation operators, see the :manual:`Evaluation Query Operators
+    </reference/operator/query-evaluation/>` guide in the {+mdb-server+} manual.
+
+The following example specifies an evaluation operator in a query filter as a
+parameter to the ``find`` method. The code uses a regular expression to return
+all documents in which the ``name`` field value has at least two consecutive
+``'p'`` characters:
+
+.. io-code-block::
+   :copyable:
+
+   .. input:: /includes/read/specify-queries.rb
+      :start-after: start-find-evaluation
+      :end-before: end-find-evaluation
+      :language: ruby
+      :dedent:
+
+   .. output::
+      :visible: false
+
+      {"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
+      {"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
+
+Additional Information
+----------------------
+
+To learn more about querying documents, see the :manual:`Query Documents
+</tutorial/query-documents/>` guide in the {+mdb-server+} manual.
+
+To learn more about retrieving documents with the {+driver-short+}, see the
+:ref:`ruby-retrieve` guide.
+
+API Documentation
+~~~~~~~~~~~~~~~~~
+
+To learn more about the ``find`` method, see the `API documentation.
+<{+api-root+}/Mongo/Collection.html#find-instance_method>`__ 
\ No newline at end of file

From 87fe6d5e9fa7eb03664fd036c51dff35521a18e0 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Fri, 13 Dec 2024 10:32:39 -0500
Subject: [PATCH 2/5] edits

---
 source/read/specify-a-query.txt | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt
index cfbc761e..1bc89d98 100644
--- a/source/read/specify-a-query.txt
+++ b/source/read/specify-a-query.txt
@@ -51,7 +51,7 @@ Literal value queries return documents that have an exact match to your query fi
 
 The following example specifies a query filter as a parameter to the ``find``
 method. The code returns all documents in which the value of the ``color`` field
-is ``"yellow"``:
+is ``'yellow'``:
 
 .. io-code-block::
    :copyable: 
@@ -83,9 +83,12 @@ Comparison Operators
 Comparison operators evaluate a document field value against a specified value
 in your query filter. The following list describes common comparison operators:
 
-- ``$gt``: Greater than
-- ``$lte``: Less than or Equal
-- ``$ne``: Not equal
+- ``$gt``: Returns documents in which the value of the given field is *greater than*
+  the specified value
+- ``$lte``: Returns documents in which the value of the given field is *less than or
+  equal to* the specified value
+- ``$ne``: Returns documents in which the value of the given field *does not equal* the
+  specified value
 
 .. tip::
 
@@ -118,10 +121,10 @@ Logical Operators
 Logical operators match documents by using logic applied to the results of two or
 more sets of expressions. The following list describes each logical operator: 
 
-- ``$and``: Returns all documents that match the conditions of *all* clauses
-- ``$or``: Returns all documents that match the conditions of *one* clause
-- ``$nor``: Returns all documents that *do not* match the conditions of any clause
-- ``$not``: Returns all documents that *do not* match the expression
+- ``$and``: Returns documents that match the conditions of *all* clauses
+- ``$or``: Returns documents that match the conditions of *one* clause
+- ``$nor``: Returns documents that *do not* match the conditions of any clause
+- ``$not``: Returns documents that *do not* match the expression
 
 .. tip::
 
@@ -131,7 +134,7 @@ more sets of expressions. The following list describes each logical operator:
 The following example specifies a logical operator in a query filter as a
 parameter to the ``find`` method. The code returns all documents that have a
 ``qty`` field value greater than ``5`` **or** a ``color`` field value of
-``"yellow"``:
+``'yellow'``:
 
 .. io-code-block::
    :copyable:
@@ -157,8 +160,8 @@ array field. The following list describes each array operator:
 
 - ``$all``: Returns documents with arrays that contain all elements in the query
 - ``$elemMatch``: Returns documents if an element in their array field matches
-   all conditions in the query
-- ``$size``: Returns all documents with arrays of a specified size
+  all conditions in the query
+- ``$size``: Returns documents with arrays of a specified size
 
 .. tip::
 
@@ -258,8 +261,8 @@ all documents in which the ``name`` field value has at least two consecutive
 Additional Information
 ----------------------
 
-To learn more about querying documents, see the :manual:`Query Documents
-</tutorial/query-documents/>` guide in the {+mdb-server+} manual.
+To learn more about querying documents, see :manual:`Query Documents
+</tutorial/query-documents/>` in the {+mdb-server+} manual.
 
 To learn more about retrieving documents with the {+driver-short+}, see the
 :ref:`ruby-retrieve` guide.

From b4e6f82375ed31df3db1487b9262d5e86dd24cd4 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Fri, 13 Dec 2024 10:36:53 -0500
Subject: [PATCH 3/5] wording

---
 source/read/specify-a-query.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt
index 1bc89d98..f88d2d75 100644
--- a/source/read/specify-a-query.txt
+++ b/source/read/specify-a-query.txt
@@ -264,7 +264,7 @@ Additional Information
 To learn more about querying documents, see :manual:`Query Documents
 </tutorial/query-documents/>` in the {+mdb-server+} manual.
 
-To learn more about retrieving documents with the {+driver-short+}, see the
+To learn more about retrieving documents by using the {+driver-short+}, see the
 :ref:`ruby-retrieve` guide.
 
 API Documentation

From 5843855cd54062ed422ffac23c9e902b5ad3e684 Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Tue, 17 Dec 2024 15:44:11 -0500
Subject: [PATCH 4/5] LM feedback

---
 source/read/specify-a-query.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt
index f88d2d75..2208adfa 100644
--- a/source/read/specify-a-query.txt
+++ b/source/read/specify-a-query.txt
@@ -34,7 +34,7 @@ Sample Data
 
 The examples in this guide run operations on the ``fruits`` collection,
 which contains documents representing fruits. The following
-code example shows how to create a database and collection, then
+code example shows how to create a database and collection, and then
 insert the sample documents into your collection:
 
 .. literalinclude:: /includes/read/specify-queries.rb

From dbe77a7081bb1d0696155ec439813c7802d14b2b Mon Sep 17 00:00:00 2001
From: norareidy <nora.reidy@mongodb.com>
Date: Thu, 19 Dec 2024 13:48:08 -0500
Subject: [PATCH 5/5] JB feedback

---
 source/includes/read/specify-queries.rb | 120 ++++++++++++------------
 source/read/specify-a-query.txt         |   6 ++
 2 files changed, 66 insertions(+), 60 deletions(-)

diff --git a/source/includes/read/specify-queries.rb b/source/includes/read/specify-queries.rb
index 43680d46..ccd6bb63 100644
--- a/source/includes/read/specify-queries.rb
+++ b/source/includes/read/specify-queries.rb
@@ -8,72 +8,72 @@
 uri = '<connection string>'
 
 Mongo::Client.new(uri) do |client|
-    # start-setup
-    database = client.use('db')
-    collection = database[:fruits]
+  # start-setup
+  database = client.use('db')
+  collection = database[:fruits]
 
-    # Inserts documents representing fruits
-    fruits = [
-    { _id: 1, name: 'apples', qty: 5, rating: 3, color: 'red', type: ['fuji', 'honeycrisp'] },
-    { _id: 2, name: 'bananas', qty: 7, rating: 4, color: 'yellow', type: ['cavendish'] },
-    { _id: 3, name: 'oranges', qty: 6, rating: 2, type: ['naval', 'mandarin'] },
-    { _id: 4, name: 'pineapples', qty: 3, rating: 5, color: 'yellow' }
-    ]
+  # Inserts documents representing fruits
+  fruits = [
+  { _id: 1, name: 'apples', qty: 5, rating: 3, color: 'red', type: ['fuji', 'honeycrisp'] },
+  { _id: 2, name: 'bananas', qty: 7, rating: 4, color: 'yellow', type: ['cavendish'] },
+  { _id: 3, name: 'oranges', qty: 6, rating: 2, type: ['naval', 'mandarin'] },
+  { _id: 4, name: 'pineapples', qty: 3, rating: 5, color: 'yellow' }
+  ]
 
-    collection.insert_many(fruits)
-    # end-setup
+  collection.insert_many(fruits)
+  # end-setup
 
-    # Retrieves documents in which the "color" value is "yellow"
-    # start-find-exact
-    filter = { color: 'yellow' }
-    results = collection.find(filter)
-    results.each do |doc|
-      puts doc
-    end
-    # end-find-exact
+  # Retrieves documents in which the "color" value is "yellow"
+  # start-find-exact
+  filter = { color: 'yellow' }
+  results = collection.find(filter)
+  results.each do |doc|
+    puts doc
+  end
+  # end-find-exact
 
-    # Retrieves and prints documents in which the "rating" value is greater than 2
-    # start-find-comparison
-    filter = { rating: { '$gt' => 2 } }
-    results = collection.find(filter)
-    results.each do |doc|
-      puts doc
-    end
-    # end-find-comparison
+  # Retrieves and prints documents in which the "rating" value is greater than 2
+  # start-find-comparison
+  filter = { rating: { '$gt' => 2 } }
+  results = collection.find(filter)
+  results.each do |doc|
+    puts doc
+  end
+  # end-find-comparison
 
-    # Retrieves and prints documents that match one or both query filters
-    # start-find-logical
-    filter = { '$or' => [{ qty: { '$gt' => 5 } }, { color: 'yellow' }] }
-    results = collection.find(filter)
-    results.each do |doc|
-      puts doc
-    end
-    # end-find-logical
+  # Retrieves and prints documents that match one or both query filters
+  # start-find-logical
+  filter = { '$or' => [{ qty: { '$gt' => 5 } }, { color: 'yellow' }] }
+  results = collection.find(filter)
+  results.each do |doc|
+    puts doc
+  end
+  # end-find-logical
 
-    # Retrieves and prints documents in which the "type" array has 2 elements
-    # start-find-array
-    filter = { type: { '$size' => 2 } }
-    results = collection.find(filter)
-    results.each do |doc|
-      puts doc
-    end
-    # end-find-array
+  # Retrieves and prints documents in which the "type" array has 2 elements
+  # start-find-array
+  filter = { type: { '$size' => 2 } }
+  results = collection.find(filter)
+  results.each do |doc|
+    puts doc
+  end
+  # end-find-array
 
-    # Retrieves and prints documents that have a "color" field
-    # start-find-element
-    filter = { color: { '$exists' => true } }
-    results = collection.find(filter)
-    results.each do |doc|
-      puts doc
-    end
-    # end-find-element
+  # Retrieves and prints documents that have a "color" field
+  # start-find-element
+  filter = { color: { '$exists' => true } }
+  results = collection.find(filter)
+  results.each do |doc|
+    puts doc
+  end
+  # end-find-element
 
-    # Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters
-    # start-find-evaluation
-    filter = { name: /p{2,}/ }
-    results = collection.find(filter)
-    results.each do |doc|
-      puts doc
-    end
-    # end-find-evaluation
+  # Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters
+  # start-find-evaluation
+  filter = { name: /p{2,}/ }
+  results = collection.find(filter)
+  results.each do |doc|
+    puts doc
+  end
+  # end-find-evaluation
 end
diff --git a/source/read/specify-a-query.txt b/source/read/specify-a-query.txt
index 2208adfa..2e94c793 100644
--- a/source/read/specify-a-query.txt
+++ b/source/read/specify-a-query.txt
@@ -258,6 +258,12 @@ all documents in which the ``name`` field value has at least two consecutive
       {"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
       {"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
 
+.. note::
+
+    The {+driver-short+} implicitly uses the ``$regex`` operator
+    when a query filter includes a regular expression value, as shown
+    in the preceding example.
+
 Additional Information
 ----------------------