Especificar uma query

Visão geral

Neste guia, você pode aprender como especificar uma query usando a biblioteca PHP do MongoDB .

Você pode refinar o conjunto de documentos que uma query retorna criando um filtro de query. Um filtro de query é uma expressão que especifica os critérios de pesquisa que o MongoDB usa para corresponder a documentos em uma operação de leitura ou gravação. Em um filtro de query, você pode solicitar ao driver que pesquise documentos que tenham uma correspondência exata à sua query ou pode compor filtros de query para Express critérios de correspondência mais complexos.

$uri = '<connection string>';
$client = new Client($uri);
$collection = $client->db->fruits;
// Inserts documents representing fruits
$fruits = [
    [
        '_id' => 1,
        'name' => 'apples',
        'qty' => 5,
        'rating' => 3,
        'color' => 'red',
        'type' => ['fuji', 'honeycrisp']
    ],
    [
        '_id' => 2,
        'name' => 'bananas',
        'qty' => 7,
        'rating' => 4,
        'color' => 'yellow',
        'type' => ['cavendish']
    ],
    [
        '_id' => 3,
        'name' => 'oranges',
        'qty' => 6,
        'rating' => 2,
        'type' => ['naval', 'mandarin']
    ],
    [
        '_id' => 4,
        'name' => 'pineapples',
        'qty' => 3,
        'rating' => 5,
        'color' => 'yellow'
    ]
];
$result = $collection->insertMany($fruits);

Correspondência exata

Consultas de valor literal retornam documentos que têm uma correspondência exata ao seu filtro de consulta.

O exemplo seguinte especifica um filtro de consulta como um parâmetro para o método MongoDB\Collection::find() . O código retorna todos os documentos em que o valor do campo color é 'yellow':

$cursor = $collection->find(['color' => 'yellow']);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}

$cursor = $collection->find([]);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

Operadores de comparação

Os operadores de comparação avaliam um valor de campo de documento em relação a um valor especificado em seu filtro de query. A seguinte lista define operadores de comparação comuns:

• $gt: Maior que

• $lte: Menor ou Igual

• $ne: Diferente

Para visualizar uma lista completa de operadores de comparação, consulte o guia Operadores de query de comparação no manual do MongoDB Server .

O exemplo a seguir especifica um operador de comparação em um filtro de query como um parâmetro para o método MongoDB\Collection::find() . O código retorna todos os documentos em que o valor do campo rating é maior que 2:

$cursor = $collection->find(['rating' => ['$gt' => 2]]);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}

Operadores lógicos

Os operadores lógicos correspondem aos documentos usando lógica aplicada aos resultados de dois ou mais conjuntos de expressões. A lista a seguir descreve cada operador lógico:

• $and: retorna todos os documentos que correspondem às condições de todas as cláusulas

• $or: retorna todos os documentos que correspondem às condições de uma cláusula

• $nor: Retorna todos os documentos que não correspondem às condições de nenhuma cláusula

• $not: retorna todos os documentos que não correspondem à expressão

Para saber mais sobre operadores lógicos, consulte o guia Operadores lógicos de query no manual do MongoDB Server .

O exemplo seguinte especifica um operador lógico em um filtro de query como um parâmetro para o método MongoDB\Collection::find() . O código retorna todos os documentos em que o valor do campo qty é maior que 5 ou o valor do campo color é 'yellow':

$cursor = $collection->find([
    '$or' => [
        ['qty' => ['$gt' => 5]],
        ['color' => 'yellow']
    ]
]);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
{"_id":3,"name":"oranges","qty":6,"rating":2,"type":["naval","mandarin"]}
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}

Operadores de array

Os operadores de array correspondem aos documentos com base no valor ou na quantidade de elementos em um campo de array . A seguinte lista descreve os operadores de array disponíveis:

• $all: retorna documentos com arrays que contêm todos os elementos da query

• $elemMatch: Retorna documentos se um elemento em seu campo de matriz corresponder a todas as condições na query

• $size: retorna todos os documentos com arrays de um tamanho especificado

Para saber mais sobre operadores de array, consulte o guia Operadores de query de array no manual do MongoDB Server .

O exemplo seguinte especifica um operador de array em um filtro de query como um parâmetro para o método MongoDB\Collection::find() . O código retorna todos os documentos em que o campo de array type contém elementos 2 :

$cursor = $collection->find(['type' => ['$size' => 2]]);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
{"_id":3,"name":"oranges","qty":6,"rating":2,"type":["naval","mandarin"]}

Operadores de elementos

Os operadores de elemento consultam os dados com base na presença ou tipo de campo.

Para saber mais sobre os operadores de elementos, consulte o guia Operadores de query de elementos no manual do MongoDB Server .

O exemplo seguinte especifica um operador de elemento em um filtro de query como um parâmetro para o método MongoDB\Collection::find() . O código retorna todos os documentos que têm um campo color :

$cursor = $collection->find(['color' => ['$exists' => true]]);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
{"_id":2,"name":"bananas","qty":7,"rating":4,"color":"yellow","type":["cavendish"]}
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}

Operadores de avaliação

Os operadores de avaliação retornam dados com base em avaliações de campos individuais ou documentos de toda a coleção.

A seguinte lista descreve operadores de avaliação comuns:

• $text: Executa uma pesquisa de texto nos documentos

• $regex: retorna documentos que correspondem a uma expressão regular especificada

• $mod: Executa uma operação de módulo no valor de um campo e retorna documentos onde o restante é um valor especificado

Para visualizar uma lista completa de operadores de avaliação, consulte o guia Operadores de query de avaliação no manual do MongoDB Server .

O exemplo seguinte especifica um operador de avaliação em um filtro de query como um parâmetro para o método MongoDB\Collection::find() . O código usa uma expressão regular para retornar todos os documentos nos quais o valor do campo name tem pelo menos dois 'p' caracteres consecutivos:

$cursor = $collection->find(['name' => ['$regex' => 'p{2,}']]);
foreach ($cursor as $doc) {
    echo json_encode($doc), PHP_EOL;
}

{"_id":1,"name":"apples","qty":5,"rating":3,"color":"red","type":["fuji","honeycrisp"]}
{"_id":4,"name":"pineapples","qty":3,"rating":5,"color":"yellow"}

Informações adicionais

Para saber mais sobre como query documentos, consulte o guia Consultar documentos no manual do MongoDB Server .

Para saber mais sobre como recuperar documentos com a biblioteca PHP do MongoDB , consulte o guia Recuperar dados .