MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Constrói uma nova consulta

Descrição

final public MongoDB\Driver\Query::__construct(array|object $filter, ?array $queryOptions = null)

Constrói um novo MongoDB\Driver\Query, que é um objeto de valor imutável que representa uma consulta ao banco de dados. A consulta pode então ser executada com MongoDB\Driver\Manager::executeQuery().

Parâmetros

filter (array|object)

O » predicado de consulta. Um predicado vazio corresponderá a todos os documentos da coleção.

Note: Ao avaliar os critérios de consulta, o MongoDB compara os tipos e valores de acordo com suas próprias » regras de comparação para tipos BSON, que diferem das regras de comparação e do malabarismo de tipos do PHP. Ao corresponder a um tipo especial de BSON, os critérios de consulta devem usar a respectiva classe BSON (por exemplo, use MongoDB\BSON\ObjectId para corresponder a um » ObjectId).

queryOptions

**queryOptions**
Opção	Tipo	Descrição
allowDiskUse	bool	Permite que o MongoDB use arquivos de disco temporários para armazenar dados que excedem o limite de memória do sistema de 100 megabytes durante o processamento de uma operação bloqueante de classificação.
allowPartialResults	bool	Para consultas em uma coleção de fragmentos, retorna resultados parciais do "mongos" se alguns fragmentos não estiverem disponíveis, em vez de lançar um erro. Se não especificada, a opção obsoleta `"partial"` será usada.
awaitData	bool	Use em conjunto com a opção `"tailable"` para bloquear temporariamente uma operação getMore no cursor se estiver no final dos dados, em vez de não retornar nenhum dado. Após um período de tempo limite, a consulta retorna normalmente.
batchSize	int	O número de documentos a serem devolvidos no primeiro lote. O padrão é 101. Um tamanho de lote 0 significa que o cursor será estabelecido, mas nenhum documento será retornado no primeiro lote. Nas versões do MongoDB anteriores à 3.2, onde as consultas usam o protocolo de ligação legado OP_QUERY, um tamanho de lote de 1 fechará o cursor, independentemente do número de documentos correspondidos.
collation	array\|object	» Collation permite que os usuários especifiquem regras específicas do idioma para comparação de strings, como regras para maiúsculas e minúsculas e acentos. Ao especificar a collation, o campo `"locale"` é obrigatório; todos os outros campos de collation são opcionais. Para obter descrições dos campos, veja o » Documento de Collation. Se a collation não for especificada, mas a coleção tiver uma collation padrão, a operação usará a collation especificada para a coleção. Se nenhuma collation for especificada para a coleção ou para a operação, o MongoDB usará a comparação binária simples usada em versões anteriores para comparações de strings. Esta opção está disponível no MongoDB 3.4+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
comment	mixed	Um comentário arbitrário para ajudar a rastrear a operação por meio do perfilador do banco de dados, da saída currentOp e dos logs. O comentário pode ser qualquer tipo BSON válido para MongoDB 4.4+. Versões anteriores do servidor suportam apenas valores de string. Se não especificada, o modificador obsoleto `"$comment"` será utilizado.
exhaust	bool	Transmite os dados a todo vapor em vários pacotes "more", supondo que o cliente lerá completamente todos os dados consultados. Mais rápido quando se está extraindo muitos dados e sabe-se que a intenção é extrair tudo. Nota: o cliente não tem permissão para não ler todos os dados, a menos que feche a conexão. Esta opção não é suportada pelo comando "find" no MongoDB 3.2+ e forçará o driver a usar a versão herdada do protocolo de ligação (ou seja, OP_QUERY).
explain	bool	Se `true`, o MongoDB\Driver\Cursor retornado conterá um único documento que descreve o processo e os índices usados para retornar a consulta. Se não especificada, o modificador obsoleto `"$explain"` será utilizado. Esta opção não é suportada pelo comando "find" no MongoDB 3.2+ e só será respeitada ao usar a versão herdada do protocolo wire (ou seja, OP_QUERY). O comando » explain deve ser usado no MongoDB 3.0+.
hint	string\|array\|object	Especificação do índice. Especifique o nome do índice como uma string ou o padrão de chave do índice. Se especificado, o sistema de consulta considerará apenas os planos usando o índice sugerido. Se não especificada, a opção obsoleta `"hint"` será utilizada.
let	array\|object	Mapa de nomes e valores de parâmetros. Os valores devem ser expressões constantes ou fechadas que não fazem referência a campos do documento. Os parâmetros podem então ser acessados como variáveis em um contexto de expressão agregada (por exemplo, `$$var`). Esta opção está disponível no MongoDB 5.0+ e resultará em uma exceção em tempo de execução se for especificada para uma versão de servidor mais antiga.
limit	int	O número máximo de documentos a serem devolvidos. Se não for especificado, o padrão será sem limite. Um limite de 0 é equivalente a não definir limite. Um limite negativo será interpretado como um limite positivo com a opção `"singleBatch"` definida como `true`. Este comportamento é suportado para compatibilidade com versões anteriores, mas deve ser considerado obsoleto.
max	array\|object	O limite superior exclusivo para um índice específico. Se não especificada, o modificador obsoleto `"$max"` será utilizado.
maxAwaitTimeMS	int	Inteiro positivo que indica o limite de tempo em milissegundos para o servidor bloquear uma operação "getMore" se nenhum dado estiver disponível. Esta opção só deve ser usada em conjunto com as opções `"tailable"` e `"awaitData"`.
maxScan	int	Warning Esta opção está obsoleta e não deve ser usada. Inteiro positivo que indica o número máximo de documentos ou chaves de índice a serem verificados ao executar a consulta. Se não especificada, o modificador obsoleto `"$maxScan"` será utilizado.
maxTimeMS	int	O limite de tempo cumulativo em milissegundos 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. Se não especificada, o modificador obsoleto `"$maxTimeMS"` será utilizado.
min	array\|object	O limite inferior (inclusive) para um índice específico. Se não especificada, o modificador obsoleto `"$min"` será utilizado.
modifiers	array	» Metaoperadores que modificam a saída ou o comportamento de uma consulta. O uso desses operadores está preterido em favor de opções nomeadas.
noCursorTimeout	bool	Impede que o servidor expire os cursores ociosos após um período de inatividade (10 minutos).
oplogReplay	bool	Uso interno para conjuntos de réplicas. Para usar o oplogReplay, é necessário incluir a seguinte condição no filtro: [ 'ts' => [ '$gte' => <timestamp> ] ] Note: Esta opção está obsoleta a partir da versão 1.8.0.
projection	array\|object	A » especificação de projeção para determinar quais campos devem ser incluídos nos documentos retornados. Se a funcionalidade ODM estiver sendo usada para desserializar documentos como sua classe PHP original, deve-se incluir o campo __pclass na projeção. Isso é necessário para que a desserialização funcione e, sem ela, a extensão retornará (por padrão) um objeto stdClass no lugar.
readConcern	MongoDB\Driver\ReadConcern	Uma preocupação de leitura a ser aplicada à operação. Por padrão, a preocupação de leitura do URI de conexão do MongoDB será usada. Esta opção está disponível no MongoDB 3.2+ e resultará em uma exceção no momento da execução se especificada para uma versão mais antiga do servidor.
returnKey	bool	Se `true`, retornará apenas as chaves de índice nos documentos resultantes. O valor padrão é `false`. Se `true` e o comando "find" não usar um índice, os documentos retornados estarão vazios. Se não especificada, o modificador obsoleto `"$returnKey"` será utilizado.
showRecordId	bool	Determina se o identificador de registro para cada documento deve ser retornado. Se `true`, adiciona um campo `"$recordId"` de nível superior aos documentos retornados. Se não especificada, o modificador obsoleto `"$showDiskLoc"` será utilizado.
singleBatch	bool	Determina se o cursor deve ser fechado após o primeiro lote. O padrão é `false`.
skip	int	Número de documentos a serem ignorados. O padrão é 0.
snapshot	bool	Warning Esta opção está obsoleta e não deve ser usada. Impede que o cursor retorne um documento mais de uma vez devido a uma operação de gravação interveniente. Se não especificada, o modificador obsoleto `"$snapshot"` será utilizado.
sort	array\|object	A especificação de classificação para a ordenação dos resultados. Se não especificada, o modificador obsoleto `"$orderby"` será utilizado.
tailable	bool	Retorna um cursor adaptável para uma coleção limitada.

Erros/Exceções

Lança uma exceção MongoDB\Driver\Exception\InvalidArgumentException em caso de erro ao analisar argumentos.

Registro de Alterações

Versão	Descrição
PECL mongodb 1.14.0	Adicionada a opção `"let"` A opção `"comment"` agora aceita qualquer tipo.
PECL mongodb 1.8.0	Adicionada a opção `"allowDiskUse"`. A opção `"oplogReplay"` tornou-se obsoleta.
PECL mongodb 1.5.0	As opções `"maxScan"` e `"snapshot"` tornaram-se obsoletas.
PECL mongodb 1.3.0	Adicionada a opção `"maxAwaitTimeMS"`.
PECL mongodb 1.2.0	Adicionadas as opções `"allowPartialResults"`, `"collation"`, `"comment"`, `"hint"`, `"max"`, `"maxScan"`, `"maxTimeMS"`, `"min"`, `"returnKey"`, `"showRecordId"` e `"snapshot"`. A opção `"partial"` foi renomeada para `"allowPartialResults"`. Para compatibilidade com versões anteriores, `"partial"` ainda será lida se `"allowPartialResults"` não for especificada. Removida a opção legada `"secondaryOk"`, que está obsoleta. Para consultas usando o protocolo de conexão legado OP_QUERY, o driver definirá o bit `secondaryOk` conforme necessário, de acordo com a » Especificação de Seleção de Servidor.
PECL mongodb 1.1.0	Adicionada a opção `"readConcern"`.

Exemplos

Example #1 Exemplo de MongoDB\Driver\Query::__construct()

<?php
/* Seleciona apenas os documentos de autoria de "bjori" com pelo menos 100 visualizações */
$filter = [
    'author' => 'bjori',
    'views' => [
        '$gte' => 100,
    ],
];

$options = [
    /* Retorna somente os campos a seguir nos documentos correspondentes */
    'projection' => [
        'title' => 1,
        'article' => 1,
    ],
    /* Retorna os documentos na ordem descendente de visualizações */
    'sort' => [
        'views' => -1
    ],
];

$query = new MongoDB\Driver\Query($filter, $options);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
$cursor = $manager->executeQuery('databaseName.collectionName', $query, $readPreference);

foreach($cursor as $document) {
    var_dump($document);
}

?>

Veja Também

MongoDB\Driver\Manager::executeQuery() - Executa uma consulta ao banco de dados
MongoDB\Driver\Cursor