@@ -29,6 +29,7 @@ This guide shows you how to perform the following tasks:
29
29
30
30
- :ref:`laravel-retrieve-matching`
31
31
- :ref:`laravel-retrieve-all`
32
+ - :ref:`laravel-retrieve-text-search`
32
33
- :ref:`Modify Find Operation Behavior <laravel-modify-find>`
33
34
34
35
Before You Get Started
@@ -175,6 +176,121 @@ Use the following syntax to run a find operation that matches all documents:
175
176
more information about ``take()``, see the :ref:`laravel-modify-find` section of this
176
177
guide.
177
178
179
+ .. _laravel-retrieve-text-search:
180
+
181
+ Search Text Fields
182
+ ------------------
183
+
184
+ A text search retrieves documents that contain a **term** or a **phrase** in the
185
+ text-indexed fields. A term is a sequence of characters that excludes
186
+ whitespace characters. A phrase is a sequence of terms with any number
187
+ of whitespace characters.
188
+
189
+ .. note::
190
+
191
+ Before you can perform a text search, you must create a :manual:`text
192
+ index </core/indexes/index-types/index-text/>` on
193
+ the text-valued field. To learn more about creating
194
+ indexes, see the :ref:`laravel-eloquent-indexes` section of the
195
+ Schema Builder guide.
196
+
197
+ You can perform a text search by using the :manual:`$text
198
+ </reference/operator/query/text>` operator followed
199
+ by the ``$search`` field in your query filter that you pass to the
200
+ ``where()`` method. The ``$text`` operator performs a text search on the
201
+ text-indexed fields. The ``$search`` field specifies the text to search for.
202
+
203
+ After building your query with the ``where()`` method, chain the ``get()``
204
+ method to retrieve the query results.
205
+
206
+ This example calls the ``where()`` method on the ``Movie`` Eloquent model to
207
+ retrieve documents in which the ``plot`` field contains the phrase
208
+ ``"love story"``. To perform this text search, the collection must have
209
+ a text index on the ``plot`` field.
210
+
211
+ .. tabs::
212
+
213
+ .. tab:: Query Syntax
214
+ :tabid: query-syntax
215
+
216
+ Use the following syntax to specify the query:
217
+
218
+ .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php
219
+ :language: php
220
+ :dedent:
221
+ :start-after: start-text
222
+ :end-before: end-text
223
+
224
+ .. tab:: Controller Method
225
+ :tabid: controller
226
+
227
+ To see the query results in the ``browse_movies`` view, edit the ``show()`` function
228
+ in the ``MovieController.php`` file to resemble the following code:
229
+
230
+ .. io-code-block::
231
+ :copyable: true
232
+
233
+ .. input::
234
+ :language: php
235
+
236
+ class MovieController
237
+ {
238
+ public function show()
239
+ {
240
+ $movies = Movie::where('$text', ['$search' => '"love story"'])
241
+ ->get();
242
+
243
+ return view('browse_movies', [
244
+ 'movies' => $movies
245
+ ]);
246
+ }
247
+ }
248
+
249
+ .. output::
250
+ :language: none
251
+ :visible: false
252
+
253
+ Title: Cafè de Flore
254
+ Year: 2011
255
+ Runtime: 120
256
+ IMDB Rating: 7.4
257
+ IMDB Votes: 9663
258
+ Plot: A love story between a man and woman ...
259
+
260
+ Title: Paheli
261
+ Year: 2005
262
+ Runtime: 140
263
+ IMDB Rating: 6.7
264
+ IMDB Votes: 8909
265
+ Plot: A folk tale - supernatural love story about a ghost ...
266
+
267
+ Title: Por un puèado de besos
268
+ Year: 2014
269
+ Runtime: 98
270
+ IMDB Rating: 6.1
271
+ IMDB Votes: 223
272
+ Plot: A girl. A boy. A love story ...
273
+
274
+ ...
275
+
276
+ A text search assigns a numerical :manual:`text score </reference/operator/query/text/#text-score>` to indicate how closely
277
+ each result matches the string in your query filter. You can sort the
278
+ results by relevance by using the ``orderBy()`` method to sort on the
279
+ ``textScore`` metadata field. You can access this metadata by using the
280
+ :manual:`$meta </reference/operator/aggregation/meta/>` operator:
281
+
282
+ .. literalinclude:: /includes/fundamentals/read-operations/ReadOperationsTest.php
283
+ :language: php
284
+ :dedent:
285
+ :start-after: start-text-relevance
286
+ :end-before: end-text-relevance
287
+ :emphasize-lines: 2
288
+
289
+ .. tip::
290
+
291
+ To learn more about the ``orderBy()`` method, see the
292
+ :ref:`laravel-sort` section of this guide.
293
+
178
294
.. _laravel-modify-find:
179
295
180
296
Modify Behavior
0 commit comments