/ /

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`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: `int` Default: `3`
`numericOrdering`	(Opcional) Especifica se o driver compara strings numéricas como números. Se definido `true` como, a biblioteca PHP compara strings numéricas como números. Por exemplo, ao comparar as strings "10" e "2", a biblioteca usa os valores numéricos das strings e trata "10" como maior que2 "". Se configurado `false` para, a biblioteca PHP compara strings numéricas como strings. Por exemplo, ao comparar as strings "10" e "2", a biblioteca compara um caractere de cada vez e trata "10" como menor que2 "". Para obter mais informações, consulte Restrições de agrupamento no manual do MongoDB Server . Tipo de dados: `bool` Padrão: `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