MongoDB\Collection::find()

Definição

MongoDB\Collection::find()

Localiza documentos correspondentes à consulta.

function find(
    array|object $filter = [],
    array $options = []
): MongoDB\Driver\Cursor

Parâmetros

$filter : array|object

Os critérios de filtro que especificam os documentos para consulta.

$options : array

Uma array especificando as opções desejadas.

Nome	Tipo	Descrição
allowDiskUse	booleano	Permite gravar em arquivos temporários. Ao definir como true, as consultas podem gravar dados no subdiretório _tmp no diretório dbPath.
allowPartialResults	booleano	Para consultas em relação a uma coleção fragmentada, retorna resultados parciais do mongos se alguns fragmentos não estiverem disponíveis em vez de lançar um erro.
batchSize	inteiro	O número de documentos a retornar no primeiro lote. O padrão é 101. Um batchSize de 0 significa que o cursor será estabelecido, mas nenhum documento será retornado no primeiro lote. Ao contrário da versão anterior do protocolo de conexão, um tamanho de lote 1 para o comando find não fecha o cursor.
Codec	MongoDB\Codec\DocumentCodec	Ocodec a ser usado para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção typeMap . O padrão é o codec da coleção. A herança de uma opção codec padrão tem precedência sobre a da opção typeMap. Novidade na versão 1.17.
agrupamento	array|object	A colocação permite que os usuários especifiquem regras específicas do idioma para comparação de string , como regras para letras maiúsculas e marcas de acento. Ao especificar agrupamento, o campo locale é obrigatório; todos os outros campos de agrupamento são opcionais. Para obter descrições dos campos, consulte Documento de agrupamento. Se o agrupamento não for especificado, mas a coleção tiver um agrupamento padrão, a operação usará o agrupamento especificado para a coleção. Se nenhum agrupamento for especificado para a coleção nem para a operação, o MongoDB usará a comparação binária simples usada nas versões anteriores para comparações de strings.
comment	misto	Permite ao usuário especificar um comentário arbitrário para ajudar a rastrear a operação por meio do profiler de banco de dados, da saída currentOp e dos registros. O comentário pode ser qualquer tipo de BSON válido desde o MongoDB 4.4. As versões anteriores do servidor suportam apenas valores de string.
cursorType	inteiro	Indica o tipo de cursor a ser usado. O cursorType suporta os seguintes valores: MongoDB\Operation\Find::NON_TAILABLE (padrão) MongoDB\Operation\Find::TAILABLE
dica	string|array|objeto	O índice a ser utilizado. Especifique o nome do índice como uma string ou o padrão da chave do índice como um documento. Se especificado, o sistema de query considerará apenas os planos usando o índice sugerido. Novidade da versão 1.2.
let	array|object	Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não façam referência aos campos do documento. Os parâmetros podem ser acessados como variáveis em um contexto de expressão agregada (como $$var). Isto não é suportado para versões de servidor anteriores à 5.0 e resultará em uma exceção no tempo de execução se utilizado. Novidade na versão 1.13.
limit	inteiro	O número máximo de documentos a retornar. Se não for especificado, o padrão será sem limite. Um limite de 0 é equivalente a não definir nenhum limite. Um limite negativo é semelhante a um limite positivo, mas fecha o cursor após retornar um único lote de resultados. Dessa forma, com um limite negativo, se o conjunto limitado não couber em um único lote, o número de documentos recebidos será menor do que o limite especificado. Ao passar um limite negativo, o cliente indica ao servidor que não solicitará um lote subsequente por meio do getMore.
max	array|object	O limite superior exclusivo para um índice específico. Novidade da versão 1.2.
maxAwaitTimeMS	inteiro	Inteiro positivo que indica o limite de tempo em milissegundos para o servidor bloquear uma operação getMore se nenhum dado estiver disponível. Essa opção só deve ser usada se cursorType for TAILABLE_AWAIT. Novidade da versão 1.2.
maxScan	inteiro	Número máximo de documentos ou chaves de índice a serem verificadas ao executar a consulta. Descontinuado desde a versão 1.4. Novidade da versão 1.2.
maxTimeMS	inteiro	O limite de tempo cumulativo em milésimos de segundo para operações de processamento no cursor. O MongoDB aborta a operação o mais cedo possível após o ponto de interrupção.
min	array|object	O limite inferior inclusivo para um índice específico. Novidade da versão 1.2.
modifiers	array|object	Meta-operadores que modificam a saída ou o comportamento de uma consulta. O uso desses operadores é preterido em favor de opções nomeadas.
noCursorTimeout	booleano	Impede que o servidor atinja o tempo limite de cursores ociosos após um período de inatividade (10 minutos).
oplogReplay	booleano	Uso interno para conjuntos de réplicas. Para usar o oplogReplay, você deve incluir a seguinte condição no filtro: { ts: { $gte: <timestamp> } } O MongoDB\BSON\Timestamp referência de classe descreve como representar o tipo de registro de data e hora BSON do MongoDB com PHP. Descontinuado desde a versão 1.7.
projeção	array|object	A especificação da projeção para determinar quais campos incluir nos documentos devolvidos. Consulte Campos do projeto para retornar da consulta e Operadores de projeção no manual do MongoDB.
readConcern	MongoDB\Driver\ReadConcern	Preocupação de leitura a ser usada para a operação. O padrão é a preocupação de leitura da coleção. Não é possível especificar uma preocupação de leitura para operações individuais como parte de uma transação. Em vez disso, defina a opção readConcern ao iniciar a transação.
readPreference	MongoDB\Driver\ReadPreference	Preferência de leitura a ser usada na operação. O padrão é a preferência de leitura da coleção.
returnKey	booleano	Se verdadeiro, retorna apenas as chaves de índice nos documentos resultantes. Novidade da versão 1.2.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidade na versão 1.3.
showRecordId	booleano	Determina se o identificador de registro de cada documento deve ser retornado. Se for verdadeiro, adiciona um campo $recordId aos documentos retornados. Novidade da versão 1.2.
ignorar	inteiro	Número de documentos a ignorar. O padrão é 0.
sort	array|object	A especificação de classificação para a ordenação dos resultados.
snapshot	booleano	Impede que o cursor retorne um documento mais de uma vez devido a uma operação de gravação interveniente. Descontinuado desde a versão 1.4. Novidade da versão 1.2.
typeMap	array	O mapa de tipos para aplicar aos cursores, que determina como os documentos BSON são convertidos para valores PHP. O padrão é o mapa de tipos da coleção.

Return Values

Um MongoDB\Driver\Cursor objeto.

Erros/exceções

MongoDB\Exception\UnsupportedException se as opções forem usadas e não aceitas pelo servidor selecionado (p. ex., collation, readConcern, writeConcern).

MongoDB\Exception\InvalidArgumentException para erros relacionados à análise de parâmetros ou opções.

MongoDB\Driver\Exception\RuntimeException para outros erros no nível da extensão (por exemplo erros de conexão).

Comportamento

Ao avaliar critérios de query, oMongoDB compara tipos e valores de acordo com suas próprias regras de comparação para BSON types, o que difere da comparação do e digite PHP malabarismo regras. Ao corresponder a um tipo BSON especial, os critérios de query devem usar a respectiva classe BSON na extensão (por exemplo use MongoDB\BSON\ObjectId para corresponder a um ObjectId).

Exemplos

O exemplo a seguir encontra restaurantes com base nos cuisine e borough uma projeção para limitar os campos retornados. Também limita os resultados a 5 documentos.

<?php
$collection = (new MongoDB\Client)->test->restaurants;
$cursor = $collection->find(
    [
        'cuisine' => 'Italian',
        'borough' => 'Manhattan',
    ],
    [
        'limit' => 5,
        'projection' => [
            'name' => 1,
            'borough' => 1,
            'cuisine' => 1,
        ],
    ]
);
foreach ($cursor as $restaurant) {
   var_dump($restaurant);
};

A saída seria então semelhante a:

object(MongoDB\Model\BSONDocument)#10 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#8 (1) {
      ["oid"]=>
      string(24) "576023c6b02fa9281da3f983"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["cuisine"]=>
    string(7) "Italian"
    ["name"]=>
    string(23) "Isle Of Capri Resturant"
  }
}
object(MongoDB\Model\BSONDocument)#13 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#12 (1) {
      ["oid"]=>
      string(24) "576023c6b02fa9281da3f98d"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["cuisine"]=>
    string(7) "Italian"
    ["name"]=>
    string(18) "Marchis Restaurant"
  }
}
object(MongoDB\Model\BSONDocument)#8 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#10 (1) {
      ["oid"]=>
      string(24) "576023c6b02fa9281da3f99b"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["cuisine"]=>
    string(7) "Italian"
    ["name"]=>
    string(19) "Forlinis Restaurant"
  }
}
object(MongoDB\Model\BSONDocument)#12 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#13 (1) {
      ["oid"]=>
      string(24) "576023c6b02fa9281da3f9a8"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["cuisine"]=>
    string(7) "Italian"
    ["name"]=>
    string(22) "Angelo Of Mulberry St."
  }
}
object(MongoDB\Model\BSONDocument)#10 (1) {
  ["storage":"ArrayObject":private]=>
  array(4) {
    ["_id"]=>
    object(MongoDB\BSON\ObjectId)#8 (1) {
      ["oid"]=>
      string(24) "576023c6b02fa9281da3f9b4"
    }
    ["borough"]=>
    string(9) "Manhattan"
    ["cuisine"]=>
    string(7) "Italian"
    ["name"]=>
    string(16) "V & T Restaurant"
  }
}

Veja também

• MongoDB\Collection::findOne()

• encontrar referência de comando no manual do MongoDB