$bucketAuto (aggregation)

Definition定义

$bucketAuto

Categorizes incoming documents into a specific number of groups, called buckets, based on a specified expression. 根据指定的表达式，将传入文档分类为特定数量的组，称为bucket。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. 每个bucket在输出中表示为一个文档。The document for each bucket contains:每个桶的文档包含：

• An _id object that specifies the bounds of the bucket.指定桶边界的_id.min对象。

  • The _id.min field specifies the inclusive lower bound for the bucket._idmin字段指定桶的包含下限。
  • The _id.max field specifies the upper bound for the bucket. _id.max字段指定桶的上限。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. 包含存储桶中文档数量的count字段。The count field is included by default when the output document is not specified.未指定output文档时，默认情况下包括count字段。

The $bucketAuto stage has the following form:$bucketAuto阶段具有以下形式：

{
  $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.一个正32位整数，指定输入文档分组到的存储桶数。
output	document	Optional. 可选。A document that specifies the fields to include in the output documents in addition to the _id field. 一种文档，它指定了除_id字段外还包括在输出文档中的字段。To specify the field to include, you must use accumulator expressions:要指定要包含的字段，必须使用累加器表达式： <outputfield1>: { <accumulator>: <expression1> }, ... The default count field is not included in the output document when output is specified. 指定output时，输出文档中不包括默认count字段。Explicitly specify the count expression as part of the output document to include it:显式指定count表达式作为输出文档的一部分，以将其包括在内： 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.一个字符串，用于指定要使用的首选数列，以确保计算的边界边以首选整数或其10的幂结束。 Available only if the all groupBy values are numeric and none of them are NaN.仅当所有groupBy值均为数值且均为NaN时可用。 The suppported values of granularity are:支持的granularity值为： "R5" "R10" "R20" "R40" "R80" "1-2-5" "E6" "E12" "E24" "E48" "E96" "E192" "POWERSOF2"

Considerations注意事项

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.groupBy表达式的唯一值数小于指定的buckets的数量。
• The granularity has fewer intervals than the number of buckets.granularity的间隔小于buckets的数量。
• The granularity is not fine enough to evenly distribute documents into the specified number of buckets.granularity不够精细，无法将文档均匀分布到指定数量的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.如果groupBy表达式引用数组或文档，则在确定桶边界之前，使用与$sort相同的顺序排列值。

The even distribution of documents across buckets depends on the cardinality, or the number of unique values, of the groupBy field. 文档跨存储桶的均匀分布取决于groupBy字段的基数或唯一值的数量。If the cardinality is not high enough, the $bucketAuto stage may not evenly distribute the results across buckets.如果基数不够高，则$bucketAuto阶段可能无法将结果均匀分布到各个桶。

{ _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:考虑一个artwork集合包含以下文档：

{ "_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" : NumberDecimal("76.04"),
    "dimensions" : { "height" : 25, "width" : 20, "units" : "in" } }
{ "_id" : 4, "title" : "The Great Wave off Kanagawa", "artist" : "Hokusai",
    "price" : NumberDecimal("167.30"),
    "dimensions" : { "height" : 24, "width" : 36, "units" : "in" } }
{ "_id" : 5, "title" : "The Persistence of Memory", "artist" : "Dali", "year" : 1931,
    "price" : NumberDecimal("483.00"),
    "dimensions" : { "height" : 20, "width" : 24, "units" : "in" } }
{ "_id" : 6, "title" : "Composition VII", "artist" : "Kandinsky", "year" : 1913,
    "price" : NumberDecimal("385.00"),
    "dimensions" : { "height" : 30, "width" : 46, "units" : "in" } }
{ "_id" : 7, "title" : "The Scream", "artist" : "Munch",
    "price" : NumberDecimal("159.00"),
    "dimensions" : { "height" : 24, "width" : 18, "units" : "in" } }
{ "_id" : 8, "title" : "Blue Flower", "artist" : "O'Keefe", "year" : 1918,
    "price" : NumberDecimal("118.42"),
    "dimensions" : { "height" : 24, "width" : 20, "units" : "in" } }

db.artwork.aggregate( [
   {
     $bucketAuto: {
         groupBy: "$price",
         buckets: 4
     }
   }
] )

{
  "_id" : {
    "min" : NumberDecimal("76.04"),
    "max" : NumberDecimal("159.00")
  },
  "count" : 2
}
{
  "_id" : {
    "min" : NumberDecimal("159.00"),
    "max" : NumberDecimal("199.99")
  },
  "count" : 2
}
{
  "_id" : {
    "min" : NumberDecimal("199.99"),
    "max" : NumberDecimal("385.00")
  },
  "count" : 2
}
{
  "_id" : {
    "min" : NumberDecimal("385.00"),
    "max" : NumberDecimal("483.00")
  },
  "count" : 2
}

db.artwork.aggregate( [
  {
    $facet: {
      "price": [
        {
          $bucketAuto: {
            groupBy: "$price",
            buckets: 4
          }
        }
      ],
      "year": [
        {
          $bucketAuto: {
            groupBy: "$year",
            buckets: 3,
            output: {
              "count": { $sum: 1 },
              "years": { $push: "$year" }
            }
          }
        }
      ],
      "area": [
        {
          $bucketAuto: {
            groupBy: {
              $multiply: [ "$dimensions.height", "$dimensions.width" ]
            },
            buckets: 4,
            output: {
              "count": { $sum: 1 },
              "titles": { $push: "$title" }
            }
          }
        }
      ]
    }
  }
] )

{
  "area" : [
    {
      "_id" : { "min" : 432, "max" : 500 },
      "count" : 3,
      "titles" : [
        "The Scream",
        "The Persistence of Memory",
        "Blue Flower"
      ]
    },
    {
      "_id" : { "min" : 500, "max" : 864 },
      "count" : 2,
      "titles" : [
        "Dancer",
        "The Pillars of Society"
      ]
    },
    {
      "_id" : { "min" : 864, "max" : 1568 },
      "count" : 2,
      "titles" : [
        "The Great Wave off Kanagawa",
        "Composition VII"
      ]
    },
    {
      "_id" : { "min" : 1568, "max" : 1568 },
      "count" : 1,
      "titles" : [
        "Melancholy III"
      ]
    }
  ],
  "price" : [
    {
      "_id" : { "min" : NumberDecimal("76.04"), "max" : NumberDecimal("159.00") },
      "count" : 2
    },
    {
      "_id" : { "min" : NumberDecimal("159.00"), "max" : NumberDecimal("199.99") },
      "count" : 2
    },
    {
      "_id" : { "min" : NumberDecimal("199.99"), "max" : NumberDecimal("385.00") },
      "count" : 2 },
    {
      "_id" : { "min" : NumberDecimal("385.00"), "max" : NumberDecimal("483.00") },
      "count" : 2
    }
  ],
  "year" : [
    { "_id" : { "min" : null, "max" : 1913 }, "count" : 3, "years" : [ 1902 ] },
    { "_id" : { "min" : 1913, "max" : 1926 }, "count" : 3, "years" : [ 1913, 1918, 1925 ] },
    { "_id" : { "min" : 1926, "max" : 1931 }, "count" : 2, "years" : [ 1926, 1931 ] }
  ]
}