countDocuments() (Contar com Filtro)
Última atualização: 2026-10-09
countDocuments() (Contar com Filtro)
countDocuments() conta documentos que correspondem a um filtro, ex.: `db.users.countDocuments({ age: { $gte: 18 } })`. Ele executa no servidor e retorna uma contagem exata. Diferente de estimatedDocumentCount(), ele realmente avalia o filtro, então é preciso porém mais lento — a escolha certa quando a precisão importa. Para consultas sensíveis a desempenho em coleções enormes, respalde o filtro com um índice.
| Categoria | Leitura |
|---|---|
| Versão do MongoDB | 1.0+ |
| Idioma do Exemplo | mongosh (Shell) |
📝 Sintaxe
db.<collection>.countDocuments(<filter>, { limit: <number> })⚙️ Parâmetros
| filtro | Filtro a contar; {} vazio conta tudo. |
|---|---|
| limit | Opcional. Limite superior de documentos contados. |
Retorno：Número de documentos correspondentes (inteiro).
▶ Exemplo
Execute os comandos abaixo no seu mongosh local (requer um mongod em execução):
// countDocuments: conta usuários adultos
const n = db.users.countDocuments({ age: { $gte: 18 } })
print('Adults: ' + n)Saída：
Adultos: 42📌 Notas
- Contagem exata que realmente avalia o filtro — mais lenta que estimatedDocumentCount
- Crie índice nos campos filtrados para evitar varreduras completas da coleção
- Passe um filtro vazio {} para o total de documentos
🏷️ Tags Relacionados
💡 Casos Relacionados
Noções básicas sobre consultas a documentos: o método `find` e as projeções
API RESTful na prática: um guia completo para o projeto CRUD
📚 Tutoriais Relacionados
❓ Perguntas Frequentes
QComo countDocuments difere de estimatedDocumentCount?
AcountDocuments() avalia o filtro com precisão porém mais lentamente; estimatedDocumentCount() usa metadados da coleção — rápido porém aproximado.
QPor que não é recomendado contar uma coleção inteira com countDocuments?
AEle precisa varrer as correspondências, o que é lento em coleções grandes. Quando a magnitude basta, use estimatedDocumentCount().
QO countDocuments retorna 0 ou lança erro quando nada corresponde?
AEle retorna 0 sem lançar erro — seguro para usar em condicionais.
