distinct() (Valores Distintos)
Última atualização: 2026-10-09
distinct() (Valores Distintos)
distinct() retorna todos os valores únicos de um determinado campo na coleção, ex.: `db.users.distinct('address.city')`. Retorna um array de valores sem duplicatas, não documentos completos — útil para enumerar categorias ou valores disponíveis. Observe que distinct em campos grandes sem índice pode ser lento, e os resultados são limitados pelo limite BSON de 16MB.
| Categoria | Leitura |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.distinct(<field>, <filter>)⚙️ Parâmetros
| campo | Nome do campo a deduplicar; caminhos com ponto como 'address.city' funcionam. |
|---|---|
| filtro | Opcional. Filtra documentos antes de coletar valores. |
Retorno：Matriz de valores distintos; vazia quando nada corresponde.
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// distinct: lista todas as cidades de usuários adultos
const cities = db.users.distinct(
'address.city',
{ age: { $gt: 18 } }
)
citiesSaída：
[ 'Beijing', 'Shanghai', 'Guangzhou' ]📌 Notas
- Retorna um array de valores, não contagens; use .length para contar
- Campos aninhados usam caminhos com pontos como 'address.city'
- Os resultados são limitados a 16MB; use um pipeline de agregação para conjuntos de dados enormes
🏷️ Tags Relacionados
💡 Casos Relacionados
Mais casos práticos em breve.
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QComo distinct difere da deduplicação com $group na agregação?
Adistinct() retorna um array simples de valores únicos; $group também pode contar, somar e agregar de formas mais ricas.
QO distinct funciona em campos aninhados?
ASim — use um caminho com pontos, ex.: db.users.distinct('address.city').
QO distinct falha quando os resultados são enormes?
ASe o resultado exceder o limite BSON de 16MB, ele gera erro; para resultados muito grandes, use um pipeline $group.
