Construtor de Query

Exemplo de método Onde

O exemplo seguinte mostra como utilizar o método de construtor de query where() para recuperar documentos da collection movies que contêm um valor de campo imdb.rating de exatamente 9.3. Clique no botão VIEW OUTPUT para visualizar os resultados retornados pela query:

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('imdb.rating', 9.3)
    ->get();

[
   { "title": "Cosmos",
     "year": 1980,
     "runtime": 60,
     "imdb": {
       "rating": 9.3,
       "votes": 17174,
       "id": 81846
     },
     "plot": "Astronomer Carl Sagan leads us on an engaging guided tour of the various elements and cosmological theories of the universe.",
     ...
   },
   { "title": "The Shawshank Redemption",
     "year": 1994,
     "runtime": 142,
     "imdb": {
       "rating": 9.3,
       "votes": 1521105,
       "id": 111161
     },
     "plot": "Two imprisoned men bond over a number of years, finding solace and eventual redemption through acts of common decency.",
     ...
   },
   { "title": "The Real Miyagi",
     "year": 2015,
     "runtime": 90,
     "imdb": {
       "rating": 9.3,
       "votes": 41,
       "id": 2313306
     },
     "plot": "The life of the greatest karate master of a generation.",
      ...
   }
]

Operações condicionais lógicas

Os exemplos nesta seção mostram a sintaxe do construtor de query que você pode utilizar para executar as seguintes operações condicionais lógicas:

• OU lógico para corresponder a uma ou mais condições

• Lógico E para corresponder a todas as condições

• NÃO lógico para corresponder à negação da condição

• Grupos de operadores lógicos aninhados

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('year', 1955)
    ->orWhere('title', 'Back to the Future')
    ->get();

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('imdb.rating', '>', 8.5)
    ->where('year', '<', 1940)
    ->get();

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereNot('imdb.rating', '>', 2)
    ->get();

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('imdb.rating', '>', 8.5)
    ->where(function (Builder $query) {
        return $query
            ->where('year', 1986)
            ->orWhere('year', 1996);
    })->get();

Faixas e verificações de tipo

Os exemplos nesta seção mostram a sintaxe do construtor de query que você pode usar para fazer a correspondência de valores usando as seguintes queries de intervalo e operações de verificação de tipo:

• Valores dentro de uma faixa numérica

• Valores nulos ou ausentes

• Um ou mais valores de um conjunto

• Datas de correspondência

• Corresponder a um padrão de texto

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereBetween('imdb.rating', [9, 9.5])
    ->get();

[
   { "title" "The Godfather", "imdb": { "rating": 9.2, "votes": 1038358, "id": 68646 }, ... },
   { "title": "Hollywood", "imdb": { "rating": 9.1, "votes": 511,"id": 80230 }, ... },
   { "title": "Cosmos", "imdb": { "rating": 9.3, "votes": 17174, "id": 81846 }, ... },
   ...
]

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereNull('runtime')
    ->get();

$result = DB::table('movies')
    ->whereIn('title', ['Toy Story', 'Shrek 2', 'Johnny English'])
    ->get();

[
   { "title": "Toy Story", "year": 1995, "runtime": 81, ... },
   { "title": "Johnny English", "year": 2003, "runtime": 87, ... },
   { "title": "Shrek 2", "year" 2004, "runtime": 93, ... },
   ...
]

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereDate('released', '2010-1-15')
    ->get();

Exemplo de correspondência de padrão de texto

O exemplo seguinte mostra como utilizar o operador de consulta like com o método de construtor de consulta where() para recuperar documentos da coleção movies utilizando um padrão de texto especificado.

Os padrões de texto podem conter texto misto com os seguintes caracteres curinga:

• % que corresponde a zero ou mais caracteres

• _ que corresponde a um único caractere

$result = DB::table('movies')
    ->where('title', 'like', '%spider_man%')
    ->get();

[
   { "title": "Kiss of the Spider Woman", ... },
   { "title": "Spider-Man", ... },
   { "title": "Spider-Man 2", ...},
   ...
]

$result = DB::connection('mongodb')
    ->table('movies')
    ->whereLike('title', 'Start%', true)
    ->get();

[
   { "title": "Start-Up", ... },
   { "title": "Start the Revolution Without Me", ... },
   ...
]

Retrieve Distinct Values

O exemplo a seguir mostra como usar o método de construtor de consulta distinct() para recuperar todos os valores diferentes do campo year para documentos nas coleções movies .

$result = DB::table('movies')
    ->distinct('year')->get();

Exemplo de resultados agrupados por valores de campo comuns

O exemplo a seguir mostra como usar o método construtor de query groupBy() para recuperar dados de documentos agrupados por valores compartilhados do campo runtime . Este exemplo encadeia as seguintes operações para corresponder a documentos da collection movies que contêm um valor rated de G e incluem o campo title de um filme para cada valor runtime distinto:

• Corresponder somente documentos que contêm um valor de campo rated de "G" usando o método where()

• Agrupe dados pelos valores distintos do campo runtime , que é atribuído ao campo _id , usando o método groupBy()

• Classificar os grupos pelo campo runtime usando o método orderBy()

• Retornar dados title do último documento no resultado agrupado especificando-os no método get()

$result = DB::table('movies')
   ->where('rated', 'G')
   ->groupBy('runtime')
   ->orderBy('runtime', 'asc')
   ->get(['title']);

[
  ...
  {
    "_id": { "runtime": 64 },
    "runtime": 64,
    "title": "Stitch! The Movie"
  },
  {
     "_id": { "runtime": 67 },
     "runtime": 67,
     "title": "Bartok the Magnificent"
   },
   {
     "_id": { "runtime":68 },
     "runtime": 68,
     "title": "Mickey's Twice Upon a Christmas"
   },
   ...
]

Exemplo de número de resultados

O exemplo a seguir mostra como usar o método de construtor de query count() para retornar o número de documentos contidos na coleção movies :

$result = DB::table('movies')
    ->count();

Valor máximo de um exemplo de campo

O exemplo seguinte mostra como utilizar o método de construtor de query max() para retornar o valor numérico mais alto do campo runtime de toda a coleção movies :

$result = DB::table('movies')
    ->max('runtime');

Valor mínimo de um exemplo de campo

O exemplo seguinte mostra como utilizar o método de construtor de query min() para retornar o valor numérico mais baixo do campo year de toda a coleção movies :

$result = DB::table('movies')
    ->min('year');

Valor médio de um exemplo de campo

O exemplo seguinte mostra como utilizar o método de construtor de query avg() para retornar a média numérica, ou média aritmética, dos valores imdb.rating de toda a coleção movies .

$result = DB::table('movies')
    ->avg('imdb.rating');

Valor somado de um exemplo de campo

O exemplo seguinte mostra como utilizar o método de construtor de consulta sum() para retornar o total numérico dos valores imdb.votes de toda a coleção movies :

$result = DB::table('movies')
    ->sum('imdb.votes');

Exemplo de agregação de resultados correspondentes

O exemplo a seguir mostra como agregar dados de resultados que correspondem a uma query. A consulta corresponde a todos os filmes após o ano 2000 e calcula o valor médio de imdb.rating dessas correspondências usando o método avg() :

$result = DB::table('movies')
    ->where('year', '>', 2000)
    ->avg('imdb.rating');

Exemplo de resultados do pedido

O exemplo seguinte mostra como utilizar o método construtor de query orderBy() para organizar os resultados que correspondem ao filtro especificado no campo title pelo valor imdb.rating em ordem decrescente:

$result = DB::table('movies')
    ->where('title', 'like', 'back to the future%')
    ->orderBy('imdb.rating', 'desc')
    ->get();

[
  { "title": "Back to the Future", "imdb": { "rating":8.5,"votes":636511,"id":88763 }, ... },
  { "title": "Back to the Future Part II", "imdb": { "rating":7.8,"votes":292539,"id":96874 }, ... },
  { "title": "Back to the Future Part III", "imdb": {"rating":7.4,"votes":242390,"id":99088 }, ... },
  ...
]

Exemplo de omissão de um número especificado de resultados

O exemplo a seguir mostra como usar o método de construtor de query skip() para omitir os quatro primeiros resultados que correspondem ao filtro especificado no campo title , classificados pelo valor year em ordem crescente:

$result = DB::table('movies')
    ->where('title', 'like', 'star trek%')
    ->orderBy('year', 'asc')
    ->skip(4)
    ->get();

Mostrar um subconjunto de campos e valores de array no exemplo de resultados

O exemplo a seguir mostra como usar o método de construtor de query project() para corresponder a documentos que contêm um valor imdb.rating maior que 8.5 e retornar somente os seguintes valores de campo:

• Título do filme no title

• Segundo a quarto valores do campo de array cast , se existirem

• Campo _id do documento, que é incluído automaticamente

$result = DB::table('movies')
    ->where('imdb.rating', '>', 8.5)
    ->project([
        'title' => 1,
        'cast' => ['$slice' => [1, 3]],
    ])
    ->get();

[
  {
    "_id": { ... },
    "title": "City Lights"
    "cast": [
      "Florence Lee",
      "Harry Myers",
      "Al Ernest Garcia"
    ],
  },
  {
    "_id": { ... },
    "title": "Modern Times",
    "cast": [
      "Paulette Goddard",
      "Henry Bergman",
      "Tiny Sandford"
    ]
  },
  {
    "_id": { ... },
    "title": "Casablanca"
    "cast": [
      "Ingrid Bergman",
      "Paul Henreid",
      "Claude Rains"
    ],
  },
  ...
]

Exemplo de paginação dos resultados

O exemplo seguinte mostra como utilizar o método de construtor de consulta paginate() para dividir toda a coleção do movie em conjuntos de resultados discretos de documentos do 15 . O exemplo também inclui uma ordem de classificação para organizar os resultados pelo campo imdb.votes em ordem decrescente e uma projeção que inclui somente campos específicos nos resultados.

$resultsPerPage = 15;
$projectionFields = ['title', 'runtime', 'imdb.rating'];
$result = DB::table('movies')
    ->orderBy('imdb.votes', 'desc')
    ->paginate($resultsPerPage, $projectionFields);

Para saber mais sobre paginação, consulte Paginando Resultados do Construtor de Consulta na documentação do Laravel.

Contém um exemplo de campo

O exemplo a seguir mostra como usar o método construtor de query exists() para corresponder a documentos que contêm o campo random_review:

$result = DB::table('movies')
    ->exists('random_review', true);

Para saber mais sobre esse operador de query, consulte $exists no manual do servidor MongoDB.

Exemplo de contém todos os campos

O exemplo a seguir mostra como usar o operador de query all com o método de construtor de query where() para corresponder a documentos que contêm todos os campos especificados:

$result = DB::table('movies')
    ->where('movies', 'all', ['title', 'rated', 'imdb.rating'])
    ->get();

Para saber mais sobre esse operador de query, consulte $all no manual do servidor MongoDB.

Exemplo de tamanho da array de correspondência

O exemplo a seguir mostra como passar o operador de query size com o método construtor de query where() para corresponder a documentos que contêm um campo directors que contém uma array de exatamente cinco elementos:

$result = DB::table('movies')
    ->where('directors', 'size', 5)
    ->get();

Para saber mais sobre esse operador de query, consulte $size no manual do servidor MongoDB.

Exemplo de tipo de dados de correspondência

O exemplo a seguir mostra como passar o operador de query type com o método de construtor de query where() para corresponder a documentos que contêm um valor de tipo 4 , que corresponde a um tipo de dados de array, no campo released .

$result = DB::table('movies')
    ->where('released', 'type', 4)
    ->get();

Para saber mais sobre os códigos de tipo e o operador de query, consulte $type no manual do servidor MongoDB.

Exemplo de corresponder a um valor calculado com o módulo

O exemplo a seguir mostra como passar o operador de query mod com o método construtor de query where() para corresponder aos documentos usando a expressão year % 2 == 0, que corresponde a valores pares para o campo year :

$result = DB::table('movies')
    ->where('year', 'mod', [2, 0])
    ->get();

Para saber mais sobre esse operador de query, consulte $mod no manual do servidor MongoDB.

Corresponder a uma expressão regular

O exemplo seguinte mostra como passar o operador de query REGEX com o método construtor de query where() para corresponder a documentos que contêm um campo title que corresponde à expressão regular especificada:

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('title', 'REGEX', new Regex('^the lord of .*', 'i'))
    ->get();

Para saber mais sobre queries de expressão regular no MongoDB, consulte $regex no manual do servidor MongoDB.

Exemplo de operações da API de query do MongoDB

O exemplo a seguir mostra como usar o método construtor de query whereRaw() para executar uma operação de query escrita usando a sintaxe da API de query do MongoDB:

$result = DB::table('movies')
    ->whereRaw([
        'imdb.votes' => ['$gte' => 1000 ],
        '$or' => [
            ['imdb.rating' => ['$gt' => 7]],
            ['directors' => ['$in' => [ 'Yasujiro Ozu', 'Sofia Coppola', 'Federico Fellini' ]]],
        ],
    ])->get();

O seguinte código mostra a sintaxe equivalente da API de query MongoDB:

db.movies.find({
  "imdb.votes": { $gte: 1000 },
  $or: [{
    imdb.rating: { $gt: 7 },
    directors: { $in: [ "Yasujiro Ozu", "Sofia Coppola", "Federico Fellini" ] }
}]});

Para saber mais sobre a de MongoDB query do API, consulte MongoDB query API do MongoDB no manual do servidor MongoDB.

Exemplo de elementos de array de correspondência

O exemplo a seguir mostra como passar o operador de query elemMatch com o método construtor de query where() para corresponder a documentos que contêm um elemento de array que corresponda a pelo menos uma das condições na query especificada:

$result = DB::table('movies')
    ->where('writers', 'elemMatch', ['$in' => ['Maya Forbes', 'Eric Roth']])
    ->get();

Para saber mais sobre queries de expressão regular no MongoDB, consulte o operador $elemMatch no manual do servidor MongoDB.

Exemplo de especificação de tempo limite do cursor

O exemplo a seguir mostra como usar o método timeout() para especificar uma duração máxima para aguardar a conclusão das operações do cursor.

$result = DB::table('movies')
    ->timeout(2) // value in seconds
    ->where('year', 2001)
    ->get();

Faça a correspondência de locais usando operações geoespaciais

Os exemplos nesta seção mostram a sintaxe do construtor de query que você pode utilizar para executar queries geoespaciais no GeoJSON ou dados de pares de coordenadas para recuperar os seguintes tipos de localizações:

• Perto de uma posição

• Dentro do limite de um objeto GeoJSON

• Interseccionando um objeto GeoJSON

• Dados de proximidade para correspondências próximas

Para saber mais sobre objetos GeoJSON que o MongoDB suporta, consulte ObjetosGeoJSON no manual do servidor MongoDB.

Exemplo de posição próxima

O exemplo seguinte mostra como utilizar o operador de query near com o método de construtor de query where() para corresponder a documentos que contêm um local que está até 50 metros de um objeto de ponto GeoJSON:

$results = DB::table('theaters')
    ->where('location.geo', 'near', [
        '$geometry' => [
            'type' => 'Point',
            'coordinates' => [
                -86.6423,
                33.6054,
            ],
        ],
        '$maxDistance' => 50,
    ])->get();

Para saber mais sobre esse operador, consulte o operador $near no manual do servidor MongoDB.

Exemplo de dentro de uma área

O exemplo a seguir mostra como usar o operador de query geoWithin com o método de construtor de query where() para corresponder a documentos que contêm um local dentro dos limites do objeto GeoJSON Polygon especificado:

$results = DB::table('theaters')
    ->where('location.geo', 'geoWithin', [
        '$geometry' => [
            'type' => 'Polygon',
            'coordinates' => [
                [
                    [-72, 40],
                    [-74, 41],
                    [-72, 39],
                    [-72, 40],
                ],
            ],
        ],
    ])->get();

Exemplo de interseção com um exemplo geométrico

O exemplo a seguir mostra como usar o operador de query geoInstersects com o método de construtor de query where() para corresponder a documentos que contêm um local que intersecciona com o objeto GeoJSON LineString especificado:

$results = DB::table('theaters')
    ->where('location.geo', 'geoIntersects', [
        '$geometry' => [
            'type' => 'LineString',
            'coordinates' => [
                [-73.600525, 40.74416],
                [-72.600525, 40.74416],
            ],
        ],
    ])->get();

Exemplo de dados de proximidade para correspondências próximas

O exemplo a seguir mostra como usar o operador de agregação geoNear com o método de construtor de consulta raw() para executar uma agregação que retorna metadados, como informações de proximidade para cada correspondência:

$results = DB::table('theaters')->raw(
    function (Collection $collection) {
        return $collection->aggregate([
            [
                '$geoNear' => [
                    'near' => [
                        'type' => 'Point',
                        'coordinates' => [-118.34, 34.10],
                    ],
                    'distanceField' => 'dist.calculated',
                    'maxDistance' => 500,
                    'includeLocs' => 'dist.location',
                    'spherical' => true,
                ],
            ],
        ]);
    },
)->toArray();

Para saber mais sobre este operador de agregação, consulte o operador $geoNear no manual do servidor MongoDB.

Exemplo de Upsert de um Documento

A partir de v4.7, você pode executar uma operação de upsert usando um dos seguintes métodos de construtor de query:

• upsert(): ao usar esse método, você pode realizar um upsert em lote para alterar ou inserir vários documentos em uma operação.

• update(): Ao usar esse método, você deve especificar a opção upsert para atualizar todos os documentos que correspondam ao filtro de query ou inserir um documento se nenhum documento for correspondido. Somente este método upsert é suportado nas versões v4.6 e anteriores.

$result = DB::table('movies')
    ->upsert(
        [
            ['title' => 'Inspector Maigret', 'recommended' => false, 'runtime' => 128],
            ['title' => 'Petit Maman', 'recommended' => true, 'runtime' => 72],
        ],
        'title',
        'recommended',
    );

$result = DB::table('movies')
    ->where('title', 'Will Hunting')
    ->update(
        [
            'plot' => 'An autobiographical movie',
            'year' => 1998,
            'writers' => [ 'Will Hunting' ],
        ],
        ['upsert' => true],
    );

Exemplo de incremento de um valor numérico

O exemplo a seguir mostra como usar o método construtor de query increment() para adicionar 3000 ao valor do campo imdb.votes no documento correspondente:

$result = DB::table('movies')
    ->where('title', 'Field of Dreams')
    ->increment('imdb.votes', 3000);

O método construtor de query do increment() retorna o número de documentos que a operação atualizou.

A partir de Integração do Laravel v4.8, você também pode usar o método construtor de query incrementEach() para incrementar vários valores em uma única operação. O exemplo seguinte utiliza o método incrementEach() para aumentar os valores dos campos awards.wins e imdb.votes no documento correspondente:

$result = DB::table('movies')
    ->where('title', 'Lost in Translation')
    ->incrementEach([
        'awards.wins' => 2,
        'imdb.votes' => 1050,
    ]);

Exemplo de decremento de um valor numérico

O exemplo a seguir mostra como usar o método de construtor de query decrement() para subtrair 0.2 do valor do campo imdb.rating no documento correspondente:

$result = DB::table('movies')
    ->where('title', 'Sharknado')
    ->decrement('imdb.rating', 0.2);

O método construtor de query do decrement() retorna o número de documentos que a operação atualizou.

A partir de Integração do Laravel v4.8, você também pode usar o método de construtor de query decrementEach() para diminuir vários valores em uma única operação. O exemplo a seguir usa o método decrementEach() para diminuir os valores dos campos metacritic e imdb.rating no documento correspondente:

$result = DB::table('movies')
    ->where('title', 'Dunkirk')
    ->decrementEach([
        'metacritic' => 1,
        'imdb.rating' => 0.4,
    ]);

Adicionar um exemplo de elemento de array

O exemplo a seguir mostra como usar o método construtor de query push() para adicionar "Gary Cole" ao campo de array cast no documento correspondente:

$result = DB::table('movies')
    ->where('title', 'Office Space')
    ->push('cast', 'Gary Cole');

O método construtor de query do push() retorna o número de documentos que a operação atualizou.

Exemplo de remoção de um elemento de array

O exemplo seguinte mostra como utilizar o pull() método de construtor de query para remover o "Adventure" valor do genres campo do documento correspondente pela query:

$result = DB::table('movies')
    ->where('title', 'Iron Man')
    ->pull('genres', 'Adventure');

O método construtor de query do pull() retorna o número de documentos que a operação atualizou.

Remover um exemplo de campo

O exemplo seguinte mostra como utilizar o método de construtor de query unset() para remover o campo e valor tomatoes.viewer do documento correspondente pela query:

$result = DB::table('movies')
    ->where('title', 'Final Accord')
    ->unset('tomatoes.viewer');

O método construtor de query do unset() retorna o número de documentos que a operação atualizou.