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

Os exemplos neste guia utilizam a coleção do companies no banco de dados de dados do sample_training a partir dos conjuntos de dados de amostra do Atlas. Para acessar essa coleção a partir do seu aplicação PHP , instancie um MongoDB\Client que se conecte a um Atlas cluster e atribua o seguinte valor à sua variável $collection :

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

Para saber como criar um cluster MongoDB Atlas gratuito e carregar os conjuntos de dados de amostra, consulte o guia Iniciar com Atlas .

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

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;

Number of documents: 9500

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;

Number of companies founded in 2010: 33

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`	The index to use for the operation. Type: `string\|array\|object`
`comment`	The comment to attach to the operation. Type: any valid BSON type
`limit`	The maximum number of documents to count. This value must be a positive integer. Type: `integer`
`maxTimeMS`	The maximum amount of time in milliseconds that the operation can run. Type: `integer`
`skip`	The number of documents to skip before counting documents. Type: `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;

Number of companies with 50 employees: 100

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`	(Optional) Specifies whether to include case comparison. When set to `true`, the comparison behavior depends on the value of the `strength` field: - If `strength` is `1`, the PHP library compares base characters and case. - If `strength` is `2`, the PHP library compares base characters, diacritics, other secondary differences, and case. - If `strength` is any other value, this field is ignored. When set to `false`, the PHP library doesn't include case comparison at strength level `1` or `2`. Data Type: `bool` Default: `false`
`caseFirst`	(Optional) Specifies the sort order of case differences during tertiary level comparisons. Data Type: `string` Default: `"off"`
`strength`	(Optional) Specifies the level of comparison to perform, as defined in the ICU documentation. Data Type: `int` Default: `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`	(Optional) Specifies whether the library considers whitespace and punctuation as base characters for comparison purposes. Data Type: `string` Default: `"non-ignorable"`
`maxVariable`	(Optional) Specifies which characters the library considers ignorable when the `alternate` field is set to `"shifted"`. Data Type: `string` Default: `"punct"`
`backwards`	(Optional) Specifies whether strings containing diacritics sort from the back of the string to the front. Data Type: `bool` Default: `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;

Estimated number of documents: 9500

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`	The comment to attach to the operation. Type: any valid BSON type
`maxTimeMS`	The maximum amount of time in milliseconds that the operation can run. Type: `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`	The client session to associate with the operation. Type: `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;

Estimated number of documents: 9500

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