Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/
Referência
/
Métodos de mongosh
/
Métodos de collection

db.collection.countDocuments()

Nesta página

  • Definição
  • Compatibilidade
  • Sintaxe
  • Comportamento
  • Exemplos

Definição

db.collection.countDocuments(query, options)

Importante

Método mongosh

Esta página documenta um método mongosh . Esta não é a documentação para comandos de banco de dados ou drivers específicos de idioma, como Node.js.

Para o comando de banco de dados, consulte o estágio de agregação $group e a expressão $sum chamada pelo comando aggregate.

Para drivers de API do MongoDB, consulte a documentação do driver MongoDB específica do idioma.

Para a documentação de shell legada do mongo, consulte a documentação para a versão correspondente do MongoDB Server:

mongo shell v4.4

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

Você pode utilizar o db.collection.countDocuments() para implantações hospedadas nos seguintes ambientes:

  • MongoDB Atlas: o serviço totalmente gerenciado para implantações MongoDB na nuvem

  • 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 formulário:

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
limit
inteiro
Opcional. O número máximo de documentos para contar.
skip
inteiro
Opcional. O número de documentos a serem ignorados antes da contagem.
hint
string ou documento
Opcional. Um nome de índice ou a especificação de índice a ser usada para a consulta.
maxTimeMS
inteiro
Opcional. A quantidade máxima de tempo para permitir a execução da contagem.

Comportamento

Mecânica

Ao contrário db.collection.count(), db.collection.countDocuments() não usa os metadados para retornar a contagem. Em vez disso, ele realiza uma agregação do documento para retornar uma contagem precisa, mesmo após um desligamento impróprio ou na presença de documentos órfãos em um cluster fragmentado.

db.collection.countDocuments() encapsula 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 visualização vazia ou inexistente.

Restrições de query

Você não pode utilizar os seguintes operadores de consulta como parte da expressão de consulta para db.collection.countDocuments():

Operador restrito
Alternativa
$where
Como alternativa, use $expr em vez disso.
$near

Como alternativa, use $geoWithin com $center; ou seja,

{ $geoWithin: { $center: [ [ <x>, <y> ], <radius> ] } }
$nearSphere

Como alternativa, use $geoWithin com $centerSphere; ou seja,

{ $geoWithin: { $centerSphere: [ [ <x>, <y> ], <radius> ] } }

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 filtra nenhuma transação de vários documentosnã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 , use a seguinte operação:

db.orders.countDocuments( {}, { hint: "_id_"} )

Observação

Se você usar db.collection.countDocuments() com um filtro de query vazio, o MongoDB executará uma varredura completa da collection, que pode ser ineficiente. Para melhorar o desempenho, este exemplo especifica um hint() para utilizar o índice _id gerado automaticamente. Como alternativa, você pode usar um filtro de query que encontra 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 } )

Dica

Veja também:

← db.collection.count()
db.collection.createIndex() →

Nesta página