MongoDB\GridFS\Bucket::findOne()

Definição

MongoDB\GridFS\Bucket::findOne()

Localiza um único documento da collection de arquivos do GridFS que corresponda à query.

function findOne(
    array|object $filter = [],
    array $options = []
): array|object|null

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	For queries against a sharded collection, returns partial results from the mongos if some shards are unavailable instead of throwing an error.
Codec	MongoDB\Codec\DocumentCodec	Os dados de codificação com codecs de tipo a serem usados para codificar ou decodificar documentos. Esta opção é mutuamente exclusiva com a opção typeMap. O padrão é o codec do bucket. A herança de uma opção codec padrão tem precedência sobre a da opção typeMap . Novidades na versão 1.17.
agrupamento	array|object	Collation allows users to specify language-specific rules for string comparison, such as rules for lettercase and accent marks. When specifying collation, the locale field is mandatory; all other collation fields are optional. For descriptions of the fields, see Collation Document.
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 a partir de MongoDB 4.4. As versões anteriores do servidor suportam apenas valores de string.
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. Novidades na 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. Novidades na versão 1.13.
max	array|object	O limite superior exclusivo para um índice específico. Novidades na versão 1.2.
maxScan	inteiro	Número máximo de documentos ou chaves de índice a serem verificadas ao executar a consulta. Obsoleto desde a versão 1.4. Novidades na 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. Novidades na 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.
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> } } A referência da classe MongoDB\BSON\Timestamp descreve como representar o tipo de registro de data/hora BSON do MongoDB com PHP. Obsoleto 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	Read concern a ser usada para a operação. O padrão é a read concern do bucket. Não é possível especificar uma read concern 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 do bucket.
returnKey	booleano	Se verdadeiro, retorna apenas as chaves de índice nos documentos resultantes. Novidades na versão 1.2.
session	MongoDB\Driver\Session	Sessão do cliente a ser associada à operação. Novidades 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. Novidades na 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.
typeMap	array	O mapa de tipo a aplicar aos cursores, que determina como os documentos BSON são convertidos em valores PHP. O padrão é o mapa de tipos do bucket. Isso será usado para o documento de resultado retornado.

Return Values

An array or object for the first document that matched the query, or null if no document matched the query. The return type will depend on the typeMap option.

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, o MongoDB compara tipos e valores de acordo com suas próprias regras de comparação para tipos BSON, o que difere das regras de comparação e malabarismo de tipos do PHP. 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

<?php
$bucket = (new MongoDB\Client)->test->selectGridFSBucket();
$stream = fopen('php://temp', 'w+b');
fwrite($stream, "foobar");
rewind($stream);
$bucket->uploadFromStream('b', $stream);
$fileDocument = $bucket->findOne(
    ['length' => ['$lte' => 6]],
    [
        'projection' => [
            'filename' => 1,
            'length' => 1,
            '_id' => 0,
        ],
        'sort' => ['length' => -1],
    ]
);
var_dump($fileDocument);

A saída seria então semelhante a:

object(MongoDB\Model\BSONDocument)#3004 (1) {
  ["storage":"ArrayObject":private]=>
  array(2) {
    ["filename"]=>
    string(1) "b"
    ["length"]=>
    int(6)
  }
}

Veja também

• MongoDB\Collection::findOne()

• MongoDB\GridFS\Bucket::find()