Skip to content

DOCSP-46479: document Scout integration #3261

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 14 commits into from
Mar 5, 2025
2 changes: 2 additions & 0 deletions docs/index.txt
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,7 @@
Databases & Collections </database-collection>
User Authentication </user-authentication>
Cache & Locks </cache>
Scout Integration </scout>
HTTP Sessions </sessions>
Queues </queues>
Transactions </transactions>
Expand Down Expand Up @@ -86,6 +87,7 @@ see the following content:
- :ref:`laravel-aggregation-builder`
- :ref:`laravel-user-authentication`
- :ref:`laravel-cache`
- :ref:`laravel-scout`
- :ref:`laravel-sessions`
- :ref:`laravel-queues`
- :ref:`laravel-transactions`
Expand Down
259 changes: 259 additions & 0 deletions docs/scout.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,259 @@
.. _laravel-scout:

===========================
Full-Text Search with Scout
===========================

.. facet::
:name: genre
:values: reference

.. meta::
:keywords: php framework, odm, code example, text search, atlas

.. contents:: On this page
:local:
:backlinks: none
:depth: 2
:class: singlecol

Overview
--------

In this guide, you can learn how to use the Laravel Scout feature in
your {+odm-long+} application. Scout enables you to implement full-text
search on your Eloquent models. To learn more, see `Laravel Scout
<https://laravel.com/docs/{+laravel-docs-version+}/scout>`__ in the
Laravel documentation.

The Scout integration for {+odm-long+} provides the following
functionality:

- Provides an abstraction to create :atlas:`Atlas Search indexes
</atlas-search/manage-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 {+php-library+} or ``Schema`` builder methods to improve
search query performance. To learn more about creating Search
indexes, see the :ref:`laravel-as-index` section of the Atlas
Search guide.

- Enables you to automatically replicate data from MongoDB into a
search engine such as `Meilisearch <https://www.meilisearch.com/>`__
or `Algolia <https://www.algolia.com/>`__. 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
<https://laravel.com/docs/{+laravel-docs-version+}/scout#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).

.. procedure::
:style: connected

.. step:: 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:

.. code-block:: bash

composer require laravel/scout

.. step:: 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:

.. code-block:: php
:emphasize-lines: 6, 10

<?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
<https://laravel.com/docs/{+laravel-docs-version+}/scout#configuring-searchable-data>`__
section of the Laravel Scout documentation.

.. step:: 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
:ref:`laravel-quick-start-connect-to-mongodb` 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:

.. code-block:: php
:caption: 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 :ref:`custom
index definition example <laravel-scout-custom-index>` in the
following step.

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

.. code-block:: none
:caption: .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
<https://laravel.com/docs/{+laravel-docs-version+}/scout#queueing>`__
of the Laravel Scout documentation and the :ref:`laravel-queues` guide.

.. step:: 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:

.. code-block:: bash

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:

.. code-block:: json

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

.. _laravel-scout-custom-index:

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:

.. code-block:: php

'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
:atlas:`Define Field Mappings
</atlas-search/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.

.. step:: 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:

.. code-block:: bash

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:

.. code-block:: php

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 {+odm-long+} application. To learn
how to perform full-text searches, see the :ref:`laravel-atlas-search`
guide.
Loading