1
|
|
|
<?php |
2
|
|
|
|
3
|
|
|
declare(strict_types=1); |
4
|
|
|
|
5
|
|
|
namespace Doctrine\ODM\MongoDB\Aggregation; |
6
|
|
|
|
7
|
|
|
use Doctrine\ODM\MongoDB\Iterator\Iterator; |
8
|
|
|
use GeoJson\Geometry\Point; |
9
|
|
|
|
10
|
|
|
/** |
11
|
|
|
* Fluent interface for building aggregation pipelines. |
12
|
|
|
* |
13
|
|
|
* @internal |
14
|
|
|
*/ |
15
|
|
|
abstract class Stage |
16
|
|
|
{ |
17
|
|
|
/** @var Builder */ |
18
|
|
|
protected $builder; |
19
|
|
|
|
20
|
268 |
|
public function __construct(Builder $builder) |
21
|
|
|
{ |
22
|
268 |
|
$this->builder = $builder; |
23
|
268 |
|
} |
24
|
|
|
|
25
|
|
|
/** |
26
|
|
|
* Assembles the aggregation stage |
27
|
|
|
*/ |
28
|
|
|
abstract public function getExpression() : array; |
29
|
|
|
|
30
|
|
|
/** |
31
|
|
|
* Executes the aggregation pipeline |
32
|
|
|
*/ |
33
|
2 |
|
public function execute(array $options = []) : Iterator |
34
|
|
|
{ |
35
|
2 |
|
return $this->builder->execute($options); |
36
|
|
|
} |
37
|
|
|
|
38
|
|
|
/** |
39
|
|
|
* Adds new fields to documents. $addFields outputs documents that contain |
40
|
|
|
* all existing fields from the input documents and newly added fields. |
41
|
|
|
* |
42
|
|
|
* The $addFields stage is equivalent to a $project stage that explicitly |
43
|
|
|
* specifies all existing fields in the input documents and adds the new |
44
|
|
|
* fields. |
45
|
|
|
* |
46
|
|
|
* @see https://docs.mongodb.com/manual/reference/operator/aggregation/addFields/ |
47
|
|
|
*/ |
48
|
|
|
public function addFields() : Stage\AddFields |
49
|
|
|
{ |
50
|
|
|
return $this->builder->addFields(); |
51
|
|
|
} |
52
|
|
|
|
53
|
|
|
/** |
54
|
|
|
* Categorizes incoming documents into groups, called buckets, based on a |
55
|
|
|
* specified expression and bucket boundaries. |
56
|
|
|
* |
57
|
|
|
* Each bucket is represented as a document in the output. The document for |
58
|
|
|
* each bucket contains an _id field, whose value specifies the inclusive |
59
|
|
|
* lower bound of the bucket and a count field that contains the number of |
60
|
|
|
* documents in the bucket. The count field is included by default when the |
61
|
|
|
* output is not specified. |
62
|
|
|
* |
63
|
|
|
* @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucket/ |
64
|
|
|
*/ |
65
|
|
|
public function bucket() : Stage\Bucket |
66
|
|
|
{ |
67
|
|
|
return $this->builder->bucket(); |
68
|
|
|
} |
69
|
|
|
|
70
|
|
|
/** |
71
|
|
|
* Categorizes incoming documents into a specific number of groups, called |
72
|
|
|
* buckets, based on a specified expression. |
73
|
|
|
* |
74
|
|
|
* Bucket boundaries are automatically determined in an attempt to evenly |
75
|
|
|
* distribute the documents into the specified number of buckets. Each |
76
|
|
|
* bucket is represented as a document in the output. The document for each |
77
|
|
|
* bucket contains an _id field, whose value specifies the inclusive lower |
78
|
|
|
* bound and the exclusive upper bound for the bucket, and a count field |
79
|
|
|
* that contains the number of documents in the bucket. The count field is |
80
|
|
|
* included by default when the output is not specified. |
81
|
|
|
* |
82
|
|
|
* @see https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/ |
83
|
|
|
*/ |
84
|
|
|
public function bucketAuto() : Stage\BucketAuto |
85
|
|
|
{ |
86
|
|
|
return $this->builder->bucketAuto(); |
87
|
|
|
} |
88
|
|
|
|
89
|
|
|
/** |
90
|
|
|
* Returns statistics regarding a collection or view. |
91
|
|
|
* |
92
|
|
|
* $collStats must be the first stage in an aggregation pipeline, or else |
93
|
|
|
* the pipeline returns an error. |
94
|
|
|
* |
95
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/geoNear/ |
96
|
|
|
*/ |
97
|
|
|
public function collStats() : Stage\CollStats |
98
|
|
|
{ |
99
|
|
|
return $this->builder->collStats(); |
100
|
|
|
} |
101
|
|
|
|
102
|
|
|
/** |
103
|
|
|
* Returns a document that contains a count of the number of documents input |
104
|
|
|
* to the stage. |
105
|
|
|
* |
106
|
|
|
* @see https://docs.mongodb.com/manual/reference/operator/aggregation/count/ |
107
|
|
|
*/ |
108
|
|
|
public function count(string $fieldName) : Stage\Count |
109
|
|
|
{ |
110
|
|
|
return $this->builder->count($fieldName); |
111
|
|
|
} |
112
|
|
|
|
113
|
|
|
/** |
114
|
|
|
* Processes multiple aggregation pipelines within a single stage on the |
115
|
|
|
* same set of input documents. |
116
|
|
|
* |
117
|
|
|
* Each sub-pipeline has its own field in the output document where its |
118
|
|
|
* results are stored as an array of documents. |
119
|
|
|
*/ |
120
|
|
|
public function facet() : Stage\Facet |
121
|
|
|
{ |
122
|
|
|
return $this->builder->facet(); |
123
|
|
|
} |
124
|
|
|
|
125
|
|
|
/** |
126
|
|
|
* Outputs documents in order of nearest to farthest from a specified point. |
127
|
|
|
* You can only use this as the first stage of a pipeline. |
128
|
|
|
* |
129
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/geoNear/ |
130
|
|
|
* |
131
|
|
|
* @param float|array|Point $x |
132
|
|
|
* @param float $y |
133
|
|
|
*/ |
134
|
|
|
public function geoNear($x, $y = null) : Stage\GeoNear |
135
|
|
|
{ |
136
|
|
|
return $this->builder->geoNear($x, $y); |
137
|
|
|
} |
138
|
|
|
|
139
|
|
|
/** |
140
|
|
|
* Returns the assembled aggregation pipeline |
141
|
|
|
*/ |
142
|
1 |
|
public function getPipeline() : array |
143
|
|
|
{ |
144
|
1 |
|
return $this->builder->getPipeline(); |
145
|
|
|
} |
146
|
|
|
|
147
|
|
|
/** |
148
|
|
|
* Performs a recursive search on a collection, with options for restricting |
149
|
|
|
* the search by recursion depth and query filter. |
150
|
|
|
* |
151
|
|
|
* @see https://docs.mongodb.org/manual/reference/operator/aggregation/graphLookup/ |
152
|
|
|
* |
153
|
|
|
* @param string $from Target collection for the $graphLookup operation to |
154
|
|
|
* search, recursively matching the connectFromField to the connectToField. |
155
|
|
|
*/ |
156
|
|
|
public function graphLookup(string $from) : Stage\GraphLookup |
157
|
|
|
{ |
158
|
|
|
return $this->builder->graphLookup($from); |
159
|
|
|
} |
160
|
|
|
|
161
|
|
|
/** |
162
|
|
|
* Groups documents by some specified expression and outputs to the next |
163
|
|
|
* stage a document for each distinct grouping. |
164
|
|
|
* |
165
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/group/ |
166
|
|
|
*/ |
167
|
2 |
|
public function group() : Stage\Group |
168
|
|
|
{ |
169
|
2 |
|
return $this->builder->group(); |
170
|
|
|
} |
171
|
|
|
|
172
|
|
|
/** |
173
|
|
|
* Returns statistics regarding the use of each index for the collection. |
174
|
|
|
* |
175
|
|
|
* @see https://docs.mongodb.org/manual/reference/operator/aggregation/indexStats/ |
176
|
|
|
*/ |
177
|
|
|
public function indexStats() : Stage\IndexStats |
178
|
|
|
{ |
179
|
|
|
return $this->builder->indexStats(); |
180
|
|
|
} |
181
|
|
|
|
182
|
|
|
/** |
183
|
|
|
* Limits the number of documents passed to the next stage in the pipeline. |
184
|
|
|
* |
185
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/limit/ |
186
|
|
|
* |
187
|
|
|
* @return Stage\Limit |
188
|
|
|
*/ |
189
|
1 |
|
public function limit(int $limit) |
190
|
|
|
{ |
191
|
1 |
|
return $this->builder->limit($limit); |
192
|
|
|
} |
193
|
|
|
|
194
|
|
|
/** |
195
|
|
|
* Performs a left outer join to an unsharded collection in the same |
196
|
|
|
* database to filter in documents from the “joined” collection for |
197
|
|
|
* processing. |
198
|
|
|
* |
199
|
|
|
* @see https://docs.mongodb.org/manual/reference/operator/aggregation/lookup/ |
200
|
|
|
*/ |
201
|
7 |
|
public function lookup(string $from) : Stage\Lookup |
202
|
|
|
{ |
203
|
7 |
|
return $this->builder->lookup($from); |
204
|
|
|
} |
205
|
|
|
|
206
|
|
|
/** |
207
|
|
|
* Filters the documents to pass only the documents that match the specified |
208
|
|
|
* condition(s) to the next pipeline stage. |
209
|
|
|
* |
210
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/match/ |
211
|
|
|
*/ |
212
|
1 |
|
public function match() : Stage\Match |
213
|
|
|
{ |
214
|
1 |
|
return $this->builder->match(); |
215
|
|
|
} |
216
|
|
|
|
217
|
|
|
/** |
218
|
|
|
* Takes the documents returned by the aggregation pipeline and writes them |
219
|
|
|
* to a specified collection. This must be the last stage in the pipeline. |
220
|
|
|
* |
221
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/out/ |
222
|
|
|
*/ |
223
|
1 |
|
public function out(string $collection) : Stage\Out |
224
|
|
|
{ |
225
|
1 |
|
return $this->builder->out($collection); |
226
|
|
|
} |
227
|
|
|
|
228
|
|
|
/** |
229
|
|
|
* Passes along the documents with only the specified fields to the next |
230
|
|
|
* stage in the pipeline. The specified fields can be existing fields from |
231
|
|
|
* the input documents or newly computed fields. |
232
|
|
|
* |
233
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/project/ |
234
|
|
|
*/ |
235
|
2 |
|
public function project() : Stage\Project |
236
|
|
|
{ |
237
|
2 |
|
return $this->builder->project(); |
238
|
|
|
} |
239
|
|
|
|
240
|
|
|
/** |
241
|
|
|
* Restricts the contents of the documents based on information stored in |
242
|
|
|
* the documents themselves. |
243
|
|
|
* |
244
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/redact/ |
245
|
|
|
*/ |
246
|
1 |
|
public function redact() : Stage\Redact |
247
|
|
|
{ |
248
|
1 |
|
return $this->builder->redact(); |
249
|
|
|
} |
250
|
|
|
|
251
|
|
|
/** |
252
|
|
|
* Promotes a specified document to the top level and replaces all other |
253
|
|
|
* fields. |
254
|
|
|
* |
255
|
|
|
* The operation replaces all existing fields in the input document, |
256
|
|
|
* including the _id field. You can promote an existing embedded document to |
257
|
|
|
* the top level, or create a new document for promotion. |
258
|
|
|
* |
259
|
|
|
* @param string|array|null $expression Optional. A replacement expression that |
260
|
|
|
* resolves to a document. |
261
|
|
|
*/ |
262
|
2 |
|
public function replaceRoot($expression = null) : Stage\ReplaceRoot |
263
|
|
|
{ |
264
|
2 |
|
return $this->builder->replaceRoot($expression); |
265
|
|
|
} |
266
|
|
|
|
267
|
|
|
/** |
268
|
|
|
* Controls if resulting iterator should be wrapped with CachingIterator. |
269
|
|
|
*/ |
270
|
1 |
|
public function rewindable(bool $rewindable = true) : self |
271
|
|
|
{ |
272
|
1 |
|
$this->builder->rewindable($rewindable); |
273
|
|
|
|
274
|
1 |
|
return $this; |
275
|
|
|
} |
276
|
|
|
|
277
|
|
|
/** |
278
|
|
|
* Randomly selects the specified number of documents from its input. |
279
|
|
|
* |
280
|
|
|
* @see https://docs.mongodb.org/manual/reference/operator/aggregation/sample/ |
281
|
|
|
*/ |
282
|
1 |
|
public function sample(int $size) : Stage\Sample |
283
|
|
|
{ |
284
|
1 |
|
return $this->builder->sample($size); |
285
|
|
|
} |
286
|
|
|
|
287
|
|
|
/** |
288
|
|
|
* Skips over the specified number of documents that pass into the stage and |
289
|
|
|
* passes the remaining documents to the next stage in the pipeline. |
290
|
|
|
* |
291
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/skip/ |
292
|
|
|
*/ |
293
|
1 |
|
public function skip(int $skip) : Stage\Skip |
294
|
|
|
{ |
295
|
1 |
|
return $this->builder->skip($skip); |
296
|
|
|
} |
297
|
|
|
|
298
|
|
|
/** |
299
|
|
|
* Groups incoming documents based on the value of a specified expression, |
300
|
|
|
* then computes the count of documents in each distinct group. |
301
|
|
|
* |
302
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/sortByCount/ |
303
|
|
|
*/ |
304
|
|
|
public function sortByCount(string $expression) : Stage\SortByCount |
305
|
|
|
{ |
306
|
|
|
return $this->builder->sortByCount($expression); |
307
|
|
|
} |
308
|
|
|
|
309
|
|
|
/** |
310
|
|
|
* Sorts all input documents and returns them to the pipeline in sorted order. |
311
|
|
|
* |
312
|
|
|
* If sorting by multiple fields, the first argument should be an array of |
313
|
|
|
* field name (key) and order (value) pairs. |
314
|
|
|
* |
315
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/sort/ |
316
|
|
|
* |
317
|
|
|
* @param array|string $fieldName Field name or array of field/order pairs |
318
|
|
|
* @param int|string $order Field order (if one field is specified) |
319
|
|
|
*/ |
320
|
3 |
|
public function sort($fieldName, $order = null) : Stage\Sort |
321
|
|
|
{ |
322
|
3 |
|
return $this->builder->sort($fieldName, $order); |
323
|
|
|
} |
324
|
|
|
|
325
|
|
|
/** |
326
|
|
|
* Deconstructs an array field from the input documents to output a document |
327
|
|
|
* for each element. Each output document is the input document with the |
328
|
|
|
* value of the array field replaced by the element. |
329
|
|
|
* |
330
|
|
|
* @see http://docs.mongodb.org/manual/reference/operator/aggregation/unwind/ |
331
|
|
|
*/ |
332
|
3 |
|
public function unwind(string $fieldName) : Stage\Unwind |
333
|
|
|
{ |
334
|
3 |
|
return $this->builder->unwind($fieldName); |
335
|
|
|
} |
336
|
|
|
|
337
|
|
|
/** |
338
|
|
|
* Allows adding an arbitrary stage to the pipeline |
339
|
|
|
* |
340
|
|
|
* @return Stage The method returns the stage given as an argument |
341
|
|
|
*/ |
342
|
1 |
|
public function addStage(Stage $stage) : Stage |
343
|
|
|
{ |
344
|
1 |
|
return $this->builder->addStage($stage); |
345
|
|
|
} |
346
|
|
|
} |
347
|
|
|
|