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 como usar a extensão Laravel MongoDB do construtor de query Laravel para trabalhar com um banco de MongoDB database. O construtor de query permite que você use uma sintaxe única e uma interface fluente para escrever queries para qualquer banco de dados suportado.

Observação

Laravel O MongoDB 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.

O Laravel MongoDB usa DB nomes alternativos para o método table() como o collection() método . 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. O exemplo a seguir mostra a sintaxe de uma chamada de construtor de query:

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

Dica

Antes de usar o método DB::collection() , 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')
    ->collection('movies')
    ->where('imdb.rating', 9.3)
    ->get();

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 construtor de query orWhere() para recuperar documentos da collection movies que correspondam ao valor year de 1955 ou ao valor title "Back to the Future":

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

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')
    ->collection('movies')
    ->where('imdb.rating', '>', 8.5)
    ->where('year', '<', 1940)
    ->get();

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')
    ->collection('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')
    ->collection('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')
    ->collection('movies')
    ->whereBetween('imdb.rating', [9, 9.5])
    ->get();

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')
    ->collection('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::collection('movies')
    ->whereIn('title', ['Toy Story', 'Shrek 2', 'Johnny English'])
    ->get();

Exemplo de datas de correspondência

O exemplo seguinte mostra como utilizar o método de construtor de query whereDate() para recuperar documentos da collection movies que correspondem à data especificada de 2010-1-15 no campo released :

$result = DB::connection('mongodb')
    ->collection('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::collection('movies')
    ->where('title', 'like', '%spider_man%')
    ->get();

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::collection('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::collection('movies')
   ->where('rated', 'G')
   ->groupBy('runtime')
   ->orderBy('runtime', 'asc')
   ->get(['title']);

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::collection('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::collection('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::collection('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::collection('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::collection('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::collection('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::collection('movies')
    ->where('title', 'like', 'back to the future%')
    ->orderBy('imdb.rating', 'desc')
    ->get();

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::collection('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::collection('movies')
    ->where('imdb.rating', '>', 8.5)
    ->project([
        'title' => 1,
        'cast' => ['$slice' => [1, 3]],
    ])
    ->get();

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::collection('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::collection('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::collection('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::collection('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::collection('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::collection('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')
    ->collection('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::collection('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::collection('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::collection('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::collection('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::collection('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::collection('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::collection('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

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::collection('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::collection('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.

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::collection('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.

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::collection('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::collection('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::collection('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