Docs Menu
Docs Home
/
Languages
/
PHP
/
Laravel MongoDB

Full-Text Search with Scout

On this page

  • Overview
  • Scout for Atlas Search Tutorial
  • Install the Scout package
  • Add the Searchable trait to your model
  • Configure Scout in your application
  • Create the Atlas Search index
  • Import data into the searchable collection

Overview

In this guide, you can learn how to use the Laravel Scout feature in your Laravel MongoDB application. Scout enables you to implement full-text search on your Eloquent models. To learn more, see Laravel Scout in the Laravel documentation.

The Scout integration for Laravel MongoDB provides the following functionality:

  • Provides an abstraction to create Atlas Search indexes from any MongoDB or SQL model.

    Important

    Use Schema Builder to Create Search Indexes

    If your documents are already in MongoDB, create Search indexes by using MongoDB PHP Library or Schema builder methods to improve search query performance. To learn more about creating Search indexes, see the Create an Atlas Search Index section of the Atlas Search guide.

  • Enables you to automatically replicate data from MongoDB into a search engine such as Meilisearch or Algolia. You can use a MongoDB Eloquent model as the source to import and index. To learn more about indexing to a search engine, see the Indexing section of the Laravel Scout documentation.

Important

Deployment Compatibility

You can use Laravel Scout only when you connect to MongoDB Atlas deployments. This feature is not available for self-managed deployments.

Scout for Atlas Search Tutorial

This tutorial demonstrates how to use Scout to compound and index documents for MongoDB Atlas Search from Eloquent models (MongoDB or SQL).

1

Install the Scout package

Before you can use Scout in your application, run the following command from your application's root directory to install the laravel/scout package:

composer require laravel/scout
2

Add the Searchable trait to your model

Add the Laravel\Scout\Searchable trait to an Eloquent model to make it searchable. The following example adds this trait to the Movie model, which represents documents in the sample_mflix.movies collection:

<?php
namespace App\Models;
use MongoDB\Laravel\Eloquent\Model;
use Laravel\Scout\Searchable;
class Movie extends Model
{
    use Searchable;
    protected $connection = 'mongodb';
}

You can also use the Searchable trait to reformat documents, embed related documents, or transform document values. To learn more, see the Configuring Searchable Data section of the Laravel Scout documentation.

3

Configure Scout in your application

Ensure that your application is configured to use MongoDB as its database connection. To learn how to configure MongoDB, see the Configure Your MongoDB Connection section of the Quick Start guide.

To configure Scout in your application, create a file named scout.php in your application's config directory. Paste the following code into the file to configure Scout:

config/scout.php
<?php
return [
    'driver' => env('SCOUT_DRIVER', 'mongodb'),
    'mongodb' => [
        'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'),
    ],
    'prefix' => env('SCOUT_PREFIX', 'scout_'),
];

The preceding code specifies the following configuration:

  • Uses the value of the SCOUT_DRIVER environment variable as the default search driver, or mongodb if the environment variable is not set

  • Specifies scout_ as the prefix for the collection name of the searchable collection

In the config/scout.php file, you can also specify a custom Atlas Search index definition. To learn more, see the custom index definition example in the following step.

Set the following environment variable in your application's .env file to select mongodb as the default search driver:

.env
SCOUT_DRIVER=mongodb

Tip

Queueing

When using Scout, consider configuring a queue driver to reduce response times for your application's web interface. To learn more, see the Queuing section of the Laravel Scout documentation and the Queues guide.

4

Create the Atlas Search index

After you configure Scout and set your default search driver, you can create your searchable collection and search index by running the following command from your application's root directory:

php artisan scout:index 'App\Models\Movie'

Because you set MongoDB as the default search driver, the preceding command creates the search collection with an Atlas Search index in your MongoDB database. The collection is named scout_movies, based on the prefix set in the preceding step. The Atlas Search index is named scout and has the following configuration by default:

{
  "mappings": {
    "dynamic": true
  }
}

To customize the index definition, add the index-definitions configuration to the mongodb entry in your config/scout.php file. The following code demonstrates how to specify a custom index definition to create on the scout_movies collection:

'mongodb' => [
    'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'),
    'index-definitions' => [
        'scout_movies' => [
            'mappings' => [
                'dynamic' => false,
                'fields' => ['title' => ['type' => 'string']]
            ]
        ]
    ]
], ...

To learn more about defining Atlas Search index definitions, see the Define Field Mappings guide in the Atlas documentation.

Note

MongoDB can take up to a minute to create and finalize an Atlas Search index, so the scout:index command might not return a success message immediately.

5

Import data into the searchable collection

You can use Scout to replicate data from a source collection modeled by your Eloquent model into a searchable collection. The following command replicates and indexes data from the movies collection into the scout_movies collection indexed in the preceding step:

php artisan scout:import 'App\Models\Movie'

The documents are automatically indexed for Atlas Search queries.

Tip

Select Fields to Import

You might not need all the fields from your source documents in your searchable collection. Limiting the amount of data you replicate can improve your application's speed and performance.

You can select specific fields to import by defining the toSearchableArray() method in your Eloquent model class. The following code demonstrates how to define toSearchableArray() to select only the plot and title fields for replication:

class Movie extends Model
{
    ....
    public function toSearchableArray(): array
    {
        return [
            'plot' => $this->plot,
            'title' => $this->title,
        ];
    }
}

After completing these steps, you can perform Atlas Search queries on the scout_movies collection in your Laravel MongoDB application. To learn how to perform full-text searches, see the Atlas Search guide.

Back

Cache & Locks

Next

HTTP Sessions