Skip to content

Commit 579bf29

Browse files
jmikolajmikola
committed
Revise command tutorial and sync with command() docs
Remove the geoNear example since the command itself was removed in MongoDB 4.2.
1 parent 38f96d8 commit 579bf29

File tree

1 file changed

+73
-256
lines changed

1 file changed

+73
-256
lines changed

‎docs/tutorial/commands.txt

Lines changed: 73 additions & 256 deletions
Original file line numberDiff line numberDiff line change
@@ -20,214 +20,109 @@ The |php-library| provides helper methods across the :phpclass:`Client
2020
:phpmethod:`MongoDB\\Database::command()` method may be used to run database
2121
commands that do not have a helper method.
2222

23-
Execute Database Commands
24-
-------------------------
23+
The :phpmethod:`MongoDB\\Database::command()` method always returns a
24+
:php:`MongoDB\\Driver\\Cursor <mongodb-driver-cursor>` object, since it must
25+
support execution of commands that return single result documents *and* multiple
26+
results via a command cursor.
2527

26-
Basic Command
27-
~~~~~~~~~~~~~
28+
Commands That Return a Single Result Document
29+
---------------------------------------------
2830

29-
To execute a command on a :program:`mongod` instance, use the
30-
:phpmethod:`MongoDB\\Database::command()` method. For instance, the following
31-
operation uses the :manual:`geoNear </reference/command/geoNear>` command to
32-
search for the three closest documents to longitude ``-74`` and latitude ``40``
33-
in the ``restos`` collection in the ``test`` database:
31+
Most database commands return a single result document, which can be obtained by
32+
converting the returned cursor to an array and accessing its first element. The
33+
following example executes a :manual:`ping </reference/command/ping>` command
34+
and prints its result document:
3435

3536
.. code-block:: php
3637

3738
<?php
3839

3940
$database = (new MongoDB\Client)->test;
4041

41-
$cursor = $database->command([
42-
'geoNear' => 'restos',
43-
'near' => [
44-
'type' => 'Point',
45-
'coordinates' => [-74.0, 40.0],
46-
],
47-
'spherical' => 'true',
48-
'num' => 3,
49-
]);
50-
51-
$results = $cursor->toArray()[0];
42+
$cursor = $database->command(['ping' => 1]);
5243

53-
var_dump($results);
44+
var_dump($cursor->toArray()[0]);
5445

55-
The output would then resemble:
46+
The output would resemble:
5647

5748
.. code-block:: none
5849

59-
object(MongoDB\Model\BSONDocument)#27 (1) {
50+
object(MongoDB\Model\BSONDocument)#11 (1) {
6051
["storage":"ArrayObject":private]=>
61-
array(4) {
62-
["waitedMS"]=>
63-
int(0)
64-
["results"]=>
65-
object(MongoDB\Model\BSONArray)#25 (1) {
66-
["storage":"ArrayObject":private]=>
67-
array(3) {
68-
[0]=>
69-
object(MongoDB\Model\BSONDocument)#14 (1) {
70-
["storage":"ArrayObject":private]=>
71-
array(2) {
72-
["dis"]=>
73-
float(39463.618389163)
74-
["obj"]=>
75-
object(MongoDB\Model\BSONDocument)#13 (1) {
76-
["storage":"ArrayObject":private]=>
77-
array(3) {
78-
["_id"]=>
79-
object(MongoDB\BSON\ObjectId)#3 (1) {
80-
["oid"]=>
81-
string(24) "55cba2486c522cafdb059bed"
82-
}
83-
["location"]=>
84-
object(MongoDB\Model\BSONDocument)#12 (1) {
85-
["storage":"ArrayObject":private]=>
86-
array(2) {
87-
["coordinates"]=>
88-
object(MongoDB\Model\BSONArray)#11 (1) {
89-
["storage":"ArrayObject":private]=>
90-
array(2) {
91-
[0]=>
92-
float(-74.1641319)
93-
[1]=>
94-
float(39.6686512)
95-
}
96-
}
97-
["type"]=>
98-
string(5) "Point"
99-
}
100-
}
101-
["name"]=>
102-
string(32) "Soul Food Kitchen Seafood Heaven"
103-
}
104-
}
105-
}
106-
}
107-
[1]=>
108-
object(MongoDB\Model\BSONDocument)#19 (1) {
109-
["storage":"ArrayObject":private]=>
110-
array(2) {
111-
["dis"]=>
112-
float(50686.851650416)
113-
["obj"]=>
114-
object(MongoDB\Model\BSONDocument)#18 (1) {
115-
["storage":"ArrayObject":private]=>
116-
array(3) {
117-
["_id"]=>
118-
object(MongoDB\BSON\ObjectId)#15 (1) {
119-
["oid"]=>
120-
string(24) "55cba2476c522cafdb0544df"
121-
}
122-
["location"]=>
123-
object(MongoDB\Model\BSONDocument)#17 (1) {
124-
["storage":"ArrayObject":private]=>
125-
array(2) {
126-
["coordinates"]=>
127-
object(MongoDB\Model\BSONArray)#16 (1) {
128-
["storage":"ArrayObject":private]=>
129-
array(2) {
130-
[0]=>
131-
float(-74.2566332)
132-
[1]=>
133-
float(40.4109872)
134-
}
135-
}
136-
["type"]=>
137-
string(5) "Point"
138-
}
139-
}
140-
["name"]=>
141-
string(20) "Seguine Bagel Bakery"
142-
}
143-
}
144-
}
145-
}
146-
[2]=>
147-
object(MongoDB\Model\BSONDocument)#24 (1) {
148-
["storage":"ArrayObject":private]=>
149-
array(2) {
150-
["dis"]=>
151-
float(58398.379630263)
152-
["obj"]=>
153-
object(MongoDB\Model\BSONDocument)#23 (1) {
154-
["storage":"ArrayObject":private]=>
155-
array(3) {
156-
["_id"]=>
157-
object(MongoDB\BSON\ObjectId)#20 (1) {
158-
["oid"]=>
159-
string(24) "55cba2476c522cafdb053c92"
160-
}
161-
["location"]=>
162-
object(MongoDB\Model\BSONDocument)#22 (1) {
163-
["storage":"ArrayObject":private]=>
164-
array(2) {
165-
["coordinates"]=>
166-
object(MongoDB\Model\BSONArray)#21 (1) {
167-
["storage":"ArrayObject":private]=>
168-
array(2) {
169-
[0]=>
170-
float(-74.3731727)
171-
[1]=>
172-
float(40.4404759)
173-
}
174-
}
175-
["type"]=>
176-
string(5) "Point"
177-
}
178-
}
179-
["name"]=>
180-
string(17) "Water'S Edge Club"
181-
}
182-
}
183-
}
184-
}
185-
}
186-
}
187-
["stats"]=>
188-
object(MongoDB\Model\BSONDocument)#26 (1) {
189-
["storage":"ArrayObject":private]=>
190-
array(5) {
191-
["nscanned"]=>
192-
int(25139)
193-
["objectsLoaded"]=>
194-
int(25134)
195-
["avgDistance"]=>
196-
float(49516.283223281)
197-
["maxDistance"]=>
198-
float(58398.379630263)
199-
["time"]=>
200-
int(126)
201-
}
202-
}
52+
array(1) {
20353
["ok"]=>
20454
float(1)
20555
}
20656
}
20757

208-
Commands with Custom Read Preference
209-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58+
Commands That Yield Multiple Results
59+
------------------------------------
60+
61+
Some database commands return a cursor with multiple results. The following
62+
example executes :manual:`listCollections </reference/command/listCollections>`,
63+
which returns a cursor containing a result document for each collection in the
64+
``test`` database, and iterates through the results using a ``foreach`` loop.
65+
Note that this example is illustrative; applications would generally use
66+
:phpmethod:`MongoDB\\Database::listCollections()` in practice.
67+
68+
.. code-block:: php
69+
70+
<?php
71+
72+
$database = (new MongoDB\Client)->test;
73+
74+
$cursor = $database->command(['listCollections' => 1]);
75+
76+
foreach ($cursor as $collection) {
77+
echo $collection['name'], "\n";
78+
}
79+
80+
The output might resemble the following:
81+
82+
.. code-block:: none
83+
84+
persons
85+
posts
86+
zips
21087

211-
Some commands, such as :manual:`createUser </reference/command/createUser>`, may
212-
only be executed on a :term:`primary` replica set member or a
213-
:term:`standalone`.
88+
.. note::
21489

215-
The command helper methods in the |php-library|, such as
90+
At the *protocol* level, commands that yield multiple results via a cursor
91+
will return a single result document with the essential ingredients for
92+
constructing the cursor (i.e. the cursor's ID, namespace, and an optional
93+
first batch of results). If the :php:`MongoDB\Driver\Manager::executeCommand()
94+
<mongodb-driver-manager.executecommand>` method in the PHP driver detects
95+
such a response, it will construct an iterable command cursor and return it
96+
instead of the raw result document. If necessary, raw result documents can
97+
still be observed using `command monitoring
98+
<https://www.php.net/manual/en/mongodb.tutorial.apm.php>`_.
99+
100+
Specifying a Custom Read Preference
101+
-----------------------------------
102+
103+
Write commands, such as :manual:`createUser </reference/command/createUser>`,
104+
can only be executed on a writable server (e.g. :term:`primary` replica set
105+
member). Command helper methods in the |php-library|, such as
216106
:phpmethod:`MongoDB\\Database::drop()`, know to apply their own :term:`read
217107
preference` if necessary. However, the :phpmethod:`MongoDB\\Database::command()`
218108
method is a generic method and defaults to the read preference of the Database
219-
object on which it is invoked. To execute commands that require a specific read
220-
preference, specify the read preference in the ``$options`` parameter of the
221-
method.
109+
object on which it is invoked. When necessary, the ``readPreference`` option may
110+
be used to override the default read preference.
222111

223-
The following example adds a user to the ``test`` database and specifies a
224-
custom read preference:
112+
The following example connects to a cluster and specifies ``secondaryPreferred``
113+
as the Client's default read preference. It then specifies a ``primary`` read
114+
preference when executing the ``createUser`` command on the ``test`` database:
225115

226116
.. code-block:: php
227117

228118
<?php
229119

230-
$db = (new MongoDB\Client)->test;
120+
$client = new MongoDB\Client(
121+
'mongodb+srv://cluster0.example.com',
122+
['readPreference' => 'secondaryPreferred']
123+
);
124+
125+
$client->test;
231126

232127
$cursor = $db->command(
233128
[
@@ -236,7 +131,7 @@ custom read preference:
236131
'roles' => ['readWrite'],
237132
],
238133
[
239-
'readPreference' => new MongoDB\Driver\ReadPreference('primaryPreferred'),
134+
'readPreference' => new MongoDB\Driver\ReadPreference('primary'),
240135
]
241136
);
242137

@@ -253,81 +148,3 @@ The output would then resemble:
253148
float(1)
254149
}
255150
}
256-
257-
View Command Results
258-
--------------------
259-
260-
View Single Result Documents
261-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
262-
263-
The :phpmethod:`MongoDB\\Database::command()` method returns a
264-
:php:`MongoDB\\Driver\\Cursor <mongodb-driver-cursor>` object.
265-
266-
Many MongoDB commands return their responses as a single document. To read the
267-
command response, you may either iterate on the cursor and access the first
268-
document, or access the first result in the array, as in the following:
269-
270-
.. code-block:: php
271-
272-
<?php
273-
274-
$database = (new MongoDB\Client)->test;
275-
276-
$cursor = $database->command(['ping' => 1]);
277-
278-
var_dump($cursor->toArray()[0]);
279-
280-
The output would then resemble:
281-
282-
.. code-block:: none
283-
284-
object(MongoDB\Model\BSONDocument)#2 (1) {
285-
["storage":"ArrayObject":private]=>
286-
array(1) {
287-
["ok"]=>
288-
float(1)
289-
}
290-
}
291-
292-
Iterate Results from a Cursor
293-
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
294-
295-
Some commands, such as :manual:`listCollections
296-
</reference/command/listCollections>`, return their results via an iterable
297-
cursor. To view the results, iterate through the cursor.
298-
299-
The following example lists the collections in the ``test`` database by
300-
iterating through the cursor returned by the ``listCollections`` command using a
301-
``foreach`` loop:
302-
303-
.. code-block:: php
304-
305-
<?php
306-
307-
$database = (new MongoDB\Client)->test;
308-
309-
$cursor = $database->command(['listCollections' => 1]);
310-
311-
foreach ($cursor as $collection) {
312-
echo $collection['name'], "\n";
313-
}
314-
315-
The output would then be a list of the values for the ``name`` key, for
316-
instance:
317-
318-
.. code-block:: none
319-
320-
persons
321-
posts
322-
zips
323-
324-
.. note::
325-
326-
At the *protocol* level, commands that support a cursor return a single
327-
result document with the essential ingredients for constructing the command
328-
cursor (i.e. the cursor's ID, namespace, and the first batch of results). In
329-
the PHP driver implementation, the
330-
:php:`MongoDB\Driver\Manager::executeCommand()
331-
<mongodb-driver-manager.executecommand>` method detects such a result and
332-
constructs the iterable command cursor, which is returned rather than the
333-
base result document.

0 commit comments

Comments
 (0)