class Match extends Stage (View source)

Fluent interface for building aggregation pipelines.

Properties

protected Builder $builder from Stage
protected Expr $query

Methods

__construct(Builder $builder)

No description

getExpression()

Assembles the aggregation stage

execute(array $options = [])

Executes the aggregation pipeline

from Stage
bucket()

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

from Stage
bucketAuto()

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

from Stage
collStats()

Returns statistics regarding a collection or view.

from Stage
count(string $fieldName)

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

from Stage
facet()

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

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

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

from Stage
getPipeline()

Returns the assembled aggregation pipeline

from Stage
graphLookup(string $from)

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

from Stage
group()

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

from Stage
indexStats()

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

from Stage
limit(int $limit)

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

from Stage
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.

from Stage
match()

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

from Stage
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.

from Stage
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.

from Stage
redact()

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

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

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

from Stage
sample(int $size)

Randomly selects the specified number of documents from its input.

from Stage
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.

from Stage
sortByCount(string $expression)

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

from Stage
sort(array|string $fieldName, int|string $order = null)

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

from Stage
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.

from Stage
__clone()

No description

addAnd(array|Expr $expression, array|Expr ...$expressions)

Add one or more $and clauses to the current query.

addNor(array|Expr $expression, array|Expr ...$expressions)

Add one or more $nor clauses to the current query.

addOr(array|Expr $expression, array|Expr ...$expressions)

Add one or more $or clauses to the current query.

all(array $values)

Specify $all criteria for the current field.

mixed
debug(string|null $name = null)

Return an array of information about the Builder state for debugging.

elemMatch(array|Expr $expression)

Specify $elemMatch criteria for the current field.

equals(mixed $value)

Specify an equality match for the current field.

exists(bool $bool)

Specify $exists criteria for the current field.

expr()

Create a new Expr instance that can be used to build partial expressions for other operator methods.

field(string $field)

Set the current field for building the expression.

geoIntersects(array|Geometry $geometry)

Add $geoIntersects criteria with a GeoJSON geometry to the query.

geoWithin(Geometry $geometry)

Add $geoWithin criteria with a GeoJSON geometry to the query.

geoWithinBox(float $x1, float $y1, float $x2, float $y2)

Add $geoWithin criteria with a $box shape to the query.

geoWithinCenter(float $x, float $y, float $radius)

Add $geoWithin criteria with a $center shape to the query.

geoWithinCenterSphere(float $x, float $y, float $radius)

Add $geoWithin criteria with a $centerSphere shape to the query.

geoWithinPolygon(array $point1, array $point2, array $point3, array ...$points)

Add $geoWithin criteria with a $polygon shape to the query.

gt(mixed $value)

Specify $gt criteria for the current field.

gte(mixed $value)

Specify $gte criteria for the current field.

in(array $values)

Specify $in criteria for the current field.

includesReferenceTo(object $document)

No description

language(string $language)

Set the $language option for $text criteria.

lt(mixed $value)

Specify $lt criteria for the current field.

lte(mixed $value)

Specify $lte criteria for the current field.

$this
maxDistance(float $maxDistance)

Add $maxDistance criteria to the query.

$this
minDistance(float $minDistance)

Add $minDistance criteria to the query.

mod(float|int $divisor, float|int $remainder = 0)

Specify $mod criteria for the current field.

not(array|Expr $expression)

Negates an expression for the current field.

notEqual(mixed $value)

Specify $ne criteria for the current field.

notIn(array $values)

Specify $nin criteria for the current field.

range(mixed $start, mixed $end)

Specify $gte and $lt criteria for the current field.

references(object $document)

No description

size(int $size)

Specify $size criteria for the current field.

text(string $search)

Specify $text criteria for the current field.

type(int|string $type)

Specify $type criteria for the current field.

Details

__construct(Builder $builder)

Parameters

Builder $builder

getExpression()

Assembles the aggregation stage

execute(array $options = [])

Executes the aggregation pipeline

Parameters

array $options

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.

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.

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

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.

indexStats()

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

Limit 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.

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.

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.

sortByCount(string $expression)

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

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/

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.

addAnd(array|Expr $expression, array|Expr ...$expressions)

Add one or more $and clauses to the current query.

You can create a new expression using the {@link Builder::matchExpr()} method.

Parameters

array|Expr $expression
array|Expr ...$expressions

See also

Expr::addAnd
http://docs.mongodb.org/manual/reference/operator/and/

addNor(array|Expr $expression, array|Expr ...$expressions)

Add one or more $nor clauses to the current query.

You can create a new expression using the {@link Builder::matchExpr()} method.

Parameters

array|Expr $expression
array|Expr ...$expressions

See also

Expr::addNor
http://docs.mongodb.org/manual/reference/operator/nor/

addOr(array|Expr $expression, array|Expr ...$expressions)

Add one or more $or clauses to the current query.

You can create a new expression using the {@link Builder::matchExpr()} method.

Parameters

array|Expr $expression
array|Expr ...$expressions

See also

Expr::addOr
http://docs.mongodb.org/manual/reference/operator/or/

all(array $values)

Specify $all criteria for the current field.

mixed debug(string|null $name = null)

Return an array of information about the Builder state for debugging.

The $name parameter may be used to return a specific key from the internal $query array property. If omitted, the entire array will be returned.

Parameters

string|null $name

Return Value

mixed

elemMatch(array|Expr $expression)

Specify $elemMatch criteria for the current field.

You can create a new expression using the {@link Builder::matchExpr()} method.

equals(mixed $value)

Specify an equality match for the current field.

Parameters

mixed $value

See also

Expr::equals

exists(bool $bool)

Specify $exists criteria for the current field.

expr()

Create a new Expr instance that can be used to build partial expressions for other operator methods.

field(string $field)

Set the current field for building the expression.

Parameters

string $field

See also

Expr::field

geoIntersects(array|Geometry $geometry)

Add $geoIntersects criteria with a GeoJSON geometry to the query.

The geometry parameter GeoJSON object or an array corresponding to the geometry's JSON representation.

geoWithin(Geometry $geometry)

Add $geoWithin criteria with a GeoJSON geometry to the query.

The geometry parameter GeoJSON object or an array corresponding to the geometry's JSON representation.

geoWithinBox(float $x1, float $y1, float $x2, float $y2)

Add $geoWithin criteria with a $box shape to the query.

A rectangular polygon will be constructed from a pair of coordinates corresponding to the bottom left and top right corners.

Note: the $box operator only supports legacy coordinate pairs and 2d indexes. This cannot be used with 2dsphere indexes and GeoJSON shapes.

Parameters

float $x1
float $y1
float $x2
float $y2

See also

Expr::geoWithinBox
http://docs.mongodb.org/manual/reference/operator/box/

geoWithinCenter(float $x, float $y, float $radius)

Add $geoWithin criteria with a $center shape to the query.

Note: the $center operator only supports legacy coordinate pairs and 2d indexes. This cannot be used with 2dsphere indexes and GeoJSON shapes.

Parameters

float $x
float $y
float $radius

See also

Expr::geoWithinCenter
http://docs.mongodb.org/manual/reference/operator/center/

geoWithinCenterSphere(float $x, float $y, float $radius)

Add $geoWithin criteria with a $centerSphere shape to the query.

Note: the $centerSphere operator supports both 2d and 2dsphere indexes.

geoWithinPolygon(array $point1, array $point2, array $point3, array ...$points)

Add $geoWithin criteria with a $polygon shape to the query.

Point coordinates are in x, y order (easting, northing for projected coordinates, longitude, latitude for geographic coordinates).

The last point coordinate is implicitly connected with the first.

Note: the $polygon operator only supports legacy coordinate pairs and 2d indexes. This cannot be used with 2dsphere indexes and GeoJSON shapes.

Parameters

array $point1 First point of the polygon
array $point2 Second point of the polygon
array $point3 Third point of the polygon
array ...$points Additional points of the polygon

See also

Expr::geoWithinPolygon
http://docs.mongodb.org/manual/reference/operator/polygon/

gt(mixed $value)

Specify $gt criteria for the current field.

gte(mixed $value)

Specify $gte criteria for the current field.

in(array $values)

Specify $in criteria for the current field.

includesReferenceTo(object $document)

Parameters

object $document

language(string $language)

Set the $language option for $text criteria.

This method must be called after text().

lt(mixed $value)

Specify $lt criteria for the current field.

lte(mixed $value)

Specify $lte criteria for the current field.

$this maxDistance(float $maxDistance)

Add $maxDistance criteria to the query.

If the query uses GeoJSON points, $maxDistance will be interpreted in meters. If legacy point coordinates are used, $maxDistance will be interpreted in radians.

$this minDistance(float $minDistance)

Add $minDistance criteria to the query.

If the query uses GeoJSON points, $minDistance will be interpreted in meters. If legacy point coordinates are used, $minDistance will be interpreted in radians.

mod(float|int $divisor, float|int $remainder = 0)

Specify $mod criteria for the current field.

Parameters

float|int $divisor
float|int $remainder

See also

Expr::mod
http://docs.mongodb.org/manual/reference/operator/mod/

not(array|Expr $expression)

Negates an expression for the current field.

You can create a new expression using the {@link Builder::matchExpr()} method.

notEqual(mixed $value)

Specify $ne criteria for the current field.

notIn(array $values)

Specify $nin criteria for the current field.

range(mixed $start, mixed $end)

Specify $gte and $lt criteria for the current field.

This method is shorthand for specifying $gte criteria on the lower bound and $lt criteria on the upper bound. The upper bound is not inclusive.

Parameters

mixed $start
mixed $end

See also

Expr::range

references(object $document)

Parameters

object $document

size(int $size)

Specify $size criteria for the current field.

text(string $search)

Specify $text criteria for the current field.

The $language option may be set with {@link Builder::language()}.

You can only use this in the first $match stage of a pipeline.

type(int|string $type)

Specify $type criteria for the current field.