Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 0d6a572

Browse files
Merge 5.2 into 5.x (#3303)
2 parents 153af6c + 937fb27 commit 0d6a572

File tree

2 files changed

+261
-0
lines changed

2 files changed

+261
-0
lines changed

‎docs/index.txt

Lines changed: 2 additions & 0 deletions
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

Lines changed: 259 additions & 0 deletions
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)

AltStyle によって変換されたページ (->オリジナル) /