class Builder (View source)

Fluent interface for building aggregation pipelines.

Methods

__construct(Collection $collection)

Create a new aggregation builder.

addFields()

Adds new fields to documents. $addFields outputs documents that contain all existing fields from the input documents and newly added fields.

bucket()

Categorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries.

bucketAuto()

Categorizes incoming documents into a specific number of groups, called buckets, based on a specified expression.

collStats()

Returns statistics regarding a collection or view.

count($fieldName)

Returns a document that contains a count of the number of documents input to the stage.

expr()

No description

execute(array $options = [])

Executes the aggregation pipeline

facet()

Processes multiple aggregation pipelines within a single stage on the same set of input documents.

geoNear(float|array|Point $x, float $y = null)

Outputs documents in order of nearest to farthest from a specified point.

getStage(integer $index)

Returns a certain stage from the pipeline

array
getPipeline()

Returns the assembled aggregation pipeline

graphLookup(string $from)

Performs a recursive search on a collection, with options for restricting the search by recursion depth and query filter.

group()

Groups documents by some specified expression and outputs to the next stage a document for each distinct grouping.

indexStats()

Returns statistics regarding the use of each index for the collection.

limit(integer $limit)

Limits the number of documents passed to the next stage in the pipeline.

lookup(string $from)

Performs a left outer join to an unsharded collection in the same database to filter in documents from the “joined” collection for processing.

match()

Filters the documents to pass only the documents that match the specified condition(s) to the next pipeline stage.

Out
out(string $collection)

Takes the documents returned by the aggregation pipeline and writes them to a specified collection. This must be the last stage in the pipeline.

project()

Passes along the documents with only the specified fields to the next stage in the pipeline. The specified fields can be existing fields from the input documents or newly computed fields.

matchExpr()

Returns a query expression to be used in match stages

redact()

Restricts the contents of the documents based on information stored in the documents themselves.

replaceRoot(string|null $expression = null)

Promotes a specified document to the top level and replaces all other fields.

sample(integer $size)

Randomly selects the specified number of documents from its input.

skip(integer $skip)

Skips over the specified number of documents that pass into the stage and passes the remaining documents to the next stage in the pipeline.

sort(array|string $fieldName, integer|string $order = null)

Sorts all input documents and returns them to the pipeline in sorted order.

sortByCount(string $expression)

Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group.

unwind(string $fieldName)

Deconstructs an array field from the input documents to output a document for each element. Each output document is the input document with the value of the array field replaced by the element.

addStage(Stage $stage)

No description

Details

__construct(Collection $collection)

Create a new aggregation builder.

Parameters

Collection $collection

AddFields addFields()

Adds new fields to documents. $addFields outputs documents that contain all existing fields from the input documents and newly added fields.

The $addFields stage is equivalent to a $project stage that explicitly specifies all existing fields in the input documents and adds the new fields.

If the name of the new field is the same as an existing field name (including _id), $addFields overwrites the existing value of that field with the value of the specified expression.

Bucket bucket()

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.

BucketAuto bucketAuto()

Categorizes incoming documents into a specific number of groups, called buckets, based on a specified expression.

Bucket boundaries are automatically determined in an attempt to evenly distribute the documents into the specified number of buckets. 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 and the exclusive upper bound for 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.

CollStats collStats()

Returns statistics regarding a collection or view.

$collStats must be the first stage in an aggregation pipeline, or else the pipeline returns an error.

Count count($fieldName)

Returns a document that contains a count of the number of documents input to the stage.

Expr expr()

Return Value

Expr

Iterator execute(array $options = [])

Executes the aggregation pipeline

Parameters

array $options

Return Value

Iterator

Facet facet()

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.

Return Value

Facet

GeoNear geoNear(float|array|Point $x, float $y = null)

Outputs documents in order of nearest to farthest from a specified point.

A GeoJSON point may be provided as the first and only argument for 2dsphere queries. This single parameter may be a GeoJSON point object or an array corresponding to the point's JSON representation. If GeoJSON is used, the "spherical" option will default to true.

You can only use this as the first stage of a pipeline.

Parameters

float|array|Point $x
float $y

Return Value

GeoNear

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/geoNear/

Stage getStage(integer $index)

Returns a certain stage from the pipeline

Parameters

integer $index

Return Value

Stage

array getPipeline()

Returns the assembled aggregation pipeline

Return Value

array

GraphLookup graphLookup(string $from)

Performs a recursive search on a collection, with options for restricting the search by recursion depth and query filter.

Parameters

string $from Target collection for the $graphLookup operation to search, recursively matching the connectFromField to the connectToField.

Return Value

GraphLookup

See also

https://docs.mongodb.org/manual/reference/operator/aggregation/graphLookup/

Group group()

Groups documents by some specified expression and outputs to the next stage a document for each distinct grouping.

IndexStats indexStats()

Returns statistics regarding the use of each index for the collection.

Limit limit(integer $limit)

Limits the number of documents passed to the next stage in the pipeline.

Parameters

integer $limit

Return Value

Limit

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/limit/

Lookup lookup(string $from)

Performs a left outer join to an unsharded collection in the same database to filter in documents from the “joined” collection for processing.

Match match()

Filters the documents to pass only the documents that match the specified condition(s) to the next pipeline stage.

Out out(string $collection)

Takes the documents returned by the aggregation pipeline and writes them to a specified collection. This must be the last stage in the pipeline.

Parameters

string $collection

Return Value

Out

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/out/

Project project()

Passes along the documents with only the specified fields to the next stage in the pipeline. The specified fields can be existing fields from the input documents or newly computed fields.

Expr matchExpr()

Returns a query expression to be used in match stages

Return Value

Expr

Redact redact()

Restricts the contents of the documents based on information stored in the documents themselves.

ReplaceRoot replaceRoot(string|null $expression = null)

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.

Parameters

string|null $expression Optional. A replacement expression that resolves to a document.

Return Value

ReplaceRoot

Sample sample(integer $size)

Randomly selects the specified number of documents from its input.

Skip skip(integer $skip)

Skips over the specified number of documents that pass into the stage and passes the remaining documents to the next stage in the pipeline.

Parameters

integer $skip

Return Value

Skip

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/skip/

Sort sort(array|string $fieldName, integer|string $order = null)

Sorts all input documents and returns them to the pipeline in sorted order.

If sorting by multiple fields, the first argument should be an array of field name (key) and order (value) pairs.

Parameters

array|string $fieldName Field name or array of field/order pairs
integer|string $order Field order (if one field is specified)

Return Value

Sort

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/sort/

SortByCount sortByCount(string $expression)

Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group.

Parameters

string $expression The expression to group by

Return Value

SortByCount

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/sortByCount/

Unwind unwind(string $fieldName)

Deconstructs an array field from the input documents to output a document for each element. Each output document is the input document with the value of the array field replaced by the element.

Parameters

string $fieldName The field to unwind. It is automatically prefixed with the $ sign

Return Value

Unwind

See also

http://docs.mongodb.org/manual/reference/operator/aggregation/unwind/

protected Stage addStage(Stage $stage)

Parameters

Stage $stage

Return Value

Stage