Skip to content

Commit cbead21

Browse files
norareidynorareidy
authored
DOCSP-41974: Specify a query (#103)
* DOCSP-41974: Specify a query * edits * output * fix * snooty.toml * RR feedback * code edits
1 parent 3887028 commit cbead21

File tree

3 files changed

+375
-1
lines changed

3 files changed

+375
-1
lines changed

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

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
<?php
2+
3+
require 'vendor/autoload.php';
4+
5+
use MongoDB\Client;
6+
7+
// start-setup
8+
$uri = "<connection string>";
9+
$client = new Client($uri);
10+
$collection = $client->db->fruits;
11+
12+
// Inserts documents representing fruits
13+
$fruits = [
14+
[
15+
'_id' => 1,
16+
'name' => 'apples',
17+
'qty' => 5,
18+
'rating' => 3,
19+
'color' => 'red',
20+
'type' => ['fuji', 'honeycrisp']
21+
],
22+
[
23+
'_id' => 2,
24+
'name' => 'bananas',
25+
'qty' => 7,
26+
'rating' => 4,
27+
'color' => 'yellow',
28+
'type' => ['cavendish']
29+
],
30+
[
31+
'_id' => 3,
32+
'name' => 'oranges',
33+
'qty' => 6,
34+
'rating' => 2,
35+
'type' => ['naval', 'mandarin']
36+
],
37+
[
38+
'_id' => 4,
39+
'name' => 'pineapples',
40+
'qty' => 3,
41+
'rating' => 5,
42+
'color' => 'yellow'
43+
]
44+
];
45+
46+
$result = $collection->insertMany($fruits);
47+
// end-setup
48+
49+
// Retrieves documents in which the "color" value is "yellow"
50+
// start-find-exact
51+
$cursor = $collection->find(['color' => 'yellow']);
52+
foreach ($cursor as $doc) {
53+
echo json_encode($doc) . PHP_EOL;
54+
}
55+
// end-find-exact
56+
57+
// Retrieves all documents in the collection
58+
// start-find-all
59+
$cursor = $collection->find([]);
60+
foreach ($cursor as $doc) {
61+
echo json_encode($doc) . PHP_EOL;
62+
}
63+
// end-find-all
64+
65+
// Retrieves and prints documents in which the "rating" value is greater than 2
66+
// start-find-comparison
67+
$cursor = $collection->find(['rating' => ['$gt' => 2]]);
68+
foreach ($cursor as $doc) {
69+
echo json_encode($doc) . PHP_EOL;
70+
}
71+
// end-find-comparison
72+
73+
// Retrieves and prints documents that match one or both query filters
74+
// start-find-logical
75+
$cursor = $collection->find([
76+
'$or' => [
77+
['qty' => ['$gt' => 5]],
78+
['color' => 'yellow']
79+
]
80+
]);
81+
foreach ($cursor as $doc) {
82+
echo json_encode($doc) . PHP_EOL;
83+
}
84+
// end-find-logical
85+
86+
// Retrieves and prints documents in which the "type" array has 2 elements
87+
// start-find-array
88+
$cursor = $collection->find(['type' => ['$size' => 2]]);
89+
foreach ($cursor as $doc) {
90+
echo json_encode($doc) . PHP_EOL;
91+
}
92+
// end-find-array
93+
94+
// Retrieves and prints documents that have a "color" field
95+
// start-find-element
96+
$cursor = $collection->find(['color' => ['$exists' => true]]);
97+
foreach ($cursor as $doc) {
98+
echo json_encode($doc) . PHP_EOL;
99+
}
100+
// end-find-element
101+
102+
// Retrieves and prints documents in which the "name" value has at least two consecutive "p" characters
103+
// start-find-evaluation
104+
$cursor = $collection->find(['name' => ['$regex' => 'p{2,}']]);
105+
foreach ($cursor as $doc) {
106+
echo json_encode($doc) . PHP_EOL;
107+
}
108+
// end-find-evaluation

‎source/read.txt

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,8 @@ Read Data from MongoDB
77
.. toctree::
88
:titlesonly:
99
:maxdepth: 1
10-
10+
1111
/read/retrieve
12+
/read/specify-a-query
1213
/read/project
1314

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

Lines changed: 265 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,265 @@
1+
.. _php-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, write, filter
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to specify a query by using the {+php-library+}.
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, then
38+
insert the sample documents into your collection:
39+
40+
.. literalinclude:: /includes/read/specify-queries.php
41+
:start-after: start-setup
42+
:end-before: end-setup
43+
:language: php
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 ``MongoDB\Collection::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.php
60+
:start-after: start-find-exact
61+
:end-before: end-find-exact
62+
:language: php
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+
.. tip:: Find All Documents
72+
73+
To find all documents in a collection, call the ``find()`` method and pass it an
74+
empty query filter. The following example finds all documents in a
75+
collection:
76+
77+
.. literalinclude:: /includes/read/specify-queries.php
78+
:start-after: start-find-all
79+
:end-before: end-find-all
80+
:language: php
81+
:dedent:
82+
:copyable:
83+
84+
Comparison Operators
85+
--------------------
86+
87+
Comparison operators evaluate a document field value against a specified value
88+
in your query filter. The following list defines common comparison operators:
89+
90+
- ``$gt``: Greater than
91+
- ``$lte``: Less than or Equal
92+
- ``$ne``: Not equal
93+
94+
To view a full list of comparison operators, see the :manual:`Comparison Query Operators
95+
</reference/operator/query-comparison/>` guide in the {+mdb-server+} manual.
96+
97+
The following example specifies a comparison operator in a query filter as a
98+
parameter to the ``MongoDB\Collection::find()`` method. The code returns all documents
99+
in which the value of the ``rating`` field is greater than ``2``:
100+
101+
.. io-code-block::
102+
:copyable:
103+
104+
.. input:: /includes/read/specify-queries.php
105+
:start-after: start-find-comparison
106+
:end-before: end-find-comparison
107+
:language: php
108+
:dedent:
109+
110+
.. output::
111+
:visible: false
112+
113+
{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
114+
{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
115+
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}
116+
117+
Logical Operators
118+
-----------------
119+
120+
Logical operators match documents by using logic applied to the results of two or
121+
more sets of expressions. The following list describes each logical operator:
122+
123+
- ``$and``: Returns all documents that match the conditions of *all* clauses
124+
- ``$or``: Returns all documents that match the conditions of *one* clause
125+
- ``$nor``: Returns all documents that *do not* match the conditions of any clause
126+
- ``$not``: Returns all documents that *do not* match the expression
127+
128+
To learn more about logical operators, see the :manual:`Logical Query Operators
129+
</reference/operator/query-logical/>` guide in the {+mdb-server+} manual.
130+
131+
The following example specifies a logical operator in a query filter as a
132+
parameter to the ``MongoDB\Collection::find()`` method. The code returns all documents
133+
in which the ``qty`` field value is greater than ``5`` **or** the ``color`` field
134+
value is ``'yellow'``:
135+
136+
.. io-code-block::
137+
:copyable:
138+
139+
.. input:: /includes/read/specify-queries.php
140+
:start-after: start-find-logical
141+
:end-before: end-find-logical
142+
:language: php
143+
:dedent:
144+
145+
.. output::
146+
:visible: false
147+
148+
{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
149+
{"_id":3,"name":"oranges","qty":6,"rating":2,"type":["naval","mandarin"]}
150+
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}
151+
152+
Array Operators
153+
---------------
154+
155+
Array operators match documents based on the value or quantity of elements in an
156+
array field. The following list describes the available array operators:
157+
158+
- ``$all``: Returns documents with arrays that contain all elements in the query
159+
- ``$elemMatch``: Returns documents if an element in their array field matches all conditions in the query
160+
- ``$size``: Returns all documents with arrays of a specified size
161+
162+
To learn more about array operators, see the :manual:`Array Query Operators
163+
</reference/operator/query-array/>` guide in the {+mdb-server+} manual.
164+
165+
The following example specifies an array operator in a query filter as a
166+
parameter to the ``MongoDB\Collection::find()`` method. The code returns all
167+
documents in which the ``type`` array field contains ``2`` elements:
168+
169+
.. io-code-block::
170+
:copyable:
171+
172+
.. input:: /includes/read/specify-queries.php
173+
:start-after: start-find-array
174+
:end-before: end-find-array
175+
:language: php
176+
:dedent:
177+
178+
.. output::
179+
:visible: false
180+
181+
{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
182+
{"_id":3,"name":"oranges","qty":6,"rating":2,"type":["naval","mandarin"]}
183+
184+
Element Operators
185+
-----------------
186+
187+
Element operators query data based on the presence or type of a field.
188+
189+
To learn more about element operators, see the :manual:`Element Query Operators
190+
</reference/operator/query-element/>` guide in the {+mdb-server+} manual.
191+
192+
The following example specifies an element operator in a query filter as a
193+
parameter to the ``MongoDB\Collection::find()`` method. The code returns all
194+
documents that have a ``color`` field:
195+
196+
.. io-code-block::
197+
:copyable:
198+
199+
.. input:: /includes/read/specify-queries.php
200+
:start-after: start-find-element
201+
:end-before: end-find-element
202+
:language: php
203+
:dedent:
204+
205+
.. output::
206+
:visible: false
207+
208+
{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
209+
{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
210+
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}
211+
212+
Evaluation Operators
213+
--------------------
214+
215+
Evaluation operators return data based on evaluations of either individual
216+
fields or the entire collection's documents.
217+
218+
The following list describes common evaluation operators:
219+
220+
- ``$text``: Performs a text search on the documents
221+
- ``$regex``: Returns documents that match a specified regular expression
222+
- ``$mod``: Performs a modulo operation on the value of a field and
223+
returns documents where the remainder is a specified value
224+
225+
To view a full list of evaluation operators, see the :manual:`Evaluation Query Operators
226+
</reference/operator/query-evaluation/>` guide in the {+mdb-server+} manual.
227+
228+
The following example specifies an evaluation operator in a query filter as a
229+
parameter to the ``MongoDB\Collection::find()`` method. The code uses a regular
230+
expression to return all documents in which the ``name`` field value has at least
231+
two consecutive ``'p'`` characters:
232+
233+
.. io-code-block::
234+
:copyable:
235+
236+
.. input:: /includes/read/specify-queries.php
237+
:start-after: start-find-evaluation
238+
:end-before: end-find-evaluation
239+
:language: php
240+
:dedent:
241+
242+
.. output::
243+
:visible: false
244+
245+
{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
246+
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}
247+
248+
Additional Information
249+
----------------------
250+
251+
To learn more about querying documents, see the :manual:`Query Documents
252+
</tutorial/query-documents/>` guide in the {+mdb-server+} manual.
253+
254+
.. TODO:
255+
To learn more about retrieving documents with the {+php-library+}, see the
256+
:ref:`php-retrieve` guide.
257+
258+
API Documentation
259+
~~~~~~~~~~~~~~~~~
260+
261+
To learn more about any of the methods or types discussed in this
262+
guide, see the following API documentation:
263+
264+
- `MongoDB\\Collection::find() <{+api+}/method/MongoDBCollection-find/>`__
265+
- `MongoDB\\Collection::insertMany() <{+api+}/method/MongoDBCollection-insertMany/>`__

0 commit comments

Comments
 (0)