$bucketAuto (Balde Automático)
Última atualização: 2026-10-09
$bucketAuto (Balde Automático)
$bucketAuto distribui documentos em um número especificado de baldes com contagens aproximadamente iguais, calculando os limites a partir da distribuição de valores — sem limites manuais. granularity ajusta os limites a sequências numéricas canônicas. O _id de cada documento de saída é um objeto de limite { min, max }. Ótimo para histogramas automáticos e visões gerais de distribuição.
| Categoria | Agrupamento e Janela |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $bucketAuto: { groupBy: <expressão>, buckets: <inteiro positivo>, output: { <campo>: <acumulador> }, granularity: <granularidade> } }⚙️ Parâmetros
| groupBy | Expressão que determina a qual bucket pertence. |
|---|---|
| buckets | Número desejado de buckets; deve ser um inteiro positivo. |
| output | Acumuladores por bucket, por exemplo $avg ou $sum. |
| granularity | Sequência numérica canônica para limites, por exemplo R5, 1-2-5, E12, POWERSOF2. |
Retorno：Um documento { _id: { min, max }, count, ... } por bucket
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $bucketAuto: divide em 4 baldes, média por balde
db.scores.aggregate([
{ $bucketAuto: {
groupBy: '$score',
buckets: 4,
output: { avg: { $avg: '$score' } }
} }
])Saída：
{ "_id": { "min": 0, "max": 45 }, "count": 10, "avg": 22.4 }
{ "_id": { "min": 45, "max": 82 }, "count": 10, "avg": 63.1 }📌 Notas
- buckets é uma meta; a contagem real pode ser menor com poucos documentos ou valores duplicados
- O _id de saída é um objeto de limite { min, max }, semi-aberto
- granularity ajusta os limites a sequências numéricas canônicas
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QA contagem de baldes é exata?
ANem sempre; poucos documentos ou valores assimétricos podem produzir menos baldes do que o solicitado.
QO que o parâmetro granularity faz?
AEle ajusta os limites a sequências canônicas como 1-2-5 ou E12 para marcas de graduação padrão.
QDevo usar $bucketAuto ou $bucket?
AEscolha $bucketAuto para baldes uniformes sem limites manuais; $bucket para limites personalizados.
