From bd5b0c294b4b7e7744935f96ad2f641ac8076d1b Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 12:09:18 -0500 Subject: [PATCH 01/13] DOCSP-46479: document Scout integration --- docs/index.txt | 2 + docs/scout.txt | 198 +++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) create mode 100644 docs/scout.txt diff --git a/docs/index.txt b/docs/index.txt index 892be3c3e..4e6c8788b 100644 --- a/docs/index.txt +++ b/docs/index.txt @@ -21,6 +21,7 @@ Query Builder User Authentication Cache & Locks + Scout Integration HTTP Sessions Queues 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` diff --git a/docs/scout.txt b/docs/scout.txt new file mode 100644 index 000000000..d8773f523 --- /dev/null +++ b/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 +`__ 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 + `. + +- Allows you to automatically replicate data from MongoDB into a + search engine such as `Meilisearch `__ + or `Algolia `__. 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 + + 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 + `__ + 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 From 239b02aa8390affa464481892ed650bd47b4d0ea Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 15:12:03 -0500 Subject: [PATCH 02/13] NR PR fixes 1 --- docs/scout.txt | 333 +++++++++++++++++++++++++------------------------ 1 file changed, 168 insertions(+), 165 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index d8773f523..26dd064bd 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -1,21 +1,21 @@ .. _laravel-scout: -============================ -Integrated Search with Scout -============================ +=========================== +Full-Text Search with Scout +=========================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: php framework, odm, code example, text search, atlas + :keywords: php framework, odm, code example, text search, atlas .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol Overview -------- @@ -26,11 +26,11 @@ search on your Eloquent models. To learn more, see `Laravel Scout `__ in the Laravel documentation. -The Scout Integration for {+odm-long+} provides the following +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 + MongoDB collections and external search engines. In MongoDB, this feature allows you to create :atlas:`Atlas Search indexes `. @@ -41,158 +41,161 @@ functionality: .. 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 - - 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 - `__ - 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 ------------------------------ + You can use Laravel Scout only when you connect to MongoDB Atlas + clusters. This feature is not available for self-managed or + serverless deployments. + +Scout for Atlas Search Tutorial +------------------------------- + +This section demonstrates how to use the Scout integration in your +application to support Atlas Search queries. + +.. procedure:: + :style: connected + + .. step:: Install Scout package + + Before you can use Scout in your application, run the following + command from your application's root directory to install Laravel Scout: + + .. 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 + + 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 + + .. 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 + `__ + 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 section. The Atlas Search index is named ``scout`` + and has the following configuration: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. 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 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. + + .. tip:: 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, + ]; + } + } + +.. TODO Use an External Search Engine +.. ----------------------------- .. TODO https://jira.mongodb.org/browse/DOCSP-45125 From ccaac919fbe5c9ab97bfdf4a2f5b1b46d5edb79d Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 15:21:14 -0500 Subject: [PATCH 03/13] fix spacing --- docs/scout.txt | 282 ++++++++++++++++++++++++------------------------- 1 file changed, 140 insertions(+), 142 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index 26dd064bd..0fcc5ca69 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -52,148 +52,146 @@ This section demonstrates how to use the Scout integration in your application to support Atlas Search queries. .. procedure:: - :style: connected - - .. step:: Install Scout package - - Before you can use Scout in your application, run the following - command from your application's root directory to install Laravel Scout: - - .. 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 - - 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 - - .. 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 - `__ - 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 section. The Atlas Search index is named ``scout`` - and has the following configuration: - - .. code-block:: json - - { - "mappings": { - "dynamic": true - } - } - - .. 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 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. - - .. tip:: 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, - ]; - } - } + :style: connected + + .. step:: Install Scout package + + Before you can use Scout in your application, run the following + command from your application's root directory to install Laravel Scout: + + .. 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 + + 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 + + .. 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 + `__ + 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 section. The Atlas Search index is named ``scout`` + and has the following configuration: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. 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 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. + + .. tip:: 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, + ]; + } + } .. TODO Use an External Search Engine .. ----------------------------- From 0ee85b18bb1656ee7f8617ce76baccc896722dc4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 15:28:28 -0500 Subject: [PATCH 04/13] fix spacing --- docs/scout.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index 0fcc5ca69..060aca3f1 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -181,17 +181,17 @@ application to support Atlas Search queries. .. code-block:: php - class Movie extends Model - { - .... - public function toSearchableArray(): array - { - return [ - 'plot' => $this->plot, - 'title' => $this->title, - ]; - } - } + class Movie extends Model + { + .... + public function toSearchableArray(): array + { + return [ + 'plot' => $this->plot, + 'title' => $this->title, + ]; + } + } .. TODO Use an External Search Engine .. ----------------------------- From 5edb13d95a135c92e9afed774f31e491d0e8013c Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 15:49:27 -0500 Subject: [PATCH 05/13] fix spacing --- docs/scout.txt | 34 +++++++++++++++++----------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index 060aca3f1..4820ea077 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -104,11 +104,11 @@ application to support Atlas Search queries. env('SCOUT_DRIVER', 'mongodb'), - 'mongodb' => [ - 'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'), - ], - 'prefix' => env('SCOUT_PREFIX', 'scout_'), + 'driver' => env('SCOUT_DRIVER', 'mongodb'), + 'mongodb' => [ + 'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'), + ], + 'prefix' => env('SCOUT_PREFIX', 'scout_'), ]; The preceding code specifies the following configuration: @@ -145,7 +145,7 @@ application to support Atlas Search queries. { "mappings": { - "dynamic": true + "dynamic": true } } @@ -181,17 +181,17 @@ application to support Atlas Search queries. .. code-block:: php - class Movie extends Model - { - .... - public function toSearchableArray(): array - { - return [ - 'plot' => $this->plot, - 'title' => $this->title, - ]; - } - } + class Movie extends Model + { + .... + public function toSearchableArray(): array + { + return [ + 'plot' => $this->plot, + 'title' => $this->title, + ]; + } + } .. TODO Use an External Search Engine .. ----------------------------- From e7b0fe38feeb39da9b669fda447a65787159d160 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 15:59:16 -0500 Subject: [PATCH 06/13] fix spacing --- docs/scout.txt | 300 ++++++++++++++++++++++++------------------------- 1 file changed, 150 insertions(+), 150 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index 4820ea077..da730bd6b 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -5,17 +5,17 @@ Full-Text Search with Scout =========================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: php framework, odm, code example, text search, atlas + :keywords: php framework, odm, code example, text search, atlas .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol Overview -------- @@ -41,9 +41,9 @@ functionality: .. 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. + You can use Laravel Scout only when you connect to MongoDB Atlas + clusters. This feature is not available for self-managed or + serverless deployments. Scout for Atlas Search Tutorial ------------------------------- @@ -52,146 +52,146 @@ This section demonstrates how to use the Scout integration in your application to support Atlas Search queries. .. procedure:: - :style: connected - - .. step:: Install Scout package - - Before you can use Scout in your application, run the following - command from your application's root directory to install Laravel Scout: - - .. 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 - - 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 - - .. 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 - `__ - 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 section. The Atlas Search index is named ``scout`` - and has the following configuration: - - .. code-block:: json - - { - "mappings": { - "dynamic": true - } - } - - .. 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 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. - - .. tip:: 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, - ]; - } - } + :style: connected + + .. step:: Install Scout package + + Before you can use Scout in your application, run the following + command from your application's root directory to install Laravel Scout: + + .. 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 + + 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 + + .. 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 + `__ + 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 section. The Atlas Search index is named ``scout`` + and has the following configuration: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. 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 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. + + .. tip:: 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, + ]; + } + } .. TODO Use an External Search Engine .. ----------------------------- From 45a7e79076ce8dd610f57a40b2fadeeec931a5a8 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Feb 2025 16:36:40 -0500 Subject: [PATCH 07/13] NR PR fixes 2 --- docs/scout.txt | 305 +++++++++++++++++++++++++------------------------ 1 file changed, 155 insertions(+), 150 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index da730bd6b..f224dee11 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -5,17 +5,17 @@ Full-Text Search with Scout =========================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: php framework, odm, code example, text search, atlas + :keywords: php framework, odm, code example, text search, atlas .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol Overview -------- @@ -41,9 +41,9 @@ functionality: .. 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. + You can use Laravel Scout only when you connect to MongoDB Atlas + clusters. This feature is not available for self-managed or + serverless deployments. Scout for Atlas Search Tutorial ------------------------------- @@ -52,146 +52,151 @@ This section demonstrates how to use the Scout integration in your application to support Atlas Search queries. .. procedure:: - :style: connected - - .. step:: Install Scout package - - Before you can use Scout in your application, run the following - command from your application's root directory to install Laravel Scout: - - .. 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 - - 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 - - .. 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 - `__ - 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 section. The Atlas Search index is named ``scout`` - and has the following configuration: - - .. code-block:: json - - { - "mappings": { - "dynamic": true - } - } - - .. 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 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. - - .. tip:: 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, - ]; - } - } + :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 Laravel Scout: + + .. 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 + + 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 + + .. 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 + `__ + 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: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. 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 into a + searchable collection. The following command replicates and indexes data + from the ``movies`` collection into the ``scout_movies`` collection + created 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 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, + ]; + } + } + +After completing these steps, you can perform Atlas Search queries on the +``scout_movies`` collection in your {+odm-long+} application. + +.. TODO add link to Atlas Search guide .. TODO Use an External Search Engine .. ----------------------------- From 33a0275b872debb6b53066f1d5b5bbb06e5e7fc9 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 4 Feb 2025 09:31:51 -0500 Subject: [PATCH 08/13] JT tech comment --- docs/scout.txt | 299 +++++++++++++++++++++++++------------------------ 1 file changed, 155 insertions(+), 144 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index f224dee11..bf21967b4 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -5,17 +5,17 @@ Full-Text Search with Scout =========================== .. facet:: - :name: genre - :values: reference + :name: genre + :values: reference .. meta:: - :keywords: php framework, odm, code example, text search, atlas + :keywords: php framework, odm, code example, text search, atlas .. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol + :local: + :backlinks: none + :depth: 2 + :class: singlecol Overview -------- @@ -41,9 +41,9 @@ functionality: .. 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. + You can use Laravel Scout only when you connect to MongoDB Atlas + clusters. This feature is not available for self-managed or + serverless deployments. Scout for Atlas Search Tutorial ------------------------------- @@ -52,146 +52,157 @@ This section demonstrates how to use the Scout integration in your application to support Atlas Search queries. .. 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 Laravel Scout: - - .. 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 - - 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 + + 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 + `__ + 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: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. 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 into a + searchable collection. The following command replicates and indexes data + from the ``movies`` collection into the ``scout_movies`` collection + created 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 fields you replicate can improve + your application's speed and performance. - class Movie extends Model - { - use Searchable; - - protected $connection = 'mongodb'; - } - - .. 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 - - 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 - - .. 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 - `__ - 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: - - .. code-block:: json - + .. code-block:: php + + class Movie extends Model { - "mappings": { - "dynamic": true - } - } - - .. 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 into a - searchable collection. The following command replicates and indexes data - from the ``movies`` collection into the ``scout_movies`` collection - created 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 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 { - .... - public function toSearchableArray(): array - { - return [ - 'plot' => $this->plot, - 'title' => $this->title, - ]; - } + 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. From eac4c214d184999b88ffff83aa67896fc78a576d Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 4 Feb 2025 09:43:41 -0500 Subject: [PATCH 09/13] fix spacing --- docs/scout.txt | 272 ++++++++++++++++++++++++------------------------- 1 file changed, 136 insertions(+), 136 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index bf21967b4..9f4593853 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -55,154 +55,154 @@ application to support Atlas Search queries. :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 Laravel Scout: - - .. code-block:: bash - - composer require laravel/scout + + Before you can use Scout in your application, run the following + command from your application's root directory to install Laravel Scout: + + .. 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 - - 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 - - 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 - `__ - of the Laravel Scout documentation and the :ref:`laravel-queues` guide. + 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 + + 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 + + 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 + `__ + 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: - - .. code-block:: json - - { - "mappings": { - "dynamic": true - } - } - - .. 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. + 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: + + .. code-block:: json + + { + "mappings": { + "dynamic": true + } + } + + .. 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 into a - searchable collection. The following command replicates and indexes data - from the ``movies`` collection into the ``scout_movies`` collection - created 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 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, - ]; - } - } + 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 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 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, + ]; + } + } After completing these steps, you can perform Atlas Search queries on the ``scout_movies`` collection in your {+odm-long+} application. From 619fe56f802b8a94bd6bd5251174b9b23a6ae287 Mon Sep 17 00:00:00 2001 From: rustagir Date: Thu, 6 Feb 2025 14:53:41 -0500 Subject: [PATCH 10/13] JT tech review 1 --- docs/scout.txt | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index 9f4593853..ffe0e1bb3 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -29,10 +29,14 @@ 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 external search engines. In MongoDB, this feature - allows you to create :atlas:`Atlas Search indexes - `. +- Provides an abstraction to create :atlas:`Atlas Search indexes + ` from any MongoDB or SQL model. + + .. tip:: + + We recommend creating Search indexes by using the ``Schema`` + builder methods. To learn more, see the :ref:`TODO DOCSP-46230` + section of the Atlas Search guide. - Allows you to automatically replicate data from MongoDB into a search engine such as `Meilisearch `__ @@ -42,7 +46,7 @@ functionality: .. 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 + deployments. This feature is not available for self-managed or serverless deployments. Scout for Atlas Search Tutorial From e02220ae4919f146fe4643ca1db470849695c59e Mon Sep 17 00:00:00 2001 From: rustagir Date: Wed, 26 Feb 2025 14:14:02 -0500 Subject: [PATCH 11/13] JT tech review 1 --- docs/scout.txt | 86 +++++++++++++++++++++++++++++++++++--------------- 1 file changed, 60 insertions(+), 26 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index ffe0e1bb3..ee5f975f5 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -32,28 +32,33 @@ functionality: - Provides an abstraction to create :atlas:`Atlas Search indexes ` from any MongoDB or SQL model. - .. tip:: + .. important:: Use Schema Builder to Create Search Indexes - We recommend creating Search indexes by using the ``Schema`` - builder methods. To learn more, see the :ref:`TODO DOCSP-46230` - section of the Atlas Search guide. + 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. - Allows you to automatically replicate data from MongoDB into a search engine such as `Meilisearch `__ or `Algolia `__. You can use a MongoDB Eloquent - model as the source to import and index. + model as the source to import and index. To learn more about indexing + to a search engine, see the `Indexing + `__ + section of the Laravel Scout documentation. -.. note:: Deployment Compatibility +.. important:: Deployment Compatibility You can use Laravel Scout only when you connect to MongoDB Atlas - deployments. This feature is not available for self-managed or - serverless deployments. + deployments. This feature is not available for self-managed + deployments. Scout for Atlas Search Tutorial ------------------------------- -This section demonstrates how to use the Scout integration in your -application to support Atlas Search queries. +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 @@ -61,7 +66,8 @@ application to support Atlas Search queries. .. 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 Laravel Scout: + command from your application's root directory to install the + ``laravel/scout`` package: .. code-block:: bash @@ -91,6 +97,12 @@ application to support Atlas Search queries. protected $connection = 'mongodb'; } + The ``Searchable`` trait also allows you to reformat documents, + embed related documents, or transform document values. To learn + more, see the `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 @@ -124,6 +136,11 @@ application to support Atlas Search queries. - 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 ` in the + following step. + Set the following environment variable in your application's ``.env`` file to select ``mongodb`` as the default search driver: @@ -154,7 +171,7 @@ application to support Atlas Search queries. 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: + and has the following configuration by default: .. code-block:: json @@ -163,7 +180,28 @@ application to support Atlas Search queries. "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 for the ``scout_index`` index: + + .. code-block:: php + + 'mongodb' => [ + 'connection' => env('SCOUT_MONGODB_CONNECTION', 'mongodb'), + 'index-definitions' => [ + 'scout_index' => [ + 'mappings' => [ + 'dynamic' => false, + 'fields' => ['title' => ['type' => 'string']] + ] + ] + ] + ], ... + .. note:: MongoDB can take up to a minute to create and finalize @@ -172,10 +210,11 @@ application to support Atlas Search queries. .. step:: Import 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 step: + 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 @@ -186,7 +225,7 @@ application to support 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 fields you replicate can improve + 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 @@ -209,11 +248,6 @@ application to support Atlas Search queries. } After completing these steps, you can perform Atlas Search queries on the -``scout_movies`` collection in your {+odm-long+} application. - -.. TODO add link to Atlas Search guide - -.. TODO Use an External Search Engine -.. ----------------------------- - -.. TODO https://jira.mongodb.org/browse/DOCSP-45125 +``scout_movies`` collection in your {+odm-long+} application. To learn +how to perform full-text searches, see the :ref:`laravel-atlas-search` +guide. From 7c988f0418134253e58e2f4f581a8f4be045b1d2 Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Mar 2025 11:27:29 -0500 Subject: [PATCH 12/13] custom index --- docs/scout.txt | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index ee5f975f5..d22375cb0 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -186,14 +186,15 @@ documents for MongoDB Atlas Search from Eloquent models (MongoDB or SQL). 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 for the ``scout_index`` index: + 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_index' => [ + 'scout_movies' => [ 'mappings' => [ 'dynamic' => false, 'fields' => ['title' => ['type' => 'string']] From fbf203ec9083b5667f861d339848ea09c8e807bc Mon Sep 17 00:00:00 2001 From: rustagir Date: Mon, 3 Mar 2025 14:06:20 -0500 Subject: [PATCH 13/13] link to atlas doc --- docs/scout.txt | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/scout.txt b/docs/scout.txt index d22375cb0..8f409148b 100644 --- a/docs/scout.txt +++ b/docs/scout.txt @@ -21,7 +21,7 @@ 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 +your {+odm-long+} application. Scout enables you to implement full-text search on your Eloquent models. To learn more, see `Laravel Scout `__ in the Laravel documentation. @@ -40,7 +40,7 @@ functionality: indexes, see the :ref:`laravel-as-index` section of the Atlas Search guide. -- Allows you to automatically replicate data from MongoDB into a +- Enables you to automatically replicate data from MongoDB into a search engine such as `Meilisearch `__ or `Algolia `__. You can use a MongoDB Eloquent model as the source to import and index. To learn more about indexing @@ -97,7 +97,7 @@ documents for MongoDB Atlas Search from Eloquent models (MongoDB or SQL). protected $connection = 'mongodb'; } - The ``Searchable`` trait also allows you to reformat documents, + 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 `__ @@ -203,6 +203,11 @@ documents for MongoDB Atlas Search from Eloquent models (MongoDB or SQL). ] ], ... + To learn more about defining Atlas Search index definitions, see the + :atlas:`Define Field Mappings + ` guide in the Atlas + documentation. + .. note:: MongoDB can take up to a minute to create and finalize