Menu Docs
Página inicial do Docs
/
Idiomas
/
PHP
/
Laravel MongoDB

Construtor de Query

Nesta página

Visão geral

Neste guia, você pode aprender a usar a extensão Laravel Integration do construtor de query Laravel para trabalhar com um banco de banco de dados MongoDB . O construtor de query permite que você use uma sintaxe única e uma interface fluente para escrever queries para qualquer banco de banco de dados suportado .

Observação

A Integração do Laravel estende o construtor de queries do Laravel e o Eloquent ORM, que pode executar operações de banco de dados de dados semelhantes. Para saber mais sobre como recuperar documentos usando modelos Eloquent, consulte Operações de leitura.

O Laravel fornece uma máscara para acessar a classe de construtor de query DB, que permite executar operações de banco de dados. As facetas, que são interfaces estáticas para classes, tornam a sintaxe mais concisa, evitam erros de tempo de execução e melhoram a testabilidade.

A integração Laravel fornece o DB método table() para acessar uma coleção. Métodos de cadeia para especificar comandos e quaisquer restrições. Em seguida, encadeie o método get() no final para executar os métodos e recuperar os resultados. Para recuperar apenas o primeiro resultado correspondente, encadeie o método first() em vez do método get() . A partir de Laravel MongoDB v5.0, o construtor de query retorna resultados como stdClass objetos.

O exemplo a seguir mostra a sintaxe de uma chamada de construtor de query:

DB::table('<collection name>')
    // chain methods by using the "->" object operator
    ->get();

Dica

Definir conexão do banco de dados

Antes de usar o método DB::table() , certifique-se de especificar MongoDB como a conexão de banco de dados padrão do seu aplicativo. Para obter instruções sobre como configurar a conexão do banco de dados, consulte a etapa Configurar sua conexão MongoDB no Início rápido.

Se o MongoDB não for o banco de dados padrão do seu aplicativo, você poderá usar o método DB::connection() para especificar uma conexão do MongoDB. Passe o nome da conexão para o método connection() , conforme mostrado no código a seguir:

$connection = DB::connection('mongodb');

Este guia fornece exemplos dos seguintes tipos de operações de construtor de query:

  • Recuperar documentos correspondentes

  • Modificar Resultados da Query

  • Recuperar dados usando operações MongoDB

  • Gravar dados usando operações de gravação do MongoDB

Antes de começar

Para executar os exemplos de código neste guia, conclua o tutorial de Início Rápido para configurar um aplicativo da web, carregue conjuntos de dados de exemplo em seu sistema do MongoDB e execute o código de exemplo de um método de controlador. Para ver a saída de código esperada como documentos JSON, use o método toJson() mostrado na etapa opcional Visualizar seus resultados como documentos JSON do Início Rápido.

Para executar operações de leitura e escrita usando o construtor de query, importe a face Illuminate\Support\Facades\DB e componha sua query.

Recuperar documentos correspondentes

Esta seção inclui exemplos de construtores de query para operações de leitura nas seguintes categorias de operador:

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:

Exemplo de OR lógico

O exemplo a seguir mostra como encadear o método de construtor de query orWhere() para recuperar documentos da collection movies na qual o valor do campo _id é ObjectId('573a1398f29313caabce9682') ou o valor do campo title é "Back to the Future":

$result = DB::connection('mongodb')
    ->table('movies')
    ->where('id', new ObjectId('573a1398f29313caabce9682'))
    ->orWhere('title', 'Back to the Future')
    ->get();

Observação

Você pode usar o apelido id em suas queries para representar o campo _id em documentos MongoDB , conforme mostrado no código anterior. Quando você usa o construtor de query para executar uma operação de localizar, a Integração Laravel converte automaticamente entre _id e id nomes de campo . Nos resultados da consulta, o campo _id é apresentado como id. Isso fornece melhor consistência com o Laravel, pois a estrutura pressupõe que cada registro tenha uma chave primária chamada id por padrão.

Devido a esse comportamento, você não pode ter dois campos id e _id separados em seus documentos.

Exemplo de Lógico E

O exemplo a seguir mostra como encadear o método construtor de query where() para recuperar documentos da collection movies que correspondam a um valor imdb.rating maior que 8.5 e a um valor year menor que 1940:

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

Dica

Para compatibilidade com Laravel, Laravel MongoDB v5.1 suporta notação de seta (->) e ponto (.) para acessar campos aninhados em um filtro de query. O exemplo anterior usa notação de ponto de ponto para fazer uma query do campo aninhado imdb.rating , que é a sintaxe recomendada.

Exemplo de NÃO lógico

O exemplo a seguir mostra como chamar o método construtor de query whereNot() para recuperar documentos da collection movies que correspondem a documentos que não têm um valor de imdb.rating maior que 2. Isso equivale a corresponder a todos os documentos que tenham imdb.rating menor ou igual a 2:

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

Exemplo de grupo de operadores lógicos aninhados

O exemplo a seguir mostra como encadear o método construtor de query where() para recuperar documentos da coleção movies que correspondam a ambas as condições a seguir. Este exemplo passa um fechamento como o primeiro parâmetro do método construtor de query where() para agrupar o grupo OU lógico:

  • imdb.rating o valor é maior que 8.5

  • year o valor é 1986 ou 1996

$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:

Exemplo de faixa numérica

O exemplo seguinte mostra como utilizar o método de construtor de consulta whereBetween() para recuperar documentos da coleção movies que contêm um valor imdb.rating entre 9 e 9.5:

$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 }, ... },
   ...
]

Exemplo de valores nulos ou ausentes

O exemplo seguinte mostra como utilizar o método de construtor de consulta whereNull() para recuperar documentos da coleção movies que omitem um valor ou campo runtime :

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

Um ou mais valores de um exemplo de conjunto

O exemplo seguinte mostra como utilizar o método de construtor de query whereIn() para recuperar documentos da collection movies que correspondem a pelo menos um dos valores title no conjunto especificado:

$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, ... },
   ...
]

Exemplo de datas de correspondência

O exemplo a seguir mostra como usar o método de construtor de query where() para recuperar documentos da collection movies nas quais o valor released é 15 janeiro de 2010, especificado em um objeto Carbon :

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

Observação

Filtro de query de data e tipo de resultado

A partir de Laravel MongoDB v5.0, Objetos decobre passados como filtros de query, conforme mostrado no código anterior, são convertidos em UTCDateTime valores BSON.

Nos resultados da query, os valores de BSON UTCDateTime no MongoDB são retornados como Carbon objetos. A Integração Laravel aplica o fuso horário padrão ao realizar esta conversão.

Se você quiser representar uma data como uma string em seu filtro de consulta em vez de um objeto Carbon , use o método whereDate() construtor de consulta . O exemplo a seguir recupera documentos da collection movies na qual o valor released é 15 2010 e especifica a data como uma string:

$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", ...},
   ...
]

Métodos ondeLike() e ondeNotLike()

Os métodos a seguir fornecem a mesma funcionalidade que usar o operador de query semelhante para corresponder padrões:

  • whereLike(): corresponde a um padrão especificado. Por padrão, esse método realiza uma correspondência insensível a maiúsculas e minúsculas. Você pode habilitar a sensibilidade a maiúsculas e minúsculas passando true como o último parâmetro para o método.

  • whereNotLike(): corresponde a documentos em que o valor do campo não contém o padrão de string especificado.

O exemplo a seguir mostra como usar o método whereLike() para combinar documentos nos quais o campo title tem um valor que corresponde ao padrão 'Start%' com a distinção entre maiúsculas e minúsculas ativada:

$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();

Agregações

Os exemplos nesta seção mostram a sintaxe do construtor de query que você pode utilizar para executar agregações. Agregações são operações que calculam valores a partir de um conjunto de dados de resultados de query. Você pode usar agregações para calcular e retornar as seguintes informações:

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()

Dica

O método groupBy() chama o operador de agregação $group do MongoDB e o operador acumulador $last . Para saber mais sobre esses operadores, consulte $group (agregação) no manual do servidor MongoDB.

$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');

Modificar Resultados da Query

Esta seção inclui exemplos de construtores de query para as seguintes funções que modificam a ordem e o formato dos resultados da query:

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.

Recuperar dados usando operações MongoDB

Esta seção inclui exemplos de construtores de query que mostram como usar as seguintes operações de query específicas do MongoDB:

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();

Observação

Esta configuração especifica um valor de maxTimeMS em segundos em vez de milissegundos. Para saber mais sobre o valor maxTimeMS , consulte MongoDBCollection::find() na documentação da Biblioteca PHP.

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:

Importante

Para executar queries GeoJSON no MongoDB, você deve criar índice 2d ou 2dsphere na coleção. Para saber como criar índices geoespaciais, consulte a seção Criar um índice geoespacial no guia Construtor de esquemas.

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.

Gravar dados usando operações de gravação do MongoDB

Esta seção inclui exemplos de construtores de queries que mostram como usar as seguintes operações de gravação específicas do 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.

Método de upsert

O método construtor de query do upsert(array $values, array|string $uniqueBy, array|null $update) aceita os seguintes parâmetros:

  • $values: Array de campos e valores que especificam documentos para atualizar ou inserir.

  • $uniqueBy: Lista de campos que identificam exclusivamente documentos em seu primeiro parâmetro de array.

  • $update: lista opcional de campos a serem atualizados se existir um documento correspondente. Se você omitir este parâmetro, a Integração do Laravel atualizará todos os campos.

O exemplo a seguir mostra como usar o método de construtor de query upsert() para atualizar ou inserir documentos com base nas seguintes instruções:

  • Especifique um documento no qual o valor do campo title é 'Inspector Maigret', o valor do campo recommended é false e o valor do campo runtime é 128.

  • Especifique um documento no qual o valor do campo title é 'Petit Maman', o valor do campo recommended é true e o valor do campo runtime é 72.

  • Indique que o campo title identifica exclusivamente documentos no escopo da sua operação.

  • Atualize somente o campo recommended em documentos correspondentes.

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

O método construtor de query do upsert() retorna o número de documentos que a operação atualizou, inseriu e modificou.

Observação

O método upsert() não trigger eventos. Para trigger eventos de uma operação de upsert, você pode usar o método createOrFirst().

Método de atualização

O exemplo a seguir mostra como usar o método de construtor de query update() e a opção upsert para atualizar o documento correspondente ou inserir um com os dados especificados se ele não existir. Quando você define a opção upsert como true e o documento não existe, o comando insere os dados e o campo e valor title especificados na operação de query where() :

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

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

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,
    ]);

Observação

Se você passar um campo para o método increment() ou incrementEach() que não tem valor ou não existe nos documentos correspondentes, esses métodos inicializarão o campo especificado com o valor de incremento.

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,
    ]);

Observação

Se você passar um campo para o método decrement() ou decrementEach() que não tem valor ou não existe nos documentos correspondentes, esses métodos inicializarão o campo especificado com o valor de decremento.

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.

Voltar

Construtor de esquemas

Próximo

Autenticação de usuários

Nesta página