class Builder (View source)

Fluent interface for building aggregation pipelines.

Methods

__construct(DocumentManager $dm, string $documentName)

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(string $fieldName)

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

execute(array $options = [])

Executes the aggregation pipeline

expr()

No description

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.

getPipeline()

Returns the assembled aggregation pipeline

getStage(int $index)

Returns a certain stage from the 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.

hydrate(string $className)

Set which class to use when hydrating results as document class instances.

indexStats()

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

limit(int $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.

matchExpr()

Returns a query expression to be used in match stages

out(string $from)

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.

redact()

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

replaceRoot(string|array|null $expression = null)

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

sample(int $size)

Randomly selects the specified number of documents from its input.

skip(int $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, int|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(DocumentManager $dm, string $documentName)

Create a new aggregation builder.

Parameters

DocumentManager $dm
string $documentName

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()

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()

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()

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(string $fieldName)

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

execute(array $options = [])

Executes the aggregation pipeline

Parameters

array $options

expr()

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.

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

See also

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

getPipeline()

Returns the assembled aggregation pipeline

For pipelines where the first stage is a $geoNear stage, it will apply the document filters and discriminator queries to the query portion of the geoNear operation. For all other pipelines, it prepends a $match stage containing the required query.

getStage(int $index)

Returns a certain stage from the pipeline

Parameters

int $index

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.

See also

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

group()

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

hydrate(string $className)

Set which class to use when hydrating results as document class instances.

Parameters

string $className

indexStats()

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

limit(int $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.

matchExpr()

Returns a query expression to be used in match stages

out(string $from)

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.

redact()

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

replaceRoot(string|array|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|array|null $expression Optional. A replacement expression that resolves to a document.

sample(int $size)

Randomly selects the specified number of documents from its input.

skip(int $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, int|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
int|string $order Field order (if one field is specified)

See also

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

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.

protected addStage(Stage $stage)

Parameters

Stage $stage