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

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

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

$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
        ]);
    }
}

$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
        ]);
    }
}