DOCSP-46479: document Scout integration

docs/index.txt

@@ -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>
@@ -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`

docs/scout.txt

@@ -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.