MongoDB C++ Driver  mongocxx-3.7.0
Public Member Functions | List of all members
mongocxx::pipeline Class Reference

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.
 
pipelineoperator= (pipeline &&) noexcept
 Move assigns a pipeline.
 
 ~pipeline ()
 Destroys a pipeline.
 
pipelineadd_fields (bsoncxx::document::view_or_value fields_to_add)
 Adds new fields to documents. More...
 
pipelinebucket (bsoncxx::document::view_or_value bucket_args)
 Categorizes documents into groups, called buckets, based on a specified expression and bucket boundaries. More...
 
pipelinebucket_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...
 
pipelinecoll_stats (bsoncxx::document::view_or_value coll_stats_args=bsoncxx::document::view{})
 Returns statistics regarding a collection or view. More...
 
pipelinecount (std::string field)
 Returns a document containing a count of the number of documents input to the stage. More...
 
pipelinecurrent_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...
 
pipelinefacet (bsoncxx::document::view_or_value facet_args)
 Processes multiple aggregation pipelines within a single stage on the same set of input documents. More...
 
pipelineappend_stage (bsoncxx::document::view_or_value stage)
 Appends a stage to this pipeline object. More...
 
pipelineappend_stages (bsoncxx::array::view_or_value stages)
 Appends stages to this pipeline object from the given bson array. More...
 
pipelinegeo_near (bsoncxx::document::view_or_value geo_near_args)
 Outputs documents in order of nearest to farthest from a specified point. More...
 
pipelinegraph_lookup (bsoncxx::document::view_or_value graph_lookup_args)
 Performs a recursive search on a collection. More...
 
pipelinegroup (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...
 
pipelineindex_stats ()
 Returns statistics regarding the use of each index for the collection. More...
 
pipelinelimit (std::int32_t limit)
 Limits the number of documents passed to the next stage in the pipeline. More...
 
pipelinelist_local_sessions (bsoncxx::document::view_or_value list_local_sessions_args)
 Lists the sessions cached in memory by the mongod or mongos instance. More...
 
pipelinelist_sessions (bsoncxx::document::view_or_value list_sessions_args)
 Lists all sessions stored in the system.sessions collection in the config database. More...
 
pipelinelookup (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...
 
pipelinematch (bsoncxx::document::view_or_value filter)
 Filters the documents. More...
 
pipelinemerge (bsoncxx::document::view_or_value merge_args)
 Outputs the aggregation results to a collection. More...
 
pipelineout (std::string collection_name)
 Takes documents returned by the aggregation pipeline and writes them to a specified collection. More...
 
pipelineproject (bsoncxx::document::view_or_value projection)
 Projects a subset of the fields in the documents to the next stage of the pipeline. More...
 
pipelineredact (bsoncxx::document::view_or_value restrictions)
 Restricts the contents of the documents based on information stored in the documents themselves. More...
 
pipelinereplace_root (bsoncxx::document::view_or_value replace_root_args)
 Promotes a specified document to the top level and replaces all other fields. More...
 
pipelinesample (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...
 
pipelineskip (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...
 
pipelinesort (bsoncxx::document::view_or_value ordering)
 Sorts all input documents and returns them to the pipeline in sorted order. More...
 
pipelinesort_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...
 
pipelinesort_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...
 
pipelineunwind (bsoncxx::document::view_or_value unwind_args)
 Deconstructs an array field from the input documents to output a document for each element. More...
 
pipelineunwind (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_addA 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
stageA 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
stagesA 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_argsThe 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_argsThe 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_argsThe 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
fieldName 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_argsA 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_argsThe 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_argsThe 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_argsThe 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_argsThe 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
limitThe 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_argsA 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_argsA 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_argsThe 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
filterThe 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_argsThe 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_nameThe 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
projectionThe 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
restrictionsThe 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_argsThe 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
sizeThe 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_skipThe 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
orderingDocument 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_expressionThe 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_expressionThe 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_argsThe 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_nameThe 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: