Class representing a MongoDB aggregation pipeline. More...

#include <pipeline.hpp>

Public Member Functions
	pipeline ()
	Creates a new aggregation pipeline. More...

	pipeline (pipeline &&) noexcept
	Move constructs a pipeline.

pipeline &	operator= (pipeline &&) noexcept
	Move assigns a pipeline.

	~pipeline ()
	Destroys a pipeline.

pipeline &	add_fields (bsoncxx::document::view_or_value fields_to_add)
	Adds new fields to documents. More...

pipeline &	bucket (bsoncxx::document::view_or_value bucket_args)
	Categorizes documents into groups, called buckets, based on a specified expression and bucket boundaries. More...

pipeline &	bucket_auto (bsoncxx::document::view_or_value bucket_auto_args)
	Categorizes documents into a specific number of groups, called buckets, based on a specified expression. More...

pipeline &	coll_stats (bsoncxx::document::view_or_value coll_stats_args=bsoncxx::document::view{})
	Returns statistics regarding a collection or view. More...

pipeline &	count (std::string field)
	Returns a document containing a count of the number of documents input to the stage. More...

pipeline &	current_op (bsoncxx::document::view_or_value current_op_args)
	Returns a stream of documents containing information on active and/or dormant operations as well as inactive sessions that are holding locks as part of a transaction. More...

pipeline &	facet (bsoncxx::document::view_or_value facet_args)
	Processes multiple aggregation pipelines within a single stage on the same set of input documents. More...

pipeline &	append_stage (bsoncxx::document::view_or_value stage)
	Appends a stage to this pipeline object. More...

pipeline &	append_stages (bsoncxx::array::view_or_value stages)
	Appends stages to this pipeline object from the given bson array. More...

pipeline &	geo_near (bsoncxx::document::view_or_value geo_near_args)
	Outputs documents in order of nearest to farthest from a specified point. More...

pipeline &	graph_lookup (bsoncxx::document::view_or_value graph_lookup_args)
	Performs a recursive search on a collection. More...

pipeline &	group (bsoncxx::document::view_or_value group_args)
	Groups documents by some specified expression and outputs to the next stage a document for each distinct grouping. More...

pipeline &	index_stats ()
	Returns statistics regarding the use of each index for the collection. More...

pipeline &	limit (std::int32_t limit)
	Limits the number of documents passed to the next stage in the pipeline. More...

pipeline &	list_local_sessions (bsoncxx::document::view_or_value list_local_sessions_args)
	Lists the sessions cached in memory by the mongod or mongos instance. More...

pipeline &	list_sessions (bsoncxx::document::view_or_value list_sessions_args)
	Lists all sessions stored in the system.sessions collection in the config database. More...

pipeline &	lookup (bsoncxx::document::view_or_value lookup_args)
	Performs a left outer join to an unsharded collection in the same database to filter in documents from the "joined" collection for processing. More...

pipeline &	match (bsoncxx::document::view_or_value filter)
	Filters the documents. More...

pipeline &	merge (bsoncxx::document::view_or_value merge_args)
	Outputs the aggregation results to a collection. More...

pipeline &	out (std::string collection_name)
	Takes documents returned by the aggregation pipeline and writes them to a specified collection. More...

pipeline &	project (bsoncxx::document::view_or_value projection)
	Projects a subset of the fields in the documents to the next stage of the pipeline. More...

pipeline &	redact (bsoncxx::document::view_or_value restrictions)
	Restricts the contents of the documents based on information stored in the documents themselves. More...

pipeline &	replace_root (bsoncxx::document::view_or_value replace_root_args)
	Promotes a specified document to the top level and replaces all other fields. More...

pipeline &	sample (std::int32_t size)
	Randomly selects the specified number of documents that pass into the stage and passes the remaining documents to the next stage in the pipeline. More...

pipeline &	skip (std::int32_t docs_to_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. More...

pipeline &	sort (bsoncxx::document::view_or_value ordering)
	Sorts all input documents and returns them to the pipeline in sorted order. More...

pipeline &	sort_by_count (bsoncxx::document::view_or_value field_expression)
	Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. More...

pipeline &	sort_by_count (std::string field_expression)
	Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. More...

pipeline &	unwind (bsoncxx::document::view_or_value unwind_args)
	Deconstructs an array field from the input documents to output a document for each element. More...

pipeline &	unwind (std::string field_name)
	Deconstructs an array field from the input documents to output a document for each element. More...

bsoncxx::array::view	view_array () const

Detailed Description

Class representing a MongoDB aggregation pipeline.

Constructor & Destructor Documentation

◆ pipeline()

mongocxx::pipeline::pipeline ( )

Creates a new aggregation pipeline.

See also: https://docs.mongodb.com/manual/core/aggregation-pipeline/

Member Function Documentation

◆ add_fields()

pipeline& mongocxx::pipeline::add_fields ( bsoncxx::document::view_or_value fields_to_add )

Adds new fields to documents.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/addFields/

Parameters

fields_to_add A document specifying the fields to add. For each field specified in this parameter, a corresponding field will be added to the documents, where the value of the added field is the result of evaluating the specified expression.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ append_stage()

pipeline& mongocxx::pipeline::append_stage ( bsoncxx::document::view_or_value stage )

Appends a stage to this pipeline object.

Use this method to run new pipeline stages that are not yet offered as explicit methods on this class. Pass in a document describing a pipeline stage:

{ "$addFields" : { "field" : 0 }}

Parameters

stage A bson document view or value describing a pipeline stage.

Returns: A reference to this object on which this member function is being called.

◆ append_stages()

pipeline& mongocxx::pipeline::append_stages ( bsoncxx::array::view_or_value stages )

Appends stages to this pipeline object from the given bson array.

Use this method to run new pipeline stages that are not yet offered as explicit methods on this class. Pass in an array of documents, where each document in the array describes a pipeline stage:

[ { "$addFields" : { "field" : 0 } }, { "$newStage" : ... }, ... ]

Parameters

stages A bson array containing documents describing pipeline stages.

Returns: A reference to the object on which this member function is being called.

◆ bucket()

pipeline& mongocxx::pipeline::bucket ( bsoncxx::document::view_or_value bucket_args )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/bucket/

Parameters

bucket_args The specification for the bucket operation. The required fields groupBy and boundaries must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ bucket_auto()

pipeline& mongocxx::pipeline::bucket_auto ( bsoncxx::document::view_or_value bucket_auto_args )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/bucketAuto/

Parameters

bucket_auto_args The specification for the bucket_auto operation. This required fields groupBy and buckets must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ coll_stats()

pipeline& mongocxx::pipeline::coll_stats ( bsoncxx::document::view_or_value coll_stats_args = bsoncxx::document::view{} )

Returns statistics regarding a collection or view.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/collStats/

Parameters

coll_stats_args The specification for the coll_stats operation. See link above for a list of valid options.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ count()

pipeline& mongocxx::pipeline::count ( std::string field )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/count/

Parameters

field Name of the field for the count to be written to.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ current_op()

pipeline& mongocxx::pipeline::current_op ( bsoncxx::document::view_or_value current_op_args )

Returns a stream of documents containing information on active and/or dormant operations as well as inactive sessions that are holding locks as part of a transaction.

The stage returns a document for each operation or session.

This stage must be used with database aggregate on the 'admin' database.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/currentOp/

Parameters

current_op_args A document containing the arguments for the current_op operation.

Returns: A reference to the object on which this method is being called.

◆ facet()

pipeline& mongocxx::pipeline::facet ( bsoncxx::document::view_or_value facet_args )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/facet/

Parameters

facet_args The specification for the facet operation. Each field in the the provided document should specify an aggregation pipeline, as an array.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ geo_near()

pipeline& mongocxx::pipeline::geo_near ( bsoncxx::document::view_or_value geo_near_args )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/geoNear/

Parameters

geo_near_args The specification for the geo_near operation. The required fields near and distanceField must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ graph_lookup()

pipeline& mongocxx::pipeline::graph_lookup ( bsoncxx::document::view_or_value graph_lookup_args )

Performs a recursive search on a collection.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/graphLookup/

Parameters

graph_lookup_args The specification for the graph_lookup operation. The required fields from, connectFromField, startWith, connectToField, and as must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ group()

pipeline& mongocxx::pipeline::group ( bsoncxx::document::view_or_value group_args )

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

The output documents contain an _id field which contains the the distinct key for that group. The output documents can also contain computed fields that hold the values of some accumulator expression grouped by the group's _id field.

Note: group does not order output documents.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/group/

Parameters

group_args The specification for the group operation. The required field _id must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ index_stats()

pipeline& mongocxx::pipeline::index_stats ( )

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

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/indexStats/

◆ limit()

pipeline& mongocxx::pipeline::limit ( std::int32_t limit )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/limit/

Parameters

limit The number of documents to which output should be limited.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ list_local_sessions()

pipeline& mongocxx::pipeline::list_local_sessions ( bsoncxx::document::view_or_value list_local_sessions_args )

Lists the sessions cached in memory by the mongod or mongos instance.

This option must be used with database aggregate.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/listLocalSessions/

Parameters

list_local_sessions_args A document containing the arguments for list_local_sessions.

Returns: A reference to the object on which this method is being called.

◆ list_sessions()

pipeline& mongocxx::pipeline::list_sessions ( bsoncxx::document::view_or_value list_sessions_args )

Lists all sessions stored in the system.sessions collection in the config database.

These sessions are visible to all members of the MongoDB deployment.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/listSessions/

Parameters

list_sessions_args A document containing the arguments for list_sessions.

Returns: A reference to the object on which this method is being called.

◆ lookup()

pipeline& mongocxx::pipeline::lookup ( bsoncxx::document::view_or_value lookup_args )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/lookup/

Parameters

lookup_args The specification for the lookup operation. The required fields from, localField, foreignField, and as must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ match()

pipeline& mongocxx::pipeline::match ( bsoncxx::document::view_or_value filter )

Filters the documents.

Only the documents that match the condition(s) specified by the filter will continue to the next pipeline stage.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/match/

Parameters

filter The filter.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ merge()

pipeline& mongocxx::pipeline::merge ( bsoncxx::document::view_or_value merge_args )

Outputs the aggregation results to a collection.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/merge/

Parameters

merge_args The specification for the merge options. Must include an into field that is either a collection name or a subdocument of the form: { db : <db name>, coll : <collection name> }.

Returns: A reference to the object on which this member function is being called.

◆ out()

pipeline& mongocxx::pipeline::out ( std::string collection_name )

Takes documents returned by the aggregation pipeline and writes them to a specified collection.

This stage must be the last stage in the pipeline. The out operator lets the aggregation framework return result sets of any size.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/out/

Parameters

collection_name The name of the collection where the output documents should go.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ project()

pipeline& mongocxx::pipeline::project ( bsoncxx::document::view_or_value projection )

Projects a subset of the fields in the documents to the next stage of the pipeline.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/project/

Parameters

projection The projection specification.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ redact()

pipeline& mongocxx::pipeline::redact ( bsoncxx::document::view_or_value restrictions )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/redact/

Parameters

restrictions The document restrictions.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ replace_root()

pipeline& mongocxx::pipeline::replace_root ( bsoncxx::document::view_or_value replace_root_args )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/replaceRoot/

Parameters

replace_root_args The specification for the replace_root operation. The required field newRoot must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ sample()

pipeline& mongocxx::pipeline::sample ( std::int32_t size )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/sample/

Parameters

size	The number of input documents to select.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ skip()

pipeline& mongocxx::pipeline::skip ( std::int32_t docs_to_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.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/skip/

Parameters

docs_to_skip The number of input documents to skip.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ sort()

pipeline& mongocxx::pipeline::sort ( bsoncxx::document::view_or_value ordering )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/sort/

Parameters

ordering Document specifying the ordering by which the documents are sorted.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

◆ sort_by_count() [1/2]

pipeline& mongocxx::pipeline::sort_by_count ( bsoncxx::document::view_or_value field_expression )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/sortByCount/

Parameters

field_expression The expression to group by, as an object. The expression can not evaluate to an object.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Note: This overload of sort_by_count() is intended to be used when the desired sort is over a grouping of the result of a complex expression computed from the input documents.

◆ sort_by_count() [2/2]

pipeline& mongocxx::pipeline::sort_by_count ( std::string field_expression )

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

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/sortByCount/

Parameters

field_expression The expression to group by, as a string. To specify a field path, prefix the field path with a dollar sign ($).

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Note: This overload of sort_by_count() is intended to be used when the desired sort is over a grouping of the value of a particular element in the input documents.

◆ unwind() [1/2]

pipeline& mongocxx::pipeline::unwind ( bsoncxx::document::view_or_value unwind_args )

Deconstructs an array field from the input documents to output a document for each element.

Each output document is an input document with the value of its array field replaced by an element from the unwound array.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/

Parameters

unwind_args The specification for the unwind operation. The required field path must be included.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Note: This overload of unwind() is intended to be used when additional options other than the field name need to be specified.

◆ unwind() [2/2]

pipeline& mongocxx::pipeline::unwind ( std::string field_name )

Deconstructs an array field from the input documents to output a document for each element.

Each output document is an input document with the value of its array field replaced by an element from the unwound array.

See also: https://docs.mongodb.com/manual/reference/operator/aggregation/unwind/

Parameters

field_name The name of the field to unwind.

Returns: A reference to the object on which this member function is being called. This facilitates method chaining.

Note: This overload of unwind() is intended to be used when no options other than the field name need to be specified.

◆ view_array()

bsoncxx::array::view mongocxx::pipeline::view_array ( ) const

Returns: A view of the underlying BSON array this pipeline represents.

The documentation for this class was generated from the following file:

src/mongocxx/pipeline.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ pipeline()

Member Function Documentation

◆ add_fields()

◆ append_stage()

◆ append_stages()

◆ bucket()

◆ bucket_auto()

◆ coll_stats()

◆ count()

◆ current_op()

◆ facet()

◆ geo_near()

◆ graph_lookup()

◆ group()

◆ index_stats()

◆ limit()

◆ list_local_sessions()

◆ list_sessions()

◆ lookup()

◆ match()

◆ merge()

◆ out()

◆ project()

◆ redact()

◆ replace_root()

◆ sample()

◆ skip()

◆ sort()

◆ sort_by_count() [1/2]

◆ sort_by_count() [2/2]

◆ unwind() [1/2]

◆ unwind() [2/2]

◆ view_array()