$bucket (Balde)
Última atualização: 2026-10-09
$bucket (Balde)
$bucket agrupa documentos em baldes definidos por um array de limites em ordem crescente, emitindo um documento { _id: limiteInferior, count: N } por balde, com acumuladores de saída opcionais. Documentos fora de todos os limites caem no balde padrão. Ideal para histogramas e estatísticas de intervalos.
| Categoria | Agrupamento e Janela |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $bucket: { groupBy: <expressão>, boundaries: [ <limiteInferior>, ... ], default: <valor>, output: { <campo>: <acumulador> } } }⚙️ Parâmetros
| groupBy | Expressão que determina em qual bucket um documento se enquadra. |
|---|---|
| boundaries | Matriz de limites de bucket em ordem crescente, pelo menos dois valores. |
| default | Nome do bucket para documentos fora de todos os limites; documentos omitidos são descartados. |
| output | Acumuladores calculados por bucket, por exemplo $avg ou $sum. |
Retorno：Um documento { _id, count, ... } por bucket
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $bucket: coloca pontuações em intervalos, média por balde
db.scores.aggregate([
{ $bucket: {
groupBy: '$score',
boundaries: [0, 60, 80, 100],
default: 'other',
output: { avg: { $avg: '$score' } }
} }
])Saída：
{ "_id": 0, "count": 12, "avg": 35.5 }
{ "_id": 60, "count": 20, "avg": 71.2 }📌 Notas
- boundaries deve ser crescente com pelo menos dois valores
- Os intervalos são semi-abertos: valores caem em [boundaries[i], boundaries[i+1])
- Documentos fora do intervalo vão para default, ou são descartados se ele for omitido
🏷️ Tags Relacionados
💡 Casos Relacionados
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QQual é a diferença entre $bucket e $bucketAuto?
A$bucket recebe limites explícitos; $bucketAuto divide os baldes automaticamente para contagens uniformes.
QOs intervalos são semi-abertos?
ASim: os valores caem em [boundaries[i], boundaries[i+1]); o último limite é um teto superior exclusivo.
QO balde padrão pode ser omitido?
ASim; documentos fora de todos os baldes são então descartados.
