As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

# $bucketAuto
<a name="bucketAuto"></a>

Novo na versão 8.0.2.

O estágio `$bucketAuto` de agregação no Amazon DocumentDB agrupa automaticamente os documentos de entrada em um número específico de buckets com base em uma expressão especificada. Ao `$bucket` contrário de quando você define explicitamente os limites do intervalo, determina `$bucketAuto` automaticamente os limites para que os documentos sejam distribuídos da forma mais uniforme possível pelo número solicitado de compartimentos. Isso pode ser útil quando você deseja categorizar os dados em um número fixo de grupos sem conhecer a distribuição dos valores com antecedência.

**Parâmetros**
+ `groupBy`(obrigatório): a expressão que especifica o valor pelo qual agrupar.
+ `buckets`(obrigatório): um número inteiro positivo que especifica o número de compartimentos nos quais os documentos são agrupados. Dependendo dos documentos de entrada e da `groupBy` expressão, o número real de compartimentos pode ser menor que o número especificado.
+ `output`(opcional): um objeto que especifica as informações a serem produzidas para cada bucket. Você pode usar operadores de acumulador como`$sum`, `$avg``$min`, e `$max` para calcular agregações para cada bucket. Se omitido, cada bucket gera um `count` campo por padrão.
+ `granularity`(opcional): uma string que especifica a série numérica preferida a ser usada para os limites do intervalo. Isso ajusta os limites computados a uma progressão numérica padrão. Esse parâmetro estará disponível somente se todos os `groupBy` valores forem numéricos e nenhum deles for`NaN`. Os valores válidos são: `R5` `R10` `R20` `R40``R80`,`1-2-5`,`E6`,`E12`,`E24`, `E48``E96`,`E192`,, `POWERSOF2` e.

**Saída**

Cada bucket é retornado como um documento separado que contém um `_id` objeto descrevendo os limites do bucket:
+ `_id.min`: O limite inferior inclusivo do balde.
+ `_id.max`: O limite superior do balde. Esse limite é exclusivo para cada compartimento, exceto o último compartimento da série, onde é inclusivo.

## Exemplo (MongoDB Shell)
<a name="bucketAuto-examples"></a>

O exemplo a seguir demonstra como usar o `$bucketAuto` estágio para agrupar dados de vendas em grupos por preço.

**Crie documentos de amostra **

```
db.sales.insertMany([
  { item: "abc", price: 10, quantity: 2, date: new Date("2020-09-01") },
  { item: "def", price: 20, quantity: 1, date: new Date("2020-10-01") },
  { item: "ghi", price: 5, quantity: 3, date: new Date("2020-11-01") },
  { item: "jkl", price: 15, quantity: 2, date: new Date("2020-12-01") },
  { item: "mno", price: 25, quantity: 1, date: new Date("2021-01-01") }
]);
```

**Exemplo de consulta **

O comando a seguir agrupa os documentos de amostra em três grupos por preço:

```
db.sales.aggregate([
  {
    $bucketAuto: {
      groupBy: "$price",
      buckets: 3,
      output: {
        "count": { $sum: 1 },
        "totalQuantity": { $sum: "$quantity" }
      }
    }
  }
])
```

**Saída**

O comando retorna a seguinte saída:

```
[
  { _id: { min: 5, max: 15 }, count: 2, totalQuantity: 5 },
  { _id: { min: 15, max: 25 }, count: 2, totalQuantity: 3 },
  { _id: { min: 25, max: 25 }, count: 1, totalQuantity: 1 }
]
```

**Exemplo de consulta com granularidade **

O exemplo a seguir adiciona a `granularity` opção de ajustar os limites do bucket computado às potências de 2.

```
db.sales.aggregate([
  {
    $bucketAuto: {
      groupBy: "$price",
      buckets: 2,
      granularity: "POWERSOF2",
      output: {
        "count": { $sum: 1 },
        "totalQuantity": { $sum: "$quantity" }
      }
    }
  }
])
```

**Saída**

O comando retorna a seguinte saída:

```
[
  { _id: { min: 4, max: 16 }, count: 3, totalQuantity: 7 },
  { _id: { min: 16, max: 32 }, count: 2, totalQuantity: 2 }
]
```

## Exemplos de código
<a name="bucketAuto-code"></a>

Para ver um exemplo de código para usar o `$bucketAuto` comando, escolha a guia do idioma que você deseja usar:

------
#### [ Node.js ]

```
const { MongoClient } = require('mongodb');

async function example() {
  const client = await MongoClient.connect('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false');
  const db = client.db('test');
  const sales = db.collection('sales');

  const result = await sales.aggregate([
    {
      $bucketAuto: {
        groupBy: "$price",
        buckets: 3,
        output: {
          "count": { $sum: 1 },
          "totalQuantity": { $sum: "$quantity" }
        }
      }
    }
  ]).toArray();

  console.log(result);
  client.close();
}

example();
```

------
#### [ Python ]

```
from pymongo import MongoClient

def example():
    client = MongoClient('mongodb://<username>:<password>@<cluster-endpoint>:27017/?tls=true&tlsCAFile=global-bundle.pem&replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false')
    db = client['test']
    sales = db['sales']

    result = list(sales.aggregate([
        {
            '$bucketAuto': {
                'groupBy': '$price',
                'buckets': 3,
                'output': {
                    'count': {'$sum': 1},
                    'totalQuantity': {'$sum': '$quantity'}
                }
            }
        }
    ]))

    print(result)
    client.close()

example()
```

------