$bucketAuto (aggregation)

Definition定义

$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.一个_id对象，用于指定桶的边界。
  • The _id.min field specifies the inclusive lower bound for the bucket._id.min字段指定桶的包含下界。
  • 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. Explicitly specify the count expression as part of the output document to include it: 指定output时，输出文档中不包括默认count字段。将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 supported 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: 0 }
{ _id: 1 }
...
{ _id: 99 }

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 ] }
  ]
}