$range (Gerar Sequência de Números)
Última atualização: 2026-10-09
$range (Gerar Sequência de Números)
$range produz uma sequência de inteiros a partir de um valor inicial até (mas excluindo) um valor final, com um passo opcional. Usos típicos: construir sequências de datas com $dateAdd, gerar números de página para paginação ou fabricar dados de teste em escala. O passo tem como padrão 1 e pode ser negativo para sequências descendentes; um passo de 0 gera erro. O array resultante contém inteiros e é frequentemente alimentado em $map para gerar campos em massa.
| Categoria | Array |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
{ $range: [ <início>, <fim>, <passo> ] }⚙️ Parâmetros
| início | O inteiro inicial da sequência, inclusivo. |
|---|---|
| fim | O inteiro final da sequência, exclusivo. |
| passo | Diferença opcional entre vizinhos, padrão 1; não pode ser 0. |
Retorno：Uma matriz de inteiros de start até (excluindo) end
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// $range: gerar os números de 0 a 4
db.test.aggregate([
{ $project: {
nums: { $range: [0, 5] }
} }
])Saída：
{ '_id': 1, 'nums': [ 0, 1, 2, 3, 4 ] }📌 Notas
- O valor final é excluído; [0, 5] produz de 0 a 4
- Um passo de 0 gera erro; passos negativos contam de trás para frente a partir do início
- Frequentemente combinado com $map/$dateAdd para sequências de datas ou números
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QO valor final é incluído?
ANão — o intervalo é fechado à esquerda e aberto à direita, então [0, 5] termina em 4.
QPosso gerar uma sequência descendente?
ASim — use um passo negativo, ex.: { $range: [5, 0, -1] } produz de 5 até 1.
QO passo pode ser 0?
ANão, um passo de 0 gera erro.
