Read Operations

Overview

In this guide, you can learn how to use Laravel MongoDB to perform find operations on your MongoDB collections. Find operations allow you to retrieve documents based on criteria that you specify.

This guide shows you how to perform the following tasks:

• Retrieve Documents that Match a Query

• Retrieve All Documents in a Collection

• Search Text Fields

• Modify Find Operation Behavior

Before You Get Started

To run the code examples in this guide, complete the Quick Start tutorial. This tutorial provides instructions on setting up a MongoDB Atlas instance with sample data and creating the following files in your Laravel web application:

• Movie.php file, which contains a Movie model to represent documents in the movies collection

• MovieController.php file, which contains a show() function to run database operations

• browse_movies.blade.php file, which contains HTML code to display the results of database operations

The following sections describe how to edit the files in your Laravel application to run the find operation code examples and view the expected output.

Retrieve Documents that Match a Query

You can use Laravel's Eloquent object-relational mapper (ORM) to create models that represent MongoDB collections and chain methods on them to specify query criteria.

To retrieve documents that match a set of criteria, call the where() method on the collection's corresponding Eloquent model, then pass a query filter to the method.

A query filter specifies field value requirements and instructs the find operation to return only documents that meet these requirements.

You can use one of the following where() method calls to build a query:

• where('<field name>', <value>) builds a query that matches documents in which the target field has the exact specified value

• where('<field name>', '<comparison operator>', <value>) builds a query that matches documents in which the target field's value meets the comparison criteria

To apply multiple sets of criteria to the find operation, you can chain a series of where() methods together.

After building your query by using the where() method, chain the get() method to retrieve the query results.

This example calls two where() methods on the Movie Eloquent model to retrieve documents that meet the following criteria:

• year field has a value of 2010

• imdb.rating nested field has a value greater than 8.5

$movies = Movie::where('year', 2010)
    ->where('imdb.rating', '>', 8.5)
    ->get();

class MovieController
{
    public function show()
    {
         $movies = Movie::where('year', 2010)
             ->where('imdb.rating', '>', 8.5)
             ->get();
         return view('browse_movies', [
             'movies' => $movies
         ]);
    }
}

Title: Inception
Year: 2010
Runtime: 148
IMDB Rating: 8.8
IMDB Votes: 1294646
Plot: A thief who steals corporate secrets through use of dream-sharing
technology is given the inverse task of planting an idea into the mind of a CEO.
Title: Senna
Year: 2010
Runtime: 106
IMDB Rating: 8.6
IMDB Votes: 41904
Plot: A documentary on Brazilian Formula One racing driver Ayrton Senna, who won the
F1 world championship three times before his death at age 34.

To learn how to query by using the Laravel query builder instead of the Eloquent ORM, see the Query Builder page.

$movies = Movie::where('countries', ['Indonesia', 'Canada'])
    ->get();

$movies = Movie::where('countries', 'in', ['Canada', 'Egypt'])
    ->get();

Retrieve All Documents in a Collection

You can retrieve all documents in a collection by omitting the query filter. To return the documents, call the get() method on an Eloquent model that represents your collection. Alternatively, you can use the get() method's alias all() to perform the same operation.

Use the following syntax to run a find operation that matches all documents:

$movies = Movie::get();

Search Text Fields

A text search retrieves documents that contain a term or a phrase in the text-indexed fields. A term is a sequence of characters that excludes whitespace characters. A phrase is a sequence of terms with any number of whitespace characters.

You can perform a text search by using the $text operator followed by the $search field in your query filter that you pass to the where() method. The $text operator performs a text search on the text-indexed fields. The $search field specifies the text to search for.

After building your query by using the where() method, chain the get() method to retrieve the query results.

This example calls the where() method on the Movie Eloquent model to retrieve documents in which the plot field contains the phrase "love story". To perform this text search, the collection must have a text index on the plot field.

$movies = Movie::where('$text', ['$search' => '"love story"'])
    ->get();

class MovieController
{
    public function show()
    {
         $movies = Movie::where('$text', ['$search' => '"love story"'])
             ->get();
         return view('browse_movies', [
             'movies' => $movies
         ]);
    }
}

Title: Cafè de Flore
Year: 2011
Runtime: 120
IMDB Rating: 7.4
IMDB Votes: 9663
Plot: A love story between a man and woman ...
Title: Paheli
Year: 2005
Runtime: 140
IMDB Rating: 6.7
IMDB Votes: 8909
Plot: A folk tale - supernatural love story about a ghost ...
Title: Por un puèado de besos
Year: 2014
Runtime: 98
IMDB Rating: 6.1
IMDB Votes: 223
Plot: A girl. A boy. A love story ...
...

A text search assigns a numerical text score to indicate how closely each result matches the string in your query filter. You can sort the results by relevance by using the orderBy() method to sort on the textScore metadata field. You can access this metadata by using the $meta operator:

$movies = Movie::where('$text', ['$search' => '"love story"'])
    ->orderBy('score', ['$meta' => 'textScore'])
    ->get();

Modify Behavior

You can modify the results of a find operation by chaining more methods to where().

The following sections demonstrate how to modify the behavior of the where() method:

• Skip and Limit Results uses the skip() method to set the number of documents to skip and the take() method to set the total number of documents to return

• Sort Query Results uses the orderBy() method to return query results in a specified order based on field values

• Return the First Result uses the first() method to return the first document that matches the query filter

$movies = Movie::where('year', 1999)
    ->skip(2)
    ->take(3)
    ->get();

class MovieController
{
    public function show()
    {
         $movies = Movie::where('year', 1999)
             ->skip(2)
             ->take(3)
             ->get();
         return view('browse_movies', [
             'movies' => $movies
         ]);
    }
}

Title: Three Kings
Year: 1999
Runtime: 114
IMDB Rating: 7.2
IMDB Votes: 130677
Plot: In the aftermath of the Persian Gulf War, 4 soldiers set out to steal gold
that was stolen from Kuwait, but they discover people who desperately need their help.
Title: Toy Story 2
Year: 1999
Runtime: 92
IMDB Rating: 7.9
IMDB Votes: 346655
Plot: When Woody is stolen by a toy collector, Buzz and his friends vow to rescue him,
but Woody finds the idea of immortality in a museum tempting.
Title: Beowulf
Year: 1999
Runtime: 95
IMDB Rating: 4
IMDB Votes: 9296
Plot: A sci-fi update of the famous 6th Century poem. In a besieged land, Beowulf must
battle against the hideous creature Grendel and his vengeance seeking mother.

$movies = Movie::where('countries', 'Indonesia')
    ->orderBy('year')
    ->orderBy('title', 'desc')
    ->get();

class MovieController
{
    public function show()
    {
        $movies = Movie::where('countries', 'Indonesia')
            ->orderBy('year')
            ->orderBy('title', 'desc')
            ->get();
        return view('browse_movies', [
            'movies' => $movies
        ]);
    }
}

Title: Joni's Promise
Year: 2005
Runtime: 83
IMDB Rating: 7.6
IMDB Votes: 702
Plot: A film delivery man promises ...
Title: Gie
Year: 2005
Runtime: 147
IMDB Rating: 7.5
IMDB Votes: 470
Plot: Soe Hok Gie is an activist who lived in the sixties ...
Title: Requiem from Java
Year: 2006
Runtime: 120
IMDB Rating: 6.6
IMDB Votes: 316
Plot: Setyo (Martinus Miroto) and Siti (Artika Sari Dewi)
are young married couple ...
...

$movie = Movie::where('runtime', 30)
    ->orderBy('_id')
    ->first();

class MovieController
{
    public function show()
    {
        $movie = Movie::where('runtime', 30)
            ->orderBy('_id')
            ->first();
        return view('browse_movies', [
            'movies' => $movie
        ]);
    }
}

Title: Statues also Die
Year: 1953
Runtime: 30
IMDB Rating: 7.6
IMDB Votes: 620
Plot: A documentary of black art.