On this page

• Definition
• Behavior
• Example

Definition

$bucketAuto

New in version 3.4.

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 stage has the following form:

copy

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

Field	Type	Description
groupBy	expression	An expression to group documents by. To specify a field path, prefix the field name with a dollar sign $ and enclose it in quotes.
buckets	integer	A positive 32-bit integer that specifies the number of buckets into which input documents are grouped.
output	document	Optional. A document that specifies the fields to include in the output documents in addition to the _id field. To specify the field to include, you must use accumulator expressions: copy <outputfield1>: { <accumulator>: <expression1> }, ... The default count field is not included in the output document when output is specified. Explicitly specify the count expression as part of the output document to include it: copy output: { <outputfield1>: { <accumulator>: <expression1> }, ... count: { $sum: 1 } }
granularity	string	Optional. A string that specifies the preferred number series to use to ensure that the calculated boundary edges end on preferred round numbers or their powers of 10. Available only if the all groupBy values are numeric and none of them are NaN. The suppported values of granularity are: "R5" "R10" "R20" "R40" "R80" "1-2-5" "E6" "E12" "E24" "E48" "E96" "E192" "POWERSOF2"

Behavior

There may be less than the specified number of buckets if:

• The number of input documents is less than the specified number of buckets.
• The number of unique values of the groupBy expression is less than the specified number of buckets.
• The granularity has fewer intervals then the number of buckets.
• The granularity is not fine enough to evenly distribute documents into the specified number of buckets.

If the groupBy expression refers to an array or document, the values are arranged using the same ordering as in $sort before determining the bucket boundaries.

The even distribution of documents across buckets depends on the cardinality, or the number of unique values, of the groupBy field. If the cardinality is not high enough, the $bucketAuto stage may not evenly distribute the results across buckets.

{ _id: 1 }
{ _id: 2 }
...
{ _id: 100 }

db.things.aggregate( [
  {
    $bucketAuto: {
      groupBy: "$_id",
      buckets: 5,
      granularity: <granularity>
    }
  }
] )

Example

Consider a collection artwork with the following documents:

{ "_id" : 1, "title" : "The Pillars of Society", "artist" : "Grosz", "year" : 1926,
    "price" : NumberDecimal("199.99"),
    "dimensions" : { "height" : 39, "width" : 21, "units" : "in" } }
{ "_id" : 2, "title" : "Melancholy III", "artist" : "Munch", "year" : 1902,
    "price" : NumberDecimal("280.00"),
    "dimensions" : { "height" : 49, "width" : 32, "units" : "in" } }
{ "_id" : 3, "title" : "Dancer", "artist" : "Miro", "year" : 1925,
    "price" : Num