DOCSP-46479: document Scout integration

Author: rustagir

docs/index.txt

@@ -21,6 +21,7 @@
    Query Builder </query-builder>
    User Authentication </user-authentication>
    Cache & Locks </cache>
+   Scout Integration </scout>
    HTTP Sessions </sessions>
    Queues </queues>
    Transactions </transactions>
@@ -85,6 +86,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`

docs/scout.txt

@@ -0,0 +1,198 @@
+.. _laravel-scout:
+
+============================
+Integrated 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 allows 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 search indexes on documents in
+  MongoDB collections and other search engines. In MongoDB, this feature
+  allows you to create :atlas:`Atlas Search indexes
+  </atlas-search/manage-indexes/>`.
+
+- Allows 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.
+
+.. note:: Deployment Compatibility
+
+   You can use Laravel Scout only when you connect to MongoDB Atlas
+   clusters. This feature is not available for self-managed or
+   serverless deployments.
+
+Install Scout Package
+---------------------
+
+Before you can use Scout in your application, you must run the following
+command to install Laravel Scout:
+
+.. code-block:: bash
+   
+   composer require laravel/scout
+
+Add the Searchable Trait to Your Model
+--------------------------------------
+
+Add the ``Laravel\Scout\Searchable`` trait to an Eloquent model to make
+it searchable. This example uses 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';
+   }
+
+Configure Scout Integration
+---------------------------
+
+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 MongoDB as the default search driver
+
+- Specifies ``scout_`` as the prefix for the collection name of the
+  searchable collection used by Scout
+
+.. 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.
+
+Create the 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:
+
+.. 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 section. The Atlas Search index is named ``scout``
+and has the following configuration:
+
+.. code-block:: json
+
+   {
+     "mappings": {
+       "dynamic": true
+     }
+   }
+
+.. note::
+
+   It generally takes up to a minute for MongoDB to create and finalize
+   an Atlas Search index, so the ``scout:index`` command might not
+   return a success message immediately.
+
+Import Your Data into the Searchable Collection
+-----------------------------------------------
+
+You can use Scout to replicate data from a source collection into a
+searchable collection. The following command replicates and indexes data
+from the ``movies`` collection into the ``scout_movies`` collection
+created in the preceding section:
+
+.. code-block:: bash
+
+   php artisan scout:import 'App\Models\Movie'
+
+The documents are automatically indexed for Atlas Search queries.
+
+Select Fields to Import
+~~~~~~~~~~~~~~~~~~~~~~~
+
+You might not need all the fields from your source documents in your
+searchable collection. Limiting the fields 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,
+           ];
+       }
+   }
+
+Use an External Search Engine
+-----------------------------
+
+.. TODO https://jira.mongodb.org/browse/DOCSP-45125