/ /

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 usam a collection companies no banco de dados sample_training dos conjuntos de banco 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 aprender como criar uma implantação gratuita do MongoDB e carregar os conjuntos de dados de amostra, consulte o Guia de introdução 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;

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`	O agrupamento a ser usado para a operação. Para saber mais, consulte a seção Agrupamento desta página. Tipo: `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 de 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 executar. Tipo: `integer`
`skip`	O número de documentos a ignorar antes de contar os documentos. Tipo: `integer`
`readPreference`	A preferência de leitura a ser usada na operação. Para saber mais, consulte Preferência de leitura no manual do servidor. Tipo: `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`	(Obrigatório) Especifica a locale { components internacionais para Unicode} (ICU). Para obter uma lista de localidades suportadas, consulte Localidades de Agrupamento e Parâmetros Padrão no manual do MongoDB Server . Tipo de dados: `string`
`caseLevel`	(Opcional) Especifica se incluir comparação de caso. Quando definido `true` como, o comportamento de comparação depende do valor do `strength` campo : - Se `strength` `1`for, a biblioteca PHP compara caracteres básicos e maiúsculas e minúsculas. - `strength` Se `2` for, a biblioteca PHP compara caracteres básicos, diacríticos, outras diferenças secundárias e maiúsculas e minúsculas. - Se `strength` for qualquer outro valor, este campo será ignorado. Quando definida `false` como, a biblioteca PHP não inclui a comparação de caso no nível `1` de força `2` ou. Tipo de Dados: `bool` Padrão: `false`
`caseFirst`	(Opcional) Especifica a ordem de classificação das diferenças de caso durante as 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`	(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 que "2". 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 que "2". 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 o espaço em branco e a pontuação como caracteres básicos 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 `alternate` campo é definido `"shifted"` como. Tipo de dados: `string` Padrão: `"punct"`
`backwards`	(Opcional) Especifica se as strings contendo diacríticos são classificadas 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;

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`	O comentário a ser anexado à operação. Tipo: qualquer tipo de BSON válido
`maxTimeMS`	A quantidade máxima de tempo em milissegundos que a operação pode executar. Tipo: `integer`
`readConcern`	A preocupação de leitura a ser usada para a operação. Para saber mais, consulte Read Concern no manual do Servidor. Tipo: `MongoDB\Driver\ReadConcern`
`readPreference`	A preferência de leitura a ser usada na operação. Para saber mais, consulte Preferência de leitura no manual do servidor. Tipo: `MongoDB\Driver\ReadPreference`
`session`	A sessão do cliente para associar à 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;

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