db.coleção.countDocuments() (método mongosh)

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:

C#Java Sync Node.js PyMongo C C++Go Java RS Kotlin Coroutine Kotlin Sync PHP Motor Rust Scala

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

db.collection.countDocuments( <query>, <options> )

Parâmetros

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. Consultetambé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() de, 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 impuro ou na presença de documentos órfãos em um cluster fragmentado.

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

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 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

countDocuments() pode ser usado dentro de transações distribuídas.

Quando você usa 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

Se o cliente que emitiu countDocuments() se desconectar antes da conclusão da operação, o MongoDB marcará countDocuments() para encerramento killOp usando.

Exemplos

Os exemplos nesta página usam dados do conjunto de dados de amostra sample_mflix. Para obter detalhes sobre como carregar esse conjunto de dados em sua implantação autogerenciada do MongoDB , consulte Carregar o conjunto de dados de amostra. Se você fez modificações nos bancos de dados de amostra, talvez seja necessário descartar e recriar os bancos de dados para executar os exemplos nesta página.

Contar todos os Documentos em uma Coleção

Para contar o número de documentos na coleção movies, utilize a seguinte operação:

db.movies.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

Este exemplo conta o número de documentos na collection movies em que o campo directors contém "David Lynch":

db.movies.countDocuments( { directors: "David Lynch" } )

Saiba mais

Voltar

db.collection.count

db.collection.createIndex