$bucketAuto (estágio de agregação )

Definição

$bucketAuto

Categoriza documentos recebidos em um número específico de grupos, chamados blocos, com base em uma expressão especificada. Os limites dos compartimentos são determinados automaticamente em uma tentativa de distribuir uniformemente os documentos no número especificado de compartimentos.

Cada bucket é representado como um documento na saída. O documento para cada bucket contém:

• Um objeto _id que especifica os limites do bucket.

  • O campo _id.min especifica o limite inferior inclusivo para o bucket.

  • O campo _id.max especifica o limite superior para o bucket. Esse limite é exclusivo para todos os buckets, exceto para o bucket final da série, onde é inclusivo.

• Um campo count que contém o número de documentos no bucket. O campo count é incluído por padrão quando o documento output não é especificado.

O estágio $bucketAuto tem a seguinte forma:

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

Campo	Tipo	Descrição
groupBy	expressão	Umaexpressão pela qual agrupar documentos. Para especificar um caminho do campo, prefixe o nome do campo com um cifrão $ e coloque-o entre aspas.
buckets	inteiro	Um número inteiro positivo de 32 bits que especifica o número de buckets nos quais os documentos de entrada são agrupados.
output	documento	Opcional. Um documento que especifica os campos a serem incluídos nos documentos de saída, além do campo _id. Para especificar o campo a ser incluído, você deve usar expressões accumulator: <outputfield1>: { <accumulator>: <expression1> }, ... O campo count padrão não é incluído no documento de saída quando output é especificado. Especifique explicitamente a expressão count como parte do documento output para incluí-la: output: { <outputfield1>: { <accumulator>: <expression1> }, ... count: { $sum: 1 } }
granularity	string	Opcional. Uma string que especifica a série numérica preferencial a ser usada para garantir que as bordas do limite calculado terminem em números redondos preferenciais ou em suas potências de 10. Disponível somente se todos os valores de groupBy forem numéricos e nenhum deles for NaN. Os valores suportados de granularity são: "R5" "R10" "R20" "R40" "R80" "1-2-5" "E6" "E12" "E24" "E48" "E96" "E192" "POWERSOF2"

Considerações

Comportamento

Pode haver menos do que o número especificado de buckets se:

• O número de documentos de entrada é menor que o número especificado de buckets.

• O número de valores únicos da expressão groupBy é menor que o número especificado de buckets.

• O granularity tem menos intervalos do que o número de buckets.

• O granularity não é suficiente para distribuir uniformemente os documentos no número especificado de buckets.

Se a expressão groupBy se referir a uma array ou documento, os valores serão organizados usando a mesma ordem de $sort antes de determinar os buckets do intervalo.

A distribuição uniforme de documentos entre buckets depende da cardinalidade, ou do número de valores únicos, do campo groupBy. Se a cardinalidade não for alta o suficiente, o estágio $bucketAuto pode não distribuir uniformemente os resultados entre os buckets.

{ _id: 0 }
{ _id: 1 }
...
{ _id: 99 }

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

Exemplos

{ "_id" : 1, "title" : "The Pillars of Society", "artist" : "Grosz", "year" : 1926,
    "price" : Decimal128("199.99"),
    "dimensions" : { "height" : 39, "width" : 21, "units" : "in" } }
{ "_id" : 2, "title" : "Melancholy III", "artist" : "Munch", "year" : 1902,
    "price" : Decimal128("280.00"),
    "dimensions" : { "height" : 49, "width" : 32, "units" : "in" } }
{ "_id" : 3, "title" : "Dancer", "artist" : "Miro", "year" : 1925,
    "price" : Decimal128("76.04"),
    "dimensions" : { "height" : 25, "width" : 20, "units" : "in" } }
{ "_id" : 4, "title" : "The Great Wave off Kanagawa", "artist" : "Hokusai",
    "price" : Decimal128("167.30"),
    "dimensions" : { "height" : 24, "width" : 36, "units" : "in" } }
{ "_id" : 5, "title" : "The Persistence of Memory", "artist" : "Dali", "year" : 1931,
    "price" : Decimal128("483.00"),
    "dimensions" : { "height" : 20, "width" : 24, "units" : "in" } }
{ "_id" : 6, "title" : "Composition VII", "artist" : "Kandinsky", "year" : 1913,
    "price" : Decimal128("385.00"),
    "dimensions" : { "height" : 30, "width" : 46, "units" : "in" } }
{ "_id" : 7, "title" : "The Scream", "artist" : "Munch",
    "price" : Decimal128("159.00"),
    "dimensions" : { "height" : 24, "width" : 18, "units" : "in" } }
{ "_id" : 8, "title" : "Blue Flower", "artist" : "O'Keefe", "year" : 1918,
    "price" : Decimal128("118.42"),
    "dimensions" : { "height" : 24, "width" : 20, "units" : "in" } }

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

{
  "_id" : {
    "min" : Decimal128("76.04"),
    "max" : Decimal128("159.00")
  },
  "count" : 2
}
{
  "_id" : {
    "min" : Decimal128("159.00"),
    "max" : Decimal128("199.99")
  },
  "count" : 2
}
{
  "_id" : {
    "min" : Decimal128("199.99"),
    "max" : Decimal128("385.00")
  },
  "count" : 2
}
{
  "_id" : {
    "min" : Decimal128("385.00"),
    "max" : Decimal128("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" : Decimal128("76.04"), "max" : Decimal128("159.00") },
      "count" : 2
    },
    {
      "_id" : { "min" : Decimal128("159.00"), "max" : Decimal128("199.99") },
      "count" : 2
    },
    {
      "_id" : { "min" : Decimal128("199.99"), "max" : Decimal128("385.00") },
      "count" : 2 },
    {
      "_id" : { "min" : Decimal128("385.00"), "max" : Decimal128("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 ] }
  ]
}

public class Movie
{
    public ObjectId Id { get; set; }
    public int Runtime { get; set; }
    
    public string Title { get; set; }
    public string Rated { get; set; }
    public List<string> Genres { get; set; }
    public string Plot { get; set; }
    
    public ImdbData Imdb { get; set; }
    public int Year { get; set; }
    public int Index { get; set; }
    
    public string[] Comments { get; set; }
   
    [BsonElement("lastupdated")]
    public DateTime LastUpdated { get; set; }
}

var camelCaseConvention = new ConventionPack { new CamelCaseElementNameConvention() };
ConventionRegistry.Register("CamelCase", camelCaseConvention, type => true);

var pipeline = new EmptyPipelineDefinition<Movie>()
    .BucketAuto(
        groupBy: m => m.Runtime,
        buckets: 5);

var bucketAutoOptions = new AggregateBucketAutoOptions()
{
    Granularity = new AggregateBucketAutoGranularity("POWERSOF2")
};
var pipeline = new EmptyPipelineDefinition<Movie>()
    .BucketAuto(
        groupBy: m => m.Runtime,
        buckets: 5,
        options: bucketAutoOptions);

const pipeline = [
  {
    $bucketAuto: {
      groupBy: "$runtime",
      buckets: 5
    }
  }
];
const cursor = collection.aggregate(pipeline);
return cursor;

const pipeline = [
  {
    $bucketAuto: {
      groupBy: "$runtime",
      buckets: 5,
      granularity: "POWERSOF2"
    }
  }
];
const cursor = collection.aggregate(pipeline);
return cursor;

Saiba mais

Para saber mais sobre os estágios de pipeline relacionados, consulte o guia$bucket.