Página inicial do Docs → Manual da Biblioteca PHP
MongoDB\Collection::findOne()
Definição
Parâmetros
$filter
: array|object- Os critérios de filtro que especificam os documentos para consulta.
$options
: arrayUm array especificando as opções desejadas.
NomeTipoDescriçãoPermitir o uso do discoboleanoPermite gravar em arquivos temporários. Ao definir comotrue
, as consultas podem gravar dados no subdiretório_tmp
no diretóriodbPath
.allowPartialResultsboleanoPara consultas em relação a uma coleção fragmentada, retorna resultados parciais domongos
se alguns fragmentos não estiverem disponíveis em vez de lançar um erro.codecMongoDB\Codec\DocumentCodecO codec 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çãotypeMap
.Novidade na versão 1.17.
Agrupamentoarray|objectA colocação permite que os usuários especifiquem regras específicas do idioma para comparação de strings, 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 collection tiver um agrupamento padrão, a operação usará o agrupamento especificado para a collection. Se nenhum agrupamento for especificado para a collection ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de string.
comentáriomistoPermite que os usuários especifiquem um comentário arbitrário para ajudar a rastrear a operação por meio do analisador de banco de dados, da saída currentOp e dos logs.
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.
dicastring|array|objetoO í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.
deixeiarray|objectMapa 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.
maxarray|objectO limite superior exclusivo para um índice específico.
Novidade da versão 1.2.
maxScaninteiroNú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.
maxTimeMSinteiroO limite de tempo cumulativo em milissegundos para operações de processamento no cursor. O MongoDB cancela a operação no primeiro ponto de interrupção seguinte.
minarray|objectO limite inferior inclusivo para um índice específico.
Novidade da versão 1.2.
modificadoresarray|objectMeta-operadores que modificam a saída ou o comportamento de uma consulta. O uso desses operadores é preterido em favor de opções nomeadas.oplogReplayboleanoUso 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çãoarray|objectA especificação de projeção para determinar quais campos incluir nos documentos devolvidos. Consulte Campos do projeto para retornar da query e Operadores de projeção no manual do MongoDB.readConcernPreocupaçã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 questão de leitura para operações individuais como parte de uma transação. Em vez disso, defina a
readConcern
opção ao iniciar a transação.readPreferencePreferência de leitura a ser usada na operação. O padrão é a preferência de leitura da coleção.
returnKeyboleanoSe verdadeiro, retorna apenas as chaves de índice nos documentos resultantes.
Novidade da versão 1.2.
sessionSessão do cliente a ser associada à operação.
Novidade na versão 1.3.
showRecordIdboleanoDetermina 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.
ignorarinteiroNúmero de documentos a ignorar. Padrão é0
.sortarray|objectA especificação de classificação para a ordenação dos resultados.typeMapvariedadeO mapa de tipos aplicar aos cursores, o que determina como os documentos BSON são convertidos em valores PHP. O padrão é o mapa de tipos da coleção.
Isso será usado para o documento de resultado retornado.
Valores de retorno
Um array ou objeto para o primeiro documento que correspondeu à query ou null
se nenhum documento correspondeu à query. O tipo de retorno depende da opção typeMap
.
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 do driver (por exemplo, erros de conexão).
Comportamento
Ao avaliar critérios de query, o MongoDB compara tipos e valores de acordo com suas próprias regras de comparação para tipos BSON, o que difere da comparação do PHP e digite malabarismo regras. Ao corresponder a um tipo BSON especial, os critérios de query devem usar a respectiva classe BSON no driver (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um ObjectId).
Exemplos
Correspondência de tipos de BSON em critérios de query
No exemplo a seguir, documentos na restaurants
collection usam um ObjectId para seu identificador (o padrão), e documentos na zips
collection usam uma string. Como ObjectId é um tipo de BSON especial, os critérios da query para selecionar um restaurante devem usar o método MongoDB\BSON\ObjectId aula.
$database = (new MongoDB\Client)->test; $zip = $database->zips->findOne(['_id' => '10036']); $restaurant = $database->restaurants->findOne([ '_id' => new MongoDB\BSON\ObjectId('594d5ef280a846852a4b3f70'), ]);
Campos de projeção
O exemplo a seguir encontra um restaurante com base nos cuisine
e borough
uma projeção para limitar os campos retornados.
$collection = (new MongoDB\Client)->test->restaurants; $restaurant = $collection->findOne( [ 'cuisine' => 'Italian', 'borough' => 'Manhattan', ], [ 'projection' => [ 'name' => 1, 'borough' => 1, 'cuisine' => 1, ], ] ); 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" } }
Veja também
encontrar referência de comando no manual do MongoDB