/ /

Contagem de documentos

Visão geral

Neste guia, você pode aprender como usar a Biblioteca PHP MongoDB para recuperar uma contagem precisa e estimada do número de documentos em uma coleção. Os métodos a seguir contam documentos em uma collection:

MongoDB\Collection::countDocuments(): retorna o número exato de documentos que correspondem a um filtro de query ou que existem em uma coleção
MongoDB\Collection::estimatedDocumentCount(): retorna o número estimado de documentos em uma coleção

Dados de amostra

The examples in this guide use the companies collection in the sample_training database from the Atlas sample datasets. To access this collection from your PHP application, instantiate a MongoDB\Client that connects to an Atlas cluster and assign the following value to your $collection variable:

$collection = $client->sample_training->companies;

Para aprender a criar uma implantação gratuita do MongoDB e carregar os conjuntos de dados de amostra, consulte o guia Começar do MongoDB.

Recuperar uma contagem precisa

Use o método MongoDB\Collection::countDocuments() para contar o número de documentos em uma coleção. Para contar o número de documentos que correspondem a critérios de pesquisa específicos, passe um filtro de query para o método countDocuments() .

Para saber mais sobre como especificar uma query, consulte o guia Especificar uma Consulta .

Contagem de todos os documentos

Para retornar uma contagem de todos os documentos na collection, passe uma array de filtro de query vazia para o método countDocuments() , conforme mostrado no exemplo a seguir:

$result = $collection->countDocuments([]);
echo 'Number of documents: ', $result;

Contagem de documentos específicos

Para retornar uma contagem de documentos que correspondam a critérios de pesquisa específicos, passe um filtro de query para o método countDocuments() .

O exemplo a seguir conta o número de documentos em que o valor do campo founded_year é 2010:

$result = $collection->countDocuments(['founded_year' => 2010]);
echo 'Number of companies founded in 2010: ', $result;

Personalizar comportamento de contagem

Você pode modificar o comportamento do método countDocuments() passando uma array que especifica valores de opção. A tabela a seguir descreve algumas opções que você pode definir para personalizar a operação de contagem:

Opção	Descrição
`collation`	The collation to use for the operation. To learn more, see the Collation section of this page. Type: `array\|object`
`hint`	O índice a ser usado para a operação. Tipo: `string\|array\|object`
`comment`	O comentário a ser anexado à operação. Tipo: qualquer tipo BSON válido
`limit`	O número máximo de documentos para contar. Esse valor deve ser um número inteiro positivo. Tipo: `integer`
`maxTimeMS`	A quantidade máxima de tempo em milissegundos que a operação pode ser executada. Tipo: `integer`
`skip`	O número de documentos a serem ignorados antes de contar os documentos. Tipo: `integer`
`readPreference`	The read preference to use for the operation. To learn more, see Read Preference in the Server manual. Type: `MongoDB\Driver\ReadPreference`

O exemplo a seguir usa o método countDocuments() para contar o número de documentos nos quais o campo number_of_employees tem o valor 50 e instrui a operação a contar um máximo de 100 resultados:

$result = $collection->countDocuments(
    ['number_of_employees' => 50],
    ['limit' => 100],
);
echo 'Number of companies with 50 employees: ', $result;

Agrupamentos

Para especificar um agrupamento para sua operação, passe um parâmetro de array $options que defina a opção collation para o método de operação. Atribua a opção collation a uma array que configure as regras de agrupamento.

A tabela a seguir descreve os campos que você pode definir para configurar o agrupamento:

Campo	Descrição
`locale`	(Required) Specifies the International Components for Unicode (ICU) locale. For a list of supported locales, see Collation Locales and Default Parameters in the MongoDB Server manual. Data Type: `string`
`caseLevel`	(Opcional) Especifica se a comparação de caso deve ser incluída. Quando definido `true` como, o comportamento de comparação depende do valor do `strength` campo: - Se `strength` `1`for, a biblioteca PHP compara caracteres base e caso. - `strength` Se `2` for, a biblioteca PHP compara caracteres base, diacríticos, outras diferenças secundárias e caso. - Se `strength` for qualquer outro valor, este campo será ignorado. Quando definido como `false`, a biblioteca PHP não inclui comparação de caso no nível de força `1` ou `2`. Tipo de dados: `bool` Padrão: `false`
`caseFirst`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante comparações de nível terciário. Tipo de dados: `string` Padrão: `"off"`
`strength`	(Opcional) Especifica o nível de comparação a ser executado, conforme definido na documentação da ICU. Tipo de dados: `int` Padrão: `3`
`numericOrdering`	(Optional) Specifies whether the driver compares numeric strings as numbers. If set to `true`, the PHP library compares numeric strings as numbers. For example, when comparing the strings "10" and "2", the library uses the strings' numeric values and treats "10" as greater than "2". If set to `false`, the PHP library compares numeric strings as strings. For example, when comparing the strings "10" and "2", the library compares one character at a time and treats "10" as less than "2". For more information, see Collation Restrictions in the MongoDB Server manual. Data Type: `bool` Default: `false`
`alternate`	(Opcional) Especifica se a biblioteca considera espaços em branco e pontuação como caracteres base para fins de comparação. Tipo de dados: `string` Padrão: `"non-ignorable"`
`maxVariable`	(Opcional) Especifica quais caracteres a biblioteca considera ignoráveis quando o campo `alternate` é definido como `"shifted"`. Tipo de dados: `string` Padrão: `"punct"`
`backwards`	(Opcional) Especifica se as strings que contêm diacríticos são ordenadas da parte de trás da string para a frente. Tipo de dados: `bool` Padrão: `false`

Para saber mais sobre agrupamento e os possíveis valores para cada campo, consulte a entrada de Agrupamento no manual do MongoDB Server.

Recuperar uma contagem estimada

Você pode recuperar uma estimativa do número de documentos em uma coleção ligando para o método MongoDB\Collection::estimatedDocumentCount() . O método estima a quantidade de documentos com base nos metadados da collection, o que pode ser mais rápido do que realizar uma contagem precisa.

O exemplo a seguir estima o número de documentos em uma coleção:

$result = $collection->estimatedDocumentCount();
echo 'Estimated number of documents: ', $result;

Personalizar comportamento de contagem estimada

Você pode modificar o comportamento do método estimatedDocumentCount() passando uma array que especifique valores de opção como um parâmetro. A tabela a seguir descreve as opções que você pode definir na array:

Opção	Descrição
`comment`	O comentário a ser anexado à operação. Tipo: qualquer tipo BSON válido
`maxTimeMS`	A quantidade máxima de tempo em milissegundos que a operação pode ser executada. Tipo: `integer`
`readConcern`	The read concern to use for the operation. To learn more, see Read Concern in the Server manual. Type: `MongoDB\Driver\ReadConcern`
`readPreference`	The read preference to use for the operation. To learn more, see Read Preference in the Server manual. Type: `MongoDB\Driver\ReadPreference`
`session`	A sessão do cliente a ser associada à operação. Tipo: `MongoDB\Driver\Session`

O exemplo a seguir utiliza o método estimatedDocumentCount() para retornar uma estimativa do número de documentos na coleção e define um tempo limite de 1000 milissegundos na operação:

$result = $collection->estimatedDocumentCount(['maxTimeMS' => 1000]);
echo 'Estimated number of documents: ', $result;

Documentação da API

Para saber mais sobre qualquer um dos métodos ou tipos discutidos neste guia, consulte a seguinte documentação da API:

Voltar

Especificar uma query

Valores de campo distintos