db.collection.countDocuments()
MongoDB com drivers
Esta página documenta um método mongosh. Para ver o método equivalente em um driver MongoDB, consulte a página correspondente da sua linguagem de programação:
Definição
db.collection.countDocuments(query, options)Retorna um número inteiro para o número de documentos que correspondem à query da coleção ou visualização. Este método está disponível para uso em Transações.
Compatibilidade
Esse método está disponível em implantações hospedadas nos seguintes ambientes:
MongoDB Atlas: o serviço totalmente gerenciado para implantações do MongoDB na nuvem
Observação
Este comando é aceito em todos os clusters do MongoDB Atlas. Para obter informações sobre o suporte do Atlas a todos os comandos, consulte Comandos não suportados.
MongoDB Enterprise: a versão autogerenciada e baseada em assinatura do MongoDB
MongoDB Community: uma versão com código disponível, de uso gratuito e autogerenciada do MongoDB
Sintaxe
O método countDocuments() tem o seguinte formato:
db.collection.countDocuments( <query>, <options> )
O método countDocuments() utiliza os seguintes parâmetros:
Parâmetro | Tipo | Descrição |
|---|---|---|
Query | documento | Os critérios de seleção da query. Para contar todos os documentos, especifique um documento vazio. Consulte também Restrições de query. |
opções | documento | Opcional. Opções extras que afetam o comportamento da contagem. |
O documento options pode conter o seguinte:
Campo | Tipo | Descrição |
|---|---|---|
| inteiro | Opcional. O número máximo de documentos para contar. |
| inteiro | Opcional. O número de documentos a serem ignorados antes da contagem. |
| string ou documento | Opcional. Um nome de índice ou a especificação de índice a ser usada para a consulta. |
| inteiro | Opcional. A quantidade máxima de tempo para permitir a execução da contagem. |
Comportamento
Mecânica
Ao contrário do db.collection.count(), o db.collection.countDocuments() não usa os metadados para retornar a contagem. Em vez disso, realiza uma agregação do documento para retornar uma contagem precisa, mesmo após um desligamento impuro ou na presença de documentos órfãos em um cluster fragmentado.
db.collection.countDocuments() envolve a seguinte operação de agregação e retorna apenas o valor de n:
db.collection.aggregate([ { $match: <query> }, { $group: { _id: null, n: { $sum: 1 } } } ])
Coleções e visualizações vazias ou não existentes
db.collection.countDocuments() retorna 0 em uma coleção ou exibição vazia ou inexistente.
Restrições de query
Você não pode usar os seguintes operadores de query como parte da expressão de query para db.collection.countDocuments():
Operador restrito | Alternativa | |
|---|---|---|
Como alternativa, use | ||
Como alternativa, use | ||
Como alternativa, use |
Transações
db.collection.countDocuments() pode ser usado dentro de transações distribuídas.
Quando você usa db.collection.countDocuments() em uma transação, a contagem resultante não filtrará transações multidocumentos não confirmada.
Importante
Na maioria dos casos, uma transação distribuída incorre em um custo de desempenho maior do que as gravações de um único documento, e a disponibilidade de transações distribuídas não deve substituir o design eficaz do esquema. Em muitos cenários, o modelo de dados desnormalizado (documentos e arrays incorporados) continuará a ser ideal para seus dados e casos de uso. Ou seja, para muitos cenários, modelar seus dados adequadamente minimizará a necessidade de transações distribuídas.
Para considerações adicionais sobre o uso de transações (como limite de tempo de execução e limite de tamanho do oplog), consulte também Considerações de produção.
Desconexão do cliente
A partir do MongoDB 4.2, se o cliente que emitiu db.collection.countDocuments() se desconectar antes da conclusão da operação, o MongoDB marcará db.collection.countDocuments() para encerramento usando killOp.
Exemplos
Contar todos os Documentos em uma Coleção
Para contar o número de documentos na coleção orders, utilize a seguinte operação:
db.orders.countDocuments( {}, { hint: "_id_"} )
Observação
Se você usar db.collection.countDocuments() com um filtro de consulta vazio, o MongoDB executará uma verificação de coleção completa que pode ser ineficiente. Para melhorar o desempenho, este exemplo especifica um hint() para usar o índice _id gerado automaticamente. Como alternativa, você pode usar um filtro de consulta que localiza todos os documentos, como { "_id": { $gte: MinKey } } para contar todos os documentos usando um índice.
Contagem de todos os Documentos que Correspondem a uma Query
Conte o número de documentos na coleção orders com o campo ord_dt maior que new
Date('01/01/2012'):
db.orders.countDocuments( { ord_dt: { $gt: new Date('01/01/2012') } }, { limit: 100 } )