Skip to content

Commit 91b251a

Browse files
norareidynorareidy
authored
DOCSP-45193: Specify queries (#102)
* DOCSP-45193: Specify queries * edits * wording * LM feedback * JB feedback
1 parent 3bc777b commit 91b251a

File tree

3 files changed

+360
-0
lines changed

3 files changed

+360
-0
lines changed

‎source/includes/read/specify-queries.rb

+79
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
require 'bundler/inline'
2+
3+
gemfile do
4+
source 'https://rubygems.org'
5+
gem 'mongo'
6+
end
7+
8+
uri = '<connection string>'
9+
10+
Mongo::Client.new(uri) do |client|
11+
# start-setup
12+
database = client.use('db')
13+
collection = database[:fruits]
14+
15+
# Inserts documents representing fruits
16+
fruits = [
17+
{ _id: 1, name: 'apples', qty: 5, rating: 3, color: 'red', type: ['fuji', 'honeycrisp'] },
18+
{ _id: 2, name: 'bananas', qty: 7, rating: 4, color: 'yellow', type: ['cavendish'] },
19+
{ _id: 3, name: 'oranges', qty: 6, rating: 2, type: ['naval', 'mandarin'] },
20+
{ _id: 4, name: 'pineapples', qty: 3, rating: 5, color: 'yellow' }
21+
]
22+
23+
collection.insert_many(fruits)
24+
# end-setup
25+
26+
# Retrieves documents in which the "color" value is "yellow"
27+
# start-find-exact
28+
filter = { color: 'yellow' }
29+
results = collection.find(filter)
30+
results.each do |doc|
31+
puts doc
32+
end
33+
# end-find-exact
34+
35+
# Retrieves and prints documents in which the "rating" value is greater than 2
36+
# start-find-comparison
37+
filter = { rating: { '$gt' => 2 } }
38+
results = collection.find(filter)
39+
results.each do |doc|
40+
puts doc
41+
end
42+
# end-find-comparison
43+
44+
# Retrieves and prints documents that match one or both query filters
45+
# start-find-logical
46+
filter = { '$or' => [{ qty: { '$gt' => 5 } }, { color: 'yellow' }] }
47+
results = collection.find(filter)
48+
results.each do |doc|
49+
puts doc
50+
end
51+
# end-find-logical
52+
53+
# Retrieves and prints documents in which the "type" array has 2 elements
54+
# start-find-array
55+
filter = { type: { '$size' => 2 } }
56+
results = collection.find(filter)
57+
results.each do |doc|
58+
puts doc
59+
end
60+
# end-find-array
61+
62+
# Retrieves and prints documents that have a "color" field
63+
# start-find-element
64+
filter = { color: { '$exists' => true } }
65+
results = collection.find(filter)
66+
results.each do |doc|
67+
puts doc
68+
end
69+
# end-find-element
70+
71+
# Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters
72+
# start-find-evaluation
73+
filter = { name: /p{2,}/ }
74+
results = collection.find(filter)
75+
results.each do |doc|
76+
puts doc
77+
end
78+
# end-find-evaluation
79+
end

‎source/read.txt

+1
Original file line numberDiff line numberDiff line change
@@ -23,5 +23,6 @@ Read Data from MongoDB
2323
:maxdepth: 1
2424

2525
Retrieve Data </read/retrieve>
26+
Specify a Query </read/specify-a-query>
2627
Specify Documents to Return </read/specify-documents-to-return>
2728
Specify Fields to Return </read/project>

‎source/read/specify-a-query.txt

+280
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,280 @@
1+
.. _ruby-specify-query:
2+
3+
===============
4+
Specify a Query
5+
===============
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: expressions, operations, read, filter, code example
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to specify a query by using the {+driver-short+}.
24+
25+
You can refine the set of documents that a query returns by creating a
26+
**query filter**. A query filter is an expression that specifies the search
27+
criteria that MongoDB uses to match documents in a read or write operation.
28+
In a query filter, you can prompt the driver to search for documents that have
29+
an exact match to your query, or you can compose query filters to express more
30+
complex matching criteria.
31+
32+
Sample Data
33+
~~~~~~~~~~~
34+
35+
The examples in this guide run operations on the ``fruits`` collection,
36+
which contains documents representing fruits. The following
37+
code example shows how to create a database and collection, and then
38+
insert the sample documents into your collection:
39+
40+
.. literalinclude:: /includes/read/specify-queries.rb
41+
:start-after: start-setup
42+
:end-before: end-setup
43+
:language: ruby
44+
:dedent:
45+
:copyable:
46+
47+
Exact Match
48+
-----------
49+
50+
Literal value queries return documents that have an exact match to your query filter.
51+
52+
The following example specifies a query filter as a parameter to the ``find``
53+
method. The code returns all documents in which the value of the ``color`` field
54+
is ``'yellow'``:
55+
56+
.. io-code-block::
57+
:copyable:
58+
59+
.. input:: /includes/read/specify-queries.rb
60+
:start-after: start-find-exact
61+
:end-before: end-find-exact
62+
:language: ruby
63+
:dedent:
64+
65+
.. output::
66+
:visible: false
67+
68+
{"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
69+
{"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
70+
71+
.. note:: Find All Documents
72+
73+
To find all documents in a collection, call the ``find`` method
74+
without passing any parameters:
75+
76+
.. code-block:: ruby
77+
78+
results = collection.find
79+
80+
Comparison Operators
81+
--------------------
82+
83+
Comparison operators evaluate a document field value against a specified value
84+
in your query filter. The following list describes common comparison operators:
85+
86+
- ``$gt``: Returns documents in which the value of the given field is *greater than*
87+
the specified value
88+
- ``$lte``: Returns documents in which the value of the given field is *less than or
89+
equal to* the specified value
90+
- ``$ne``: Returns documents in which the value of the given field *does not equal* the
91+
specified value
92+
93+
.. tip::
94+
95+
To view a full list of comparison operators, see the :manual:`Comparison Query Operators
96+
</reference/operator/query-comparison/>` guide in the {+mdb-server+} manual.
97+
98+
The following example specifies a comparison operator in a query filter as a
99+
parameter to the ``find`` method. The code returns all documents that have a
100+
``rating`` field value greater than ``2``:
101+
102+
.. io-code-block::
103+
:copyable:
104+
105+
.. input:: /includes/read/specify-queries.rb
106+
:start-after: start-find-comparison
107+
:end-before: end-find-comparison
108+
:language: ruby
109+
:dedent:
110+
111+
.. output::
112+
:visible: false
113+
114+
{"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
115+
{"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
116+
{"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
117+
118+
Logical Operators
119+
-----------------
120+
121+
Logical operators match documents by using logic applied to the results of two or
122+
more sets of expressions. The following list describes each logical operator:
123+
124+
- ``$and``: Returns documents that match the conditions of *all* clauses
125+
- ``$or``: Returns documents that match the conditions of *one* clause
126+
- ``$nor``: Returns documents that *do not* match the conditions of any clause
127+
- ``$not``: Returns documents that *do not* match the expression
128+
129+
.. tip::
130+
131+
To learn more about logical operators, see the :manual:`Logical Query Operators
132+
</reference/operator/query-logical/>` guide in the {+mdb-server+} manual.
133+
134+
The following example specifies a logical operator in a query filter as a
135+
parameter to the ``find`` method. The code returns all documents that have a
136+
``qty`` field value greater than ``5`` **or** a ``color`` field value of
137+
``'yellow'``:
138+
139+
.. io-code-block::
140+
:copyable:
141+
142+
.. input:: /includes/read/specify-queries.rb
143+
:start-after: start-find-logical
144+
:end-before: end-find-logical
145+
:language: ruby
146+
:dedent:
147+
148+
.. output::
149+
:visible: false
150+
151+
{"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
152+
{"_id"=>3, "name"=>"oranges", "qty"=>6, "rating"=>2, "type"=>["naval", "mandarin"]}
153+
{"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
154+
155+
Array Operators
156+
---------------
157+
158+
Array operators match documents based on the value or quantity of elements in an
159+
array field. The following list describes each array operator:
160+
161+
- ``$all``: Returns documents with arrays that contain all elements in the query
162+
- ``$elemMatch``: Returns documents if an element in their array field matches
163+
all conditions in the query
164+
- ``$size``: Returns documents with arrays of a specified size
165+
166+
.. tip::
167+
168+
To learn more about array operators, see the :manual:`Array Query Operators
169+
</reference/operator/query-array/>` guide in the {+mdb-server+} manual.
170+
171+
The following example specifies an array operator in a query filter as a
172+
parameter to the ``find`` method. The code returns all documents in which the
173+
``type`` array field contains ``2`` elements:
174+
175+
.. io-code-block::
176+
:copyable:
177+
178+
.. input:: /includes/read/specify-queries.rb
179+
:start-after: start-find-array
180+
:end-before: end-find-array
181+
:language: ruby
182+
:dedent:
183+
184+
.. output::
185+
:visible: false
186+
187+
{"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
188+
{"_id"=>3, "name"=>"oranges", "qty"=>6, "rating"=>2, "type"=>["naval", "mandarin"]}
189+
190+
Element Operators
191+
-----------------
192+
193+
Element operators query data based on the presence or type of a field. The following
194+
list describes each element operator:
195+
196+
- ``$exists``: Returns documents that contain the specified field
197+
- ``$type``: Returns documents that contain a field of the specified type
198+
199+
.. tip::
200+
201+
To learn more about element operators, see the :manual:`Element Query Operators
202+
</reference/operator/query-element/>` guide in the {+mdb-server+} manual.
203+
204+
The following example specifies an element operator in a query filter as a
205+
parameter to the ``find`` method. The code returns all documents that have a
206+
``color`` field:
207+
208+
.. io-code-block::
209+
:copyable:
210+
211+
.. input:: /includes/read/specify-queries.rb
212+
:start-after: start-find-element
213+
:end-before: end-find-element
214+
:language: ruby
215+
:dedent:
216+
217+
.. output::
218+
:visible: false
219+
220+
{"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
221+
{"_id"=>2, "name"=>"bananas", "qty"=>7, "rating"=>4, "color"=>"yellow", "type"=>["cavendish"]}
222+
{"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
223+
224+
Evaluation Operators
225+
--------------------
226+
227+
Evaluation operators return data based on evaluations of either individual
228+
fields or the entire collection's documents. The following list describes
229+
common element operators:
230+
231+
- ``$text``: Performs a text search on the documents
232+
- ``$regex``: Returns documents that match a specified regular expression
233+
- ``$mod``: Performs a modulo operation on the value of a field and
234+
returns documents where the remainder is a specified value
235+
236+
.. tip::
237+
238+
To view a full list of evaluation operators, see the :manual:`Evaluation Query Operators
239+
</reference/operator/query-evaluation/>` guide in the {+mdb-server+} manual.
240+
241+
The following example specifies an evaluation operator in a query filter as a
242+
parameter to the ``find`` method. The code uses a regular expression to return
243+
all documents in which the ``name`` field value has at least two consecutive
244+
``'p'`` characters:
245+
246+
.. io-code-block::
247+
:copyable:
248+
249+
.. input:: /includes/read/specify-queries.rb
250+
:start-after: start-find-evaluation
251+
:end-before: end-find-evaluation
252+
:language: ruby
253+
:dedent:
254+
255+
.. output::
256+
:visible: false
257+
258+
{"_id"=>1, "name"=>"apples", "qty"=>5, "rating"=>3, "color"=>"red", "type"=>["fuji", "honeycrisp"]}
259+
{"_id"=>4, "name"=>"pineapples", "qty"=>3, "rating"=>5, "color"=>"yellow"}
260+
261+
.. note::
262+
263+
The {+driver-short+} implicitly uses the ``$regex`` operator
264+
when a query filter includes a regular expression value, as shown
265+
in the preceding example.
266+
267+
Additional Information
268+
----------------------
269+
270+
To learn more about querying documents, see :manual:`Query Documents
271+
</tutorial/query-documents/>` in the {+mdb-server+} manual.
272+
273+
To learn more about retrieving documents by using the {+driver-short+}, see the
274+
:ref:`ruby-retrieve` guide.
275+
276+
API Documentation
277+
~~~~~~~~~~~~~~~~~
278+
279+
To learn more about the ``find`` method, see the `API documentation.
280+
<{+api-root+}/Mongo/Collection.html#find-instance_method>`__

0 commit comments

Comments
 (0)