Skip to content

Commit 4e15ad1

Browse files
kvwalkerkvwalker
committed
PHPLIB-332: Create explain helper on Collection class
1 parent 2e865c4 commit 4e15ad1

File tree

4 files changed

+312
-0
lines changed

4 files changed

+312
-0
lines changed

‎source/includes/apiargs-MongoDBCollection-method-explain-option.yaml

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
source:
2+
file: apiargs-MongoDBCollection-common-option.yaml
3+
ref: readPreference
4+
---
5+
source:
6+
file: apiargs-MongoDBCollection-common-option.yaml
7+
ref: typeMap
8+
post: |
9+
This will be used for the returned command result document.
10+
---
11+
arg_name: option
12+
name: verbosity
13+
type: string
14+
description: |
15+
The verbosity level at which to run the command. See the :manual:`explain
16+
</reference/command/explain>` command for more information.
17+
interface: phpmethod
18+
operation: ~
19+
optional: true
20+
...

‎source/includes/apiargs-MongoDBCollection-method-explain-param.yaml

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
arg_name: param
2+
name: $explainable
3+
type: :phpclass:`MongoDB\\Operation\\Explainable`
4+
description: |
5+
The command to explain.
6+
interface: phpmethod
7+
operation: ~
8+
optional: false
9+
---
10+
source:
11+
file: apiargs-common-param.yaml
12+
ref: $options
13+
...

‎source/reference/class/MongoDBCollection.txt

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,7 @@ Methods
7171
/reference/method/MongoDBCollection-drop
7272
/reference/method/MongoDBCollection-dropIndex
7373
/reference/method/MongoDBCollection-dropIndexes
74+
/reference/method/MongoDBCollection-explain
7475
/reference/method/MongoDBCollection-find
7576
/reference/method/MongoDBCollection-findOne
7677
/reference/method/MongoDBCollection-findOneAndDelete

‎source/reference/method/MongoDBCollection-explain.txt

Lines changed: 278 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,278 @@
1+
==============================
2+
MongoDB\\Collection::explain()
3+
==============================
4+
5+
.. versionadded:: 1.4
6+
7+
.. default-domain:: mongodb
8+
9+
.. contents:: On this page
10+
:local:
11+
:backlinks: none
12+
:depth: 1
13+
:class: singlecol
14+
15+
Definition
16+
----------
17+
18+
.. phpmethod:: MongoDB\\Collection::explain()
19+
20+
Explain the given command.
21+
22+
.. code-block:: php
23+
24+
function explain(MongoDB\\Operation\\Explainable $explainable, array $options = []): array|object
25+
26+
This method has the following parameters:
27+
28+
.. include:: /includes/apiargs/MongoDBCollection-method-explain-param.rst
29+
30+
The ``$options`` parameter supports the following options:
31+
32+
.. include:: /includes/apiargs/MongoDBCollection-method-explain-option.rst
33+
34+
Return Values
35+
-------------
36+
37+
An array or object with the result document of the :manual:`explain
38+
</reference/command/explain>` command. The return type will depend on the
39+
``typeMap`` option.
40+
41+
Errors/Exceptions
42+
-----------------
43+
44+
.. include:: /includes/extracts/error-unsupportedexception.rst
45+
.. include:: /includes/extracts/error-invalidargumentexception.rst
46+
.. include:: /includes/extracts/error-driver-runtimeexception.rst
47+
48+
Explainable Commands
49+
--------------------
50+
51+
Explainable commands include, but are not limited to:
52+
53+
- :phpclass:`MongoDB\\Operation\\Count`
54+
- :phpclass:`MongoDB\\Operation\\DeleteMany`
55+
- :phpclass:`MongoDB\\Operation\\DeleteOne`
56+
- :phpclass:`MongoDB\\Operation\\Distinct`
57+
- :phpclass:`MongoDB\\Operation\\Find`
58+
- :phpclass:`MongoDB\\Operation\\FindOne`
59+
- :phpclass:`MongoDB\\Operation\\FindOneAndDelete`
60+
- :phpclass:`MongoDB\\Operation\\FindOneAndReplace`
61+
- :phpclass:`MongoDB\\Operation\\FindOneAndUpdate`
62+
- :phpclass:`MongoDB\\Operation\\UpdateMany`
63+
- :phpclass:`MongoDB\\Operation\\UpdateOne`
64+
65+
Examples
66+
--------
67+
68+
This example explains a count command.
69+
70+
.. code-block:: php
71+
72+
<?php
73+
74+
$collection = (new MongoDB\Client)->test->restaurants;
75+
76+
$count = new MongoDB\Operation\Count(
77+
$collection->getDatabaseName(),
78+
$collection->getCollectionName(),
79+
['cuisine' => 'Italian']
80+
);
81+
82+
$result = $collection->explain($count);
83+
84+
var_dump($result);
85+
86+
The output would then resemble::
87+
88+
object(MongoDB\Model\BSONDocument)#29 (1) {
89+
["storage":"ArrayObject":private]=>
90+
array(4) {
91+
["queryPlanner"]=>
92+
object(MongoDB\Model\BSONDocument)#21 (1) {
93+
["storage":"ArrayObject":private]=>
94+
array(6) {
95+
["plannerVersion"]=>
96+
int(1)
97+
["namespace"]=>
98+
string(16) "test.restaurants"
99+
["indexFilterSet"]=>
100+
bool(false)
101+
["parsedQuery"]=>
102+
object(MongoDB\Model\BSONDocument)#15 (1) {
103+
["storage":"ArrayObject":private]=>
104+
array(1) {
105+
["cuisine"]=>
106+
object(MongoDB\Model\BSONDocument)#14 (1) {
107+
["storage":"ArrayObject":private]=>
108+
array(1) {
109+
["$eq"]=>
110+
string(7) "Italian"
111+
}
112+
}
113+
}
114+
}
115+
["winningPlan"]=>
116+
object(MongoDB\Model\BSONDocument)#19 (1) {
117+
["storage":"ArrayObject":private]=>
118+
array(2) {
119+
["stage"]=>
120+
string(5) "COUNT"
121+
["inputStage"]=>
122+
object(MongoDB\Model\BSONDocument)#18 (1) {
123+
["storage":"ArrayObject":private]=>
124+
array(3) {
125+
["stage"]=>
126+
string(8) "COLLSCAN"
127+
["filter"]=>
128+
object(MongoDB\Model\BSONDocument)#17 (1) {
129+
["storage":"ArrayObject":private]=>
130+
array(1) {
131+
["cuisine"]=>
132+
object(MongoDB\Model\BSONDocument)#16 (1) {
133+
["storage":"ArrayObject":private]=>
134+
array(1) {
135+
["$eq"]=>
136+
string(7) "Italian"
137+
}
138+
}
139+
}
140+
}
141+
["direction"]=>
142+
string(7) "forward"
143+
}
144+
}
145+
}
146+
}
147+
["rejectedPlans"]=>
148+
object(MongoDB\Model\BSONArray)#20 (1) {
149+
["storage":"ArrayObject":private]=>
150+
array(0) {
151+
}
152+
}
153+
}
154+
}
155+
["executionStats"]=>
156+
object(MongoDB\Model\BSONDocument)#27 (1) {
157+
["storage":"ArrayObject":private]=>
158+
array(7) {
159+
["executionSuccess"]=>
160+
bool(true)
161+
["nReturned"]=>
162+
int(0)
163+
["executionTimeMillis"]=>
164+
int(24)
165+
["totalKeysExamined"]=>
166+
int(0)
167+
["totalDocsExamined"]=>
168+
int(25359)
169+
["executionStages"]=>
170+
object(MongoDB\Model\BSONDocument)#25 (1) {
171+
["storage":"ArrayObject":private]=>
172+
array(14) {
173+
["stage"]=>
174+
string(5) "COUNT"
175+
["nReturned"]=>
176+
int(0)
177+
["executionTimeMillisEstimate"]=>
178+
int(20)
179+
["works"]=>
180+
int(25361)
181+
["advanced"]=>
182+
int(0)
183+
["needTime"]=>
184+
int(25360)
185+
["needYield"]=>
186+
int(0)
187+
["saveState"]=>
188+
int(198)
189+
["restoreState"]=>
190+
int(198)
191+
["isEOF"]=>
192+
int(1)
193+
["invalidates"]=>
194+
int(0)
195+
["nCounted"]=>
196+
int(1069)
197+
["nSkipped"]=>
198+
int(0)
199+
["inputStage"]=>
200+
object(MongoDB\Model\BSONDocument)#24 (1) {
201+
["storage":"ArrayObject":private]=>
202+
array(14) {
203+
["stage"]=>
204+
string(8) "COLLSCAN"
205+
["filter"]=>
206+
object(MongoDB\Model\BSONDocument)#23 (1) {
207+
["storage":"ArrayObject":private]=>
208+
array(1) {
209+
["cuisine"]=>
210+
object(MongoDB\Model\BSONDocument)#22 (1) {
211+
["storage":"ArrayObject":private]=>
212+
array(1) {
213+
["$eq"]=>
214+
string(7) "Italian"
215+
}
216+
}
217+
}
218+
}
219+
["nReturned"]=>
220+
int(1069)
221+
["executionTimeMillisEstimate"]=>
222+
int(20)
223+
["works"]=>
224+
int(25361)
225+
["advanced"]=>
226+
int(1069)
227+
["needTime"]=>
228+
int(24291)
229+
["needYield"]=>
230+
int(0)
231+
["saveState"]=>
232+
int(198)
233+
["restoreState"]=>
234+
int(198)
235+
["isEOF"]=>
236+
int(1)
237+
["invalidates"]=>
238+
int(0)
239+
["direction"]=>
240+
string(7) "forward"
241+
["docsExamined"]=>
242+
int(25359)
243+
}
244+
}
245+
}
246+
}
247+
["allPlansExecution"]=>
248+
object(MongoDB\Model\BSONArray)#26 (1) {
249+
["storage":"ArrayObject":private]=>
250+
array(0) {
251+
}
252+
}
253+
}
254+
}
255+
["serverInfo"]=>
256+
object(MongoDB\Model\BSONDocument)#28 (1) {
257+
["storage":"ArrayObject":private]=>
258+
array(4) {
259+
["host"]=>
260+
string(9) "localhost"
261+
["port"]=>
262+
int(27017)
263+
["version"]=>
264+
string(5) "3.6.1"
265+
["gitVersion"]=>
266+
string(40) "025d4f4fe61efd1fb6f0005be20cb45a004093d1"
267+
}
268+
}
269+
["ok"]=>
270+
float(1)
271+
}
272+
}
273+
274+
See Also
275+
--------
276+
277+
- :manual:`explain </reference/command/explain>` command reference in the MongoDB
278+
manual

0 commit comments

Comments
 (0)