Skip to content

Commit 937fb27

Browse files
rustagirrustagir
authored
DOCSP-46479: document Scout integration (mongodb#3261)
* DOCSP-46479: document Scout integration * NR PR fixes 1 * fix spacing * fix spacing * fix spacing * fix spacing * NR PR fixes 2 * JT tech comment * fix spacing * JT tech review 1 * JT tech review 1 * custom index * link to atlas doc
1 parent f06d944 commit 937fb27

File tree

2 files changed

+261
-0
lines changed

2 files changed

+261
-0
lines changed

‎docs/index.txt

+2
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,7 @@
2222
Databases & Collections </database-collection>
2323
User Authentication </user-authentication>
2424
Cache & Locks </cache>
25+
Scout Integration </scout>
2526
HTTP Sessions </sessions>
2627
Queues </queues>
2728
Transactions </transactions>
@@ -86,6 +87,7 @@ see the following content:
8687
- :ref:`laravel-aggregation-builder`
8788
- :ref:`laravel-user-authentication`
8889
- :ref:`laravel-cache`
90+
- :ref:`laravel-scout`
8991
- :ref:`laravel-sessions`
9092
- :ref:`laravel-queues`
9193
- :ref:`laravel-transactions`

‎docs/scout.txt

+259
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
.. _laravel-scout:
2+
3+
===========================
4+
Full-Text Search with Scout
5+
===========================
6+
7+
.. facet::
8+
:name: genre
9+
:values: reference
10+
11+
.. meta::
12+
:keywords: php framework, odm, code example, text search, atlas
13+
14+
.. contents:: On this page
15+
:local:
16+
:backlinks: none
17+
:depth: 2
18+
:class: singlecol
19+
20+
Overview
21+
--------
22+
23+
In this guide, you can learn how to use the Laravel Scout feature in
24+
your {+odm-long+} application. Scout enables you to implement full-text
25+
search on your Eloquent models. To learn more, see `Laravel Scout
26+
<https://laravel.com/docs/{+laravel-docs-version+}/scout>`__ in the
27+
Laravel documentation.
28+
29+
The Scout integration for {+odm-long+} provides the following
30+
functionality:
31+
32+
- Provides an abstraction to create :atlas:`Atlas Search indexes
33+
</atlas-search/manage-indexes/>` from any MongoDB or SQL model.
34+
35+
.. important:: Use Schema Builder to Create Search Indexes
36+
37+
If your documents are already in MongoDB, create Search indexes
38+
by using {+php-library+} or ``Schema`` builder methods to improve
39+
search query performance. To learn more about creating Search
40+
indexes, see the :ref:`laravel-as-index` section of the Atlas
41+
Search guide.
42+
43+
- Enables you to automatically replicate data from MongoDB into a
44+
search engine such as `Meilisearch <https://www.meilisearch.com/>`__
45+
or `Algolia <https://www.algolia.com/>`__. You can use a MongoDB Eloquent
46+
model as the source to import and index. To learn more about indexing
47+
to a search engine, see the `Indexing
48+
<https://laravel.com/docs/{+laravel-docs-version+}/scout#indexing>`__
49+
section of the Laravel Scout documentation.
50+
51+
.. important:: Deployment Compatibility
52+
53+
You can use Laravel Scout only when you connect to MongoDB Atlas
54+
deployments. This feature is not available for self-managed
55+
deployments.
56+
57+
Scout for Atlas Search Tutorial
58+
-------------------------------
59+
60+
This tutorial demonstrates how to use Scout to compound and index
61+
documents for MongoDB Atlas Search from Eloquent models (MongoDB or SQL).
62+
63+
.. procedure::
64+
:style: connected
65+
66+
.. step:: Install the Scout package
67+
68+
Before you can use Scout in your application, run the following
69+
command from your application's root directory to install the
70+
``laravel/scout`` package:
71+
72+
.. code-block:: bash
73+
74+
composer require laravel/scout
75+
76+
.. step:: Add the Searchable trait to your model
77+
78+
Add the ``Laravel\Scout\Searchable`` trait to an Eloquent model to make
79+
it searchable. The following example adds this trait to the ``Movie``
80+
model, which represents documents in the ``sample_mflix.movies``
81+
collection:
82+
83+
.. code-block:: php
84+
:emphasize-lines: 6, 10
85+
86+
<?php
87+
88+
namespace App\Models;
89+
90+
use MongoDB\Laravel\Eloquent\Model;
91+
use Laravel\Scout\Searchable;
92+
93+
class Movie extends Model
94+
{
95+
use Searchable;
96+
97+
protected $connection = 'mongodb';
98+
}
99+
100+
You can also use the ``Searchable`` trait to reformat documents,
101+
embed related documents, or transform document values. To learn
102+
more, see the `Configuring Searchable Data
103+
<https://laravel.com/docs/{+laravel-docs-version+}/scout#configuring-searchable-data>`__
104+
section of the Laravel Scout documentation.
105+
106+
.. step:: Configure Scout in your application
107+
108+
Ensure that your application is configured to use MongoDB as its
109+
database connection. To learn how to configure MongoDB, see the
110+
:ref:`laravel-quick-start-connect-to-mongodb` section of the Quick Start
111+
guide.
112+
113+
To configure Scout in your application, create a file named
114+
``scout.php`` in your application's ``config`` directory. Paste the
115+
following code into the file to configure Scout:
116+
117+
.. code-block:: php
118+
:caption: config/scout.php
119+
120+
<?php
121+
122+
return [
123+
'driver' => env('SCOUT_DRIVER', 'mongodb'),
124+
'mongodb' => [
125+
'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'),
126+
],
127+
'prefix' => env('SCOUT_PREFIX', 'scout_'),
128+
];
129+
130+
The preceding code specifies the following configuration:
131+
132+
- Uses the value of the ``SCOUT_DRIVER`` environment variable as
133+
the default search driver, or ``mongodb`` if the environment
134+
variable is not set
135+
136+
- Specifies ``scout_`` as the prefix for the collection name of the
137+
searchable collection
138+
139+
In the ``config/scout.php`` file, you can also specify a custom
140+
Atlas Search index definition. To learn more, see the :ref:`custom
141+
index definition example <laravel-scout-custom-index>` in the
142+
following step.
143+
144+
Set the following environment variable in your application's
145+
``.env`` file to select ``mongodb`` as the default search driver:
146+
147+
.. code-block:: none
148+
:caption: .env
149+
150+
SCOUT_DRIVER=mongodb
151+
152+
.. tip:: Queueing
153+
154+
When using Scout, consider configuring a queue driver to reduce
155+
response times for your application's web interface. To learn more,
156+
see the `Queuing section
157+
<https://laravel.com/docs/{+laravel-docs-version+}/scout#queueing>`__
158+
of the Laravel Scout documentation and the :ref:`laravel-queues` guide.
159+
160+
.. step:: Create the Atlas Search index
161+
162+
After you configure Scout and set your default search driver, you can
163+
create your searchable collection and search index by running the
164+
following command from your application's root directory:
165+
166+
.. code-block:: bash
167+
168+
php artisan scout:index 'App\Models\Movie'
169+
170+
Because you set MongoDB as the default search driver, the preceding
171+
command creates the search collection with an Atlas Search index in your
172+
MongoDB database. The collection is named ``scout_movies``, based on the prefix
173+
set in the preceding step. The Atlas Search index is named ``scout``
174+
and has the following configuration by default:
175+
176+
.. code-block:: json
177+
178+
{
179+
"mappings": {
180+
"dynamic": true
181+
}
182+
}
183+
184+
.. _laravel-scout-custom-index:
185+
186+
To customize the index definition, add the ``index-definitions``
187+
configuration to the ``mongodb`` entry in your
188+
``config/scout.php`` file. The following code demonstrates how to
189+
specify a custom index definition to create on the
190+
``scout_movies`` collection:
191+
192+
.. code-block:: php
193+
194+
'mongodb' => [
195+
'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'),
196+
'index-definitions' => [
197+
'scout_movies' => [
198+
'mappings' => [
199+
'dynamic' => false,
200+
'fields' => ['title' => ['type' => 'string']]
201+
]
202+
]
203+
]
204+
], ...
205+
206+
To learn more about defining Atlas Search index definitions, see the
207+
:atlas:`Define Field Mappings
208+
</atlas-search/define-field-mappings/>` guide in the Atlas
209+
documentation.
210+
211+
.. note::
212+
213+
MongoDB can take up to a minute to create and finalize
214+
an Atlas Search index, so the ``scout:index`` command might not
215+
return a success message immediately.
216+
217+
.. step:: Import data into the searchable collection
218+
219+
You can use Scout to replicate data from a source collection
220+
modeled by your Eloquent model into a searchable collection. The
221+
following command replicates and indexes data from the ``movies``
222+
collection into the ``scout_movies`` collection indexed in the
223+
preceding step:
224+
225+
.. code-block:: bash
226+
227+
php artisan scout:import 'App\Models\Movie'
228+
229+
The documents are automatically indexed for Atlas Search queries.
230+
231+
.. tip:: Select Fields to Import
232+
233+
You might not need all the fields from your source documents in your
234+
searchable collection. Limiting the amount of data you replicate can improve
235+
your application's speed and performance.
236+
237+
You can select specific fields to import by defining the
238+
``toSearchableArray()`` method in your Eloquent model class. The
239+
following code demonstrates how to define ``toSearchableArray()`` to
240+
select only the ``plot`` and ``title`` fields for replication:
241+
242+
.. code-block:: php
243+
244+
class Movie extends Model
245+
{
246+
....
247+
public function toSearchableArray(): array
248+
{
249+
return [
250+
'plot' => $this->plot,
251+
'title' => $this->title,
252+
];
253+
}
254+
}
255+
256+
After completing these steps, you can perform Atlas Search queries on the
257+
``scout_movies`` collection in your {+odm-long+} application. To learn
258+
how to perform full-text searches, see the :ref:`laravel-atlas-search`
259+
guide.

0 commit comments

Comments
 (0)