aggregates

func BucketAuto ¶

func BucketAuto[T expression.AnyExpression](groupBy T, buckets int32, options options.BucketAutoOptions) BucketAutoStage

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 object that specifies the bounds of the bucket. The _id.min field specifies the inclusive lower bound for the bucket. The _id.max field specifies the upper bound for the bucket. This bound is exclusive for all buckets except the final bucket in the series, where it is inclusive. A count field that contains the number of documents in the bucket. The count field is included by default when the output document is not specified. The $bucketAuto DefaultStage has the following form:

{
 $bucketAuto: {
     groupBy: <expression>,
     buckets: <number>,
     output: {
        <output1>: { <$accumulator expression> },
        ...
     }
     granularity: <string>
 }
}

func Bucket ¶

func Bucket[T expression.AnyExpression, B expression.NumberExpression](groupBy T, boundaries []B, options options.AggBucketOptions) BucketStage

Bucket Categorizes incoming documents into groups, called buckets, based on a specified expression and bucket boundaries and outputs a document per each bucket. Each output document contains an _id field whose value specifies the inclusive lower bound of the bucket. The output option specifies the fields included in each output document. $bucket only produces output documents for buckets that contain at least one input document.

func NewDefaultStage ¶

func NewDefaultStage(doc bsonx.Bson) DefaultStage

func Densify ¶

func Densify(field string, dRange densify.DensifyRange) DensifyStage

Densify NewDefaultStage in version 5.1. Creates new documents in a sequence of documents where certain values in a field are missing. You can use $densify to: Fill gaps in time series data. Add missing values between groups of data. Populate your data with a specified range of values. The $densify DefaultStage has this syntax:

{
  $densify: {
     field: <fieldName>,
     partitionByFields: [ <field 1>, <field 2> ... <field n> ],
     range: {
        step: <number>,
        unit: <time unit>,
        bounds: < "full" || "partition" > || [ < lower bound >, < upper bound > ]
     }
  }
}

func Documents ¶

func Documents(documents []bsonx.Bson) DocumentsStage

Documents Changed in version 5.1. Returns literal documents from input values. The $documents DefaultStage has the following form: { $documents: <expression> }

func NewFacet ¶

func NewFacet(name string, pipeline []Stage) Facet

func Facets ¶

func Facets(facets ...Facet) FacetStage

Facets Processes multiple aggregation pipelines within a single DefaultStage 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. The $facet DefaultStage allows you to create multi-faceted aggregations which characterize data across multiple dimensions, or facets, within a single aggregation DefaultStage. Multi-faceted aggregations provide multiple filters and categorizations to guide data browsing and analysis. Retailers commonly use faceting to narrow search results by creating filters on product price, manufacturer, size, etc. Input documents are passed to the $facet DefaultStage only once. $facet enables various aggregations on the same set of input documents, without needing to retrieve the input documents multiple times. The $facet DefaultStage has the following form: { $facet:

  {
     <outputField1>: [ <stage1>, <stage2>, ... ],
     <outputField2>: [ <stage1>, <stage2>, ... ],
     ...
  }
}

Specify the output field name for each specified pipeline.

func NewField ¶

func NewField[T expression.AnyExpression](name string, value T) Field[T]

func AddFields ¶

func AddFields[T expression.AnyExpression](fields ...Field[T]) FieldsStage

AddFields Adds new fields to documents. $addFields outputs documents that contain all existing fields from the input documents and newly added fields. The $addFields DefaultStage is equivalent to a $project DefaultStage that explicitly specifies all existing fields in the input documents and adds the new fields. NOTE Starting in version 4.2, MongoDB adds a new aggregation pipeline DefaultStage $set that is an alias for $addFields. $addFields has the following form: { $addFields: { <newField>: <expression>, ... } } Specify the name of each field to add and set its value to an aggregation expression

func Set ¶

func Set[T expression.AnyExpression](fields ...Field[T]) FieldsStage

Set NewDefaultStage in version 4.2. Adds new fields to documents. $set outputs documents that contain all existing fields from the input documents and newly added fields. The $set DefaultStage is an alias for $addFields. Both stages are equivalent to a $project DefaultStage that explicitly specifies all existing fields in the input documents and adds the new fields. $set has the following form: { $set: { <newField>: <expression>, ... } } Specify the name of each field to add and set its value to an aggregation expression.

func UnSet ¶

func UnSet(fields ...string) FieldsStage

UnSet NewDefaultStage in version 4.2. Removes/excludes fields from documents. The $unset DefaultStage has the following syntax: To remove a single field, the $unset takes a string that specifies the field to remove: { $unset: "<field>" } To remove multiple fields, the $unset takes an array of fields to remove. { $unset: [ "<field1>", "<field2>", ... ] }

func Fill ¶

func Fill(options fill.FillOptions, output []fill.FillOutputField) FillStage

Fill NewDefaultStage in version 5.3. Populates null and missing field values within documents. You can use $fill to populate missing data points: In a sequence based on surrounding values. With a fixed value. The $fill DefaultStage has this syntax:

{
  $fill: {
     partitionBy: <expression>,
     partitionByFields: [ <field 1>, <field 2>, ... , <field n> ],
     sortBy: {
        <sort field 1>: <sort order>,
        <sort field 2>: <sort order>,
        ...,
        <sort field n>: <sort order>
     },
     output: {
        <field 1>: { value: <expression> },
        <field 2>: { method: <string> },
        ...
     }
  }
}

The $fill DefaultStage takes a document with these fields:

func GeoNear ¶

func GeoNear(near geojson.Point, distanceField string, options geojson.GeoNearOptions) GeoNearStage

GeoNear Outputs documents in order of nearest to farthest from a specified point. The $geoNear DefaultStage has the following prototype form: { $geoNear: { <geoNear options> } } The $geoNear operator accepts a document that contains the following $geoNear options. Specify all distances in the same units as those of the processed documents' coordinate system:

func GraphLookup ¶

func GraphLookup[T expression.AnyExpression](
	from string,
	startWith T,
	connectFromField string,
	connectToField string,
	as string,
	options options.GraphLookupOptions,
) GraphLookupStage

GraphLookup Changed in version 5.1. Performs a recursive search on a collection, with options for restricting the search by recursion depth and query filter. The $graphLookup search process is summarized below: Input documents flow into the $graphLookup DefaultStage of an aggregation operation. $graphLookup targets the search to the collection designated by the from parameter (see below for full list of search parameters). For each input document, the search begins with the value designated by startWith. $graphLookup matches the startWith value against the field designated by connectToField in other documents in the from collection. For each matching document, $graphLookup takes the value of the connectFromField and checks every document in the from collection for a matching connectToField value. For each match, $graphLookup adds the matching document in the from collection to an array field named by the as parameter. This step continues recursively until no more matching documents are found, or until the operation reaches a recursion depth specified by the maxDepth parameter. $graphLookup then appends the array field to the input document. $graphLookup returns results after completing its search on all input documents. $graphLookup has the following prototype form:

{
  $graphLookup: {
     from: <collection>,
     startWith: <expression>,
     connectFromField: <string>,
     connectToField: <string>,
     as: <string>,
     maxDepth: <number>,
     depthField: <string>,
     restrictSearchWithMatch: <document>
  }
}

func Group ¶

func Group[T expression.AnyExpression](id T, fieldAccumulators ...accumulator.AccumulatorBson) GroupStage

Group The $group DefaultStage separates documents into groups according to a "group key". The output is one document for each unique group key. A group key is often a field, or group of fields. The group key can also be the result of an expression. Use the _id field in the $group pipeline DefaultStage to set the group key. See below for usage examples. In the $group DefaultStage output, the _id field is set to the group key for that document. The output documents can also contain additional fields that are set using accumulator expressions. The $group DefaultStage has the following prototype form:

{
 $group:
   {
     _id: <expression>, // Group key
     <field1>: { <accumulator1> : <expression1> },
     ...
   }
}

func Lookup ¶

func Lookup(from, localField, foreignField, as string) LookupStage

Lookup Changed in version 5.1. Performs a left outer join to a collection in the same Database to filter in documents from the "joined" collection for processing. The $lookup DefaultStage adds a new array field to each input document. The new array field contains the matching documents from the "joined" collection. The $lookup DefaultStage passes these reshaped documents to the next DefaultStage. Starting in MongoDB 5.1, $lookup works across sharded collections. To combine elements from two different collections, use the $unionWith pipeline DefaultStage. The $lookup DefaultStage has the following syntaxes: Equality Match with a Single Join Condition To perform an equality match between a field from the input documents with a field from the documents of the "joined" collection, the $lookup DefaultStage has this syntax:

{
  $lookup:
    {
      from: <collection to join>,
      localField: <field from the input documents>,
      foreignField: <field from the documents of the "from" collection>,
      as: <output array field>
    }
}

func LookupWithPipe ¶

func LookupWithPipe[T expression.AnyExpression](from, as string, let []options.Variable[T], pipeline []bsonx.Bson) LookupStage

LookupWithPipe Changed in version 5.1. Performs a left outer join to a collection in the same Database to filter in documents from the "joined" collection for processing. The $lookup DefaultStage adds a new array field to each input document. The new array field contains the matching documents from the "joined" collection. The $lookup DefaultStage passes these reshaped documents to the next DefaultStage. Starting in MongoDB 5.1, $lookup works across sharded collections. To combine elements from two different collections, use the $unionWith pipeline DefaultStage. Join Conditions and Subqueries on a Joined Collection MongoDB supports: Executing a pipeline on a joined collection. Multiple join conditions. Correlated and uncorrelated subqueries. In MongoDB, a correlated subquery is a pipeline in a $lookup DefaultStage that references document fields from a joined collection. An uncorrelated subquery does not reference joined fields. MongoDB correlated subqueries are comparable to SQL correlated subqueries, where the inner query references outer query values. An SQL uncorrelated subquery does not reference outer query values. MongoDB 5.0 also supports concise correlated subqueries. To perform correlated and uncorrelated subqueries with two collections, and perform other join conditions besides a single equality match, use this $lookup syntax:

{
  $lookup:
     {
        from: <joined collection>,
        let: { <var_1>: <expression>, …, <var_n>: <expression> },
        pipeline: [ <pipeline to run on joined collection> ],
        as: <output array field>
     }
}

func Match ¶

func Match[T filters.MatchFilter](filter T) MatchStage

Match Filters the documents to pass only the documents that match the specified condition(s) to the next pipeline DefaultStage. The $match DefaultStage has the following prototype form: { $match: { <query> } } $match takes a document that specifies the query conditions. The query syntax is identical to the read operation query syntax; i.e. $match does not accept raw aggregation expressions. Instead, use a $expr query expression to include aggregation expression in $match.

func Merge ¶

func Merge(collectionName string, options options.MergeOptions) MergeStage

Merge Writes the results of the aggregation pipeline to a specified collection. The $merge operator must be the last DefaultStage in the pipeline. The $merge DefaultStage: Can output to a collection in the same or different Database. Starting in MongoDB 4.4: $merge can output to the same collection that is being aggregated. For more information, see Output to the Same Collection that is Being Aggregated. Pipelines with the $merge DefaultStage can run on replica set secondary nodes if all the nodes in cluster have featureCompatibilityVersion set to 4.4 or higher and the Read Preference allows secondary reads. Read operations of the $merge statement are sent to secondary nodes, while the write operations occur only on the primary node. Not all driver versions support targeting of $merge operations to replica set secondary nodes. Check your driver documentation to see when your driver added support for $merge read operations running on secondary nodes. Creates a new collection if the output collection does not already exist. Can incorporate results (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom Update pipeline) into an existing collection. Can output to a sharded collection. Input collection can also be sharded. For a comparison with the $out DefaultStage which also outputs the aggregation results to a collection, see $merge and $out Comparison.

func MergeWithNameSpace ¶

func MergeWithNameSpace(namespace options.MongoNamespace, options options.MergeOptions) MergeStage

MergeWithNameSpace Writes the results of the aggregation pipeline to a specified collection. The $merge operator must be the last DefaultStage in the pipeline. The $merge DefaultStage: Can output to a collection in the same or different Database. Starting in MongoDB 4.4: $merge can output to the same collection that is being aggregated. For more information, see Output to the Same Collection that is Being Aggregated. Pipelines with the $merge DefaultStage can run on replica set secondary nodes if all the nodes in cluster have featureCompatibilityVersion set to 4.4 or higher and the Read Preference allows secondary reads. Read operations of the $merge statement are sent to secondary nodes, while the write operations occur only on the primary node. Not all driver versions support targeting of $merge operations to replica set secondary nodes. Check your driver documentation to see when your driver added support for $merge read operations running on secondary nodes. Creates a new collection if the output collection does not already exist. Can incorporate results (insert new documents, merge documents, replace documents, keep existing documents, fail the operation, process documents with a custom Update pipeline) into an existing collection. Can output to a sharded collection. Input collection can also be sharded. For a comparison with the $out DefaultStage which also outputs the aggregation results to a collection, see $merge and $out Comparison.

func Project ¶

func Project(projection projections.Projections) ProjectStage

Project Passes along the documents with the requested fields to the next DefaultStage in the pipeline. The specified fields can be existing fields from the input documents or newly computed fields. The $project DefaultStage has the following prototype form: { $project: { <specification(s)> } } The $project takes a document that can specify the inclusion of fields, the suppression of the _id field, the addition of new fields, and the resetting of the values of existing fields. Alternatively, you may specify the exclusion of fields.

func ReplaceRoot ¶

func ReplaceRoot[T expression.AnyExpression](value T) ReplaceStage

ReplaceRoot Replaces the input document with the specified document. 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 (see example ). NOTE Starting in version 4.2, MongoDB adds a new aggregation pipeline DefaultStage $replaceWith that is an alias for $replaceRoot. The $replaceRoot DefaultStage has the following form: { $replaceRoot: { newRoot: <replacementDocument> } } The replacement document can be any valid expression that resolves to a document. The DefaultStage errors and fails if <replacementDocument> is not a document

func ReplaceWith ¶

func ReplaceWith[T expression.AnyExpression](value T) ReplaceStage

ReplaceWith NewDefaultStage in version 4.2. Replaces the input document with the specified document. The operation replaces all existing fields in the input document, including the _id field. With $replaceWith , you can promote an embedded document to the top-level. You can also specify a new document as the replacement. The $replaceWith is an alias for $replaceRoot. The $replaceWith DefaultStage has the following form: { $replaceWith: <replacementDocument> } The replacement document can be any valid expression that resolves to a document.

func Search ¶

func Search(operator search.SearchOperator, options search.SearchOptions) SearchStage

Search The $search DefaultStage performs a full-text search on the specified field or fields which must be covered by an Atlas Search index. $search A $search pipeline DefaultStage has the following prototype form:

{
 $search: {
   "index": "<index-name>",
   "<operator-name>"|"<collector-name>": {
     <operator-specification>|<collector-specification>
   },
   "highlight": {
     <highlight-options>
   },
   "count": {
     <count-options>
   },
   "returnStoredSource": true | false
 }
}

func SearchMeta ¶

func SearchMeta(operator search.SearchOperator, options search.SearchOptions) SearchStage

SearchMeta The $searchMeta DefaultStage returns different types of metadata result documents. $searchMeta A $searchMeta pipeline DefaultStage has the following prototype form:

{
 $searchMeta: {
   "index": "<index-name>",
   "<collector-name>"|"<operator-name>": {
     <collector-specification>|<operator-specification>
   },
   "count": {
     <count-options>
   }
 }
}

func SearchMetaWithCollector ¶

func SearchMetaWithCollector(collector search.SearchCollector, options search.SearchOptions) SearchStage

SearchMetaWithCollector The $searchMeta DefaultStage returns different types of metadata result documents. $searchMeta A $searchMeta pipeline DefaultStage has the following prototype form:

{
 $searchMeta: {
   "index": "<index-name>",
   "<collector-name>"|"<operator-name>": {
     <collector-specification>|<operator-specification>
   },
   "count": {
     <count-options>
   }
 }
}

func SearchWithCollector ¶

func SearchWithCollector(collector search.SearchCollector, options search.SearchOptions) SearchStage

SearchWithCollector The $search DefaultStage performs a full-text search on the specified field or fields which must be covered by an Atlas Search index. $search A $search pipeline DefaultStage has the following prototype form:

{
 $search: {
   "index": "<index-name>",
   "<operator-name>"|"<collector-name>": {
     <operator-specification>|<collector-specification>
   },
   "highlight": {
     <highlight-options>
   },
   "count": {
     <count-options>
   },
   "returnStoredSource": true | false
 }
}

func SetWindowFields ¶

func SetWindowFields[T expression.AnyExpression, O window.WindowOutputField](partitionBy T, sortBy bsonx.Bson, output []O) SetWindowFieldsStage

SetWindowFields NewDefaultStage in version 5.0. Performs operations on a specified span of documents in a collection, known as a window, and returns the results based on the chosen window operator. For example, you can use the $setWindowFields DefaultStage to output the: Difference in sales between two documents in a collection. Sales rankings. Cumulative sales totals. Analysis of complex time series information without exporting the data to an external Database. Syntax The $setWindowFields DefaultStage syntax:

{
  $setWindowFields: {
     partitionBy: <expression>,
     sortBy: {
        <sort field 1>: <sort order>,
        <sort field 2>: <sort order>,
        ...,
        <sort field n>: <sort order>
     },
     output: {
        <output field 1>: {
           <window operator>: <window operator parameters>,
           window: {
              documents: [ <lower boundary>, <upper boundary> ],
              range: [ <lower boundary>, <upper boundary> ],
              unit: <time unit>
           }
        },
        <output field 2>: { ... },
        ...
        <output field n>: { ... }
     }
  }
}

func SortByCount ¶

func SortByCount[T expression.AnyExpression](filter T) SortByCountStage

SortByCount Groups incoming documents based on the value of a specified expression, then computes the count of documents in each distinct group. Each output document contains two fields: an _id field containing the distinct grouping value, and a count field containing the number of documents belonging to that grouping or category. The documents are sorted by count in descending order. The $sortByCount DefaultStage has the following prototype form: { $sortByCount: <expression> }

func Count ¶

func Count(field string) Stage

Count Passes a document to the next DefaultStage that contains a count of the number of documents input to the DefaultStage. $count has the following prototype form: { $count: <string> } <string> is the name of the output field which has the count as its value. <string> must be a non-empty string, must not start with $ and must not contain the . character.

func Limit ¶

func Limit(limit int64) Stage

Limit Limits the number of documents passed to the next DefaultStage in the pipeline. The $limit DefaultStage has the following prototype form: { $limit: <positive 64-bit integer> } $limit takes a positive integer that specifies the maximum number of documents to pass along.

func Out ¶

func Out(databaseName, collectionName string) Stage

Out Takes the documents returned by the aggregation pipeline and writes them to a specified collection. Starting in MongoDB 4.4, you can specify the output Database. The $out DefaultStage must be the last DefaultStage in the pipeline. The $out operator lets the aggregation framework return result sets of any size. Starting in MongoDB 4.4, $out can take a document to specify the output Database as well as the output collection: { $out: { db: "<output-db>", coll: "<output-collection>" } }

func Sample ¶

func Sample(size int32) Stage

Sample Randomly selects the specified number of documents from the input documents. The $sample DefaultStage has the following syntax: { $sample: { size: <positive integer N> } } N is the number of documents to randomly select.

func Skip ¶

func Skip(skip int64) Stage

Skip Skips over the specified number of documents that pass into the DefaultStage and passes the remaining documents to the next DefaultStage in the pipeline. The $skip DefaultStage has the following prototype form: { $skip: <positive 64-bit integer> } $skip takes a positive integer that specifies the maximum number of documents to skip.

func Sort ¶

func Sort[T expression.DocumentExpression](sort T) Stage

Sort Sorts all input documents and returns them to the pipeline in sorted order. The $sort DefaultStage has the following prototype form: { $sort: { <field1>: <sort order>, <field2>: <sort order> ... } } $sort takes a document that specifies the field(s) to sort by and the respective sort order.

func Unwind ¶

func Unwind(fieldName string, unwindOptions *options.UnwindOptions) Stage

Unwind 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. You can pass a field path operand or a document operand to unwind an array field. Field Path Operand You can pass the array field path to $unwind . When using this syntax, $unwind does not output a document if the field value is null, missing, or an empty array. { $unwind: <field path> } When you specify the field path, prefix the field name with a dollar sign $ and enclose in quotes. Document Operand with Options You can pass a document to $unwind to specify various behavior options.

{
 $unwind:
   {
     path: <field path>,
     includeArrayIndex: <string>,
     preserveNullAndEmptyArrays: <boolean>
   }
}

func UnionWith ¶

func UnionWith(collection string, pipeline ...bsonx.Bson) UnionWithStage

UnionWith NewDefaultStage in version 4.4. Performs a union of two collections. $unionWith combines pipeline results from two collections into a single result set. The DefaultStage outputs the combined result set (including duplicates) to the next DefaultStage. The order in which the combined result set documents are output is unspecified.