Support for
$densify
,
$fill
,
$merge
,
$replaceWith
,
$search
,
$set
,
$setWindowFields
,
$unionWith
, and
$unset
was added in Doctrine MongoDB ODM 2.6. Please consult the MongoDB
documentation to ensure that the pipeline stage is available in the MongoDB
version you are using.
Categorizes incoming documents into groups, called buckets, based on a specified
expression and bucket boundaries.
Each bucket is represented as a document in the output. The document for each
bucket contains an _id field, whose value specifies the inclusive lower bound of
the bucket and a count field that contains the number of documents in the bucket.
The count field is included by default when the output is not specified.
$bucket only produces output documents for buckets that contain at least one
input document.
Similar to $bucket, except that boundaries are automatically determined in
an attempt to evenly distribute the documents into the specified number of
buckets.
Creates new documents in a sequence of documents where certain values in a
field are missing. You can use $densify to fill gaps in time series data,
add missing values between groups of data, or to populate your data with a
specified range of values. Taking the partition example from the
$densify documentation,
this is how you would create the pipeline from the example with the aggregation
builder:
Processes multiple aggregation pipelines within a single stage on the same set
of input documents. Each sub-pipeline has its own field in the output document
where its results are stored as an array of documents.
The $fill stage populates null and missing field values within documents.
You can use $fill to populate missing data points in a sequence based on
surrounding values, or with a fixed value.
For each field in the output, you can use linear to use linear interpolation
based on the surrounding values, locf to carry forward the last observed
value, or value to specify an expression that returns the value for the field:
<?php
$builder = $this->dm->createAggregationBuilder(\Documents\City::class);
$builder
->geoNear(120, 40)
->spherical(true)
->distanceField('distance')
// Convert radians to kilometers (use 3963.192 for miles)
->distanceMultiplier(6378.137);
The $geoNear stage must be the first stage in the pipeline and the
collection must contain a single geospatial index. You must include the
distanceField option for the stage to work.
Performs a recursive search on a collection, with options for restricting the
search by recursion depth and query filter. The $graphLookup stage can be
used to resolve association graphs and flatten them into a single list.
The target document of the reference used in connectFromField must be
the very same document. The aggregation builder will throw an exception if
you try to resolve a different document.
Due to a limitation in MongoDB, the $graphLookup stage can not be used
with references that are stored as DBRef. To use references in a
$graphLookup stage, store the reference as ID or ref. This is
explained in the Reference mapping chapter.
The $indexStats stage returns statistics regarding the use of each index for
the collection. More information can be found in the official Documentation
In MongoDB 3.2, the resulting array will be empty for a one-to-many relationship,
you need to unwind your field at first and use a group stage afterwards.
The resulting array will contain all matched item documents in an array. This has
to be considered when looking up one-to-one relationships:
MongoDB will always return an array, even if the lookup only returned a single
document. Thus, when looking up one-to-one references the result must be flattened
using the $unwind operator.
Looking up a reference nested in an embedded document (like ->lookup('embedDoc.refDocs'))
is not supported. You'll need to make your lookup as if your Reference was not mapped
See below for more.
Due to a limitation in MongoDB, the $lookup stage can not be used with
references that are stored as DBRef. To use references in a $lookup
stage, store the reference as ID or ref. This is explained in the
Reference mapping chapter.
You can also configure your lookup manually if you don't have it mapped in your
document:
The $merge stage is used to write the results of an aggregation pipeline to
a collection. Unlike the $out stage, this stage does not replace the entire
output collection, but lets you define how to handle conflicts or missing data
in the output collection. $merge must be the last stage in an aggregation
pipeline.
The following pipeline uses the $merge pipeline stage to aggregate orders
that were created after the last aggregation run (tracked separately in the
$lastAggregateRunAt variable) and updates the monthlyOrderStats
collection to account for latest data.
The on builder method tells the merge stage which fields to use to match
documents in the output collection. The output collection needs to have a unique
index on the fields specified in the on method. The whenMatched and
whenNotMatched methods define how to handle conflicts or missing data in the
output collection. For more information on the available options, see the
MongoDB documentation.
The $out stage is used to store the result of the aggregation pipeline in a
collection instead of returning an iterable cursor of results. This must be the
last stage in an aggregation pipeline.
If the collection specified by the $out operation already exists, then upon
completion of the aggregation, the existing collection is atomically replaced.
Any indexes that existed on the collection are left intact. If the aggregation
fails, the $out operation does not remove the data from an existing
collection.
The aggregation pipeline will fail to complete if the result would violate
any unique index constraints, including those on the _id field.
The redact stage can be used to restrict the contents of the documents based on
information stored in the documents themselves. You can read more about the
$redact stage in the MongoDB documentation.
The following example taken from the official documentation checks the level
field on all document levels and evaluates it to grant or deny access:
Promotes a specified document to the top level and replaces all other fields.
The operation replaces all existing fields in the input document, including the
_id field. You can promote an existing embedded document to the top level,
or create a new document for promotion.
The sample stage can be used to randomly select a subset of documents in the
aggregation pipeline. It behaves like the $limit stage, but instead of
returning the first n documents it returns n random documents.
The $search stage performs a full-text search on the specified field or
fields which must be covered by an Atlas Search index. This stage is only
available when using MongoDB Atlas. $search must be the first stage in the
aggregation pipeline.
The following example documents basic usage of the $search stage. Due to the
number of available operators, please refer to the
MongoDB documentation
for a reference of all available operators.
The $setWindowFields performs operations on a specified span of documents in
a collection and returns the results based on the chosen window operator. For
example, $setWindowFields can be used to calculate the difference in a value
between two documents in a collection.
The following example uses the $setWindowFields stage to obtain a cumulative
sales quantity for each year:
The $sort, $limit and $skip stages behave like the corresponding
query options, allowing you to control the order and subset of results returned
by the aggregation pipeline.
Groups incoming documents based on the value of a specified expression, then
computes the count of documents in each distinct group.
Each output document contains two fields: an _id field containing the distinct
grouping value, and a count field containing the number of documents belonging
to that grouping or category.
The documents are sorted by count in descending order.
The example above is equivalent to the following pipeline:
$unionWith combines the results of two or more pipelines into a single
result set. The stage outputs the combined result set (including duplicates) to
the next stage.
<?php// Create a pipeline to apply within the union
$unionBuilder = $dm->createAggregationBuilder(\Documents\Warehouse::class);
$unionBuilder
->project()
->excludeFields(['_id'])
->includeFields(['location']);
$builder = $dm->createAggregationBuilder(\Documents\Supplier::class);
$builder
->project()
->excludeFields(['_id'])
->includeFields(['location'])
->unionWith(\Documents\Warehouse::class)
// Directly filter documents from the unioned collection
->pipeline($unionBuilder)