From 034c6e85791deed889644ec462f80efd2e1e6065 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 10:38:04 -0500 Subject: [PATCH 01/12] DOCSP-46230: atlas search index mgmt --- docs/eloquent-models/schema-builder.txt | 95 +++++++++++ docs/fundamentals/atlas-search.txt | 148 ++++++++++-------- docs/fundamentals/vector-search.txt | 27 +++- .../schema-builder/galaxies_migration.php | 58 +++++++ 4 files changed, 262 insertions(+), 66 deletions(-) create mode 100644 docs/includes/schema-builder/galaxies_migration.php diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index dad3c8eed..0f659bdbe 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -399,4 +399,99 @@ from the ``flights`` collection: :start-after: begin drop index :end-before: end drop index +.. _laravel-schema-builder-atlas-idx: +Manage Atlas Search and Vector Search Indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In MongoDB, :atlas:`Atlas Search indexes +` support your full-text queries. +:atlas:`Atlas Vector Search indexes +` support similarity +searches that compare query vectors to vector embeddings in your +documents. + +View the following guides to learn more about the Atlas Search and +Vector Search features: + +- :ref:`laravel-atlas-search` guide +- :ref:`laravel-vector-search` guide + +Atlas Search +```````````` + +To create Atlas Search indexes, call the ``create()`` method on the +``Schema`` facade in your migration file. Pass ``create()`` the +collection name and a callback method with a +``MongoDB\Laravel\Schema\Blueprint`` parameter. Pass the Atlas index +creation details to the ``searchIndex()`` method on the ``Blueprint`` +instance. + +This example migration creates the following Atlas Search indexes on the +``galaxies`` collection: + +- ``dynamic_index``: Creates dynamic mappings +- ``auto_index``: Supports autocomplete queries on the ``name`` field + +Click the :guilabel:`{+code-output-label+}` button to see the Search +indexes created by running the migration: + +.. io-code-block:: + .. input:: /includes/schema-builder/galaxies_migration.php + :language: php + :dedent: + :start-after: begin-create-search-indexes + :end-before: end-create-search-indexes + + .. output:: + :language: json + :visible: false + + WIP + +Vector Search +````````````` + +To create Vector Search indexes, call the ``create()`` method on the +``Schema`` facade in your migration file. Pass ``create()`` the +collection name and a callback method with a +``MongoDB\Laravel\Schema\Blueprint`` parameter. Pass the Atlas index +creation details to the ``vectorSearchIndex()`` method on the ``Blueprint`` +instance. + +The following example migration creates a Vector Search index called +``vs_index`` on the ``galaxies`` collection. + +Click the :guilabel:`{+code-output-label+}` button to see the Search +indexes created by running the migration: + +.. io-code-block:: + .. input:: /includes/schema-builder/galaxies_migration.php + :language: php + :dedent: + :start-after: begin-create-vs-index + :end-before: end-create-vs-index + + .. output:: + :language: json + :visible: false + + WIP + +Drop a Search Index +``````````````````` + +To drop an Atlas Search or Vector Search index from a collection, call +the ``table()`` method on the ``Schema`` facade in your migration file. +Pass it the collection name and a callback method with a +``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the ``dropSearchIndex()`` +method with the Search index name on the ``Blueprint`` instance. + +The following example migration drops an index called ``auto_index`` +from the ``galaxies`` collection: + +.. literalinclude:: /includes/schema-builder/galaxies_migration.php + :language: php + :dedent: + :start-after: begin-drop-search-index + :end-before: end-drop-search-index diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index 9aaa9156b..f7d6e4415 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -56,7 +56,25 @@ documentation. Create an Atlas Search Index ---------------------------- -.. TODO in DOCSP-46230 +You can create an Atlas Search index in either of the following ways: + +- Call the ``create()`` method on the ``Schema`` facade and pass the + ``searchIndex()`` helper method with index creation details. To learn + more about this strategy, see the + :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. + +- Access a collection, then call the + :phpmethod:`MongoDB\Collection::createSearchIndex()` from the + {+php-library+}, as shown in the following code: + + .. code-block:: php + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], + ['name' => 'search_index'] + ); Perform Queries --------------- @@ -93,23 +111,23 @@ model's ``title`` field for the term ``'dream'``: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-search-query - :end-before: end-search-query + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query .. output:: - :language: json - :visible: false - - [ - { "title": "Dreaming of Jakarta", - "year": 1990 - }, - { "title": "See You in My Dreams", - "year": 1996 - } - ] + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] You can use the ``search()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the @@ -119,55 +137,55 @@ following optional parameters to ``search()``: :header-rows: 1 * - Optional Parameter - - Type - - Description + - Type + - Description * - ``index`` - - ``string`` - - Provides the name of the Atlas Search index to use + - ``string`` + - Provides the name of the Atlas Search index to use * - ``highlight`` - - ``array`` - - Specifies highlighting options for displaying search terms in their - original context + - ``array`` + - Specifies highlighting options for displaying search terms in their + original context * - ``concurrent`` - - ``bool`` - - Parallelizes search query across segments on dedicated search nodes + - ``bool`` + - Parallelizes search query across segments on dedicated search nodes * - ``count`` - - ``string`` - - Specifies the count options for retrieving a count of the results + - ``string`` + - Specifies the count options for retrieving a count of the results * - ``searchAfter`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately following that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately following that point * - ``searchBefore`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately preceding that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately preceding that point * - ``scoreDetails`` - - ``bool`` - - Specifies whether to retrieve a detailed breakdown of the score - for results + - ``bool`` + - Specifies whether to retrieve a detailed breakdown of the score + for results * - ``sort`` - - ``array`` - - Specifies the fields on which to sort the results + - ``array`` + - Specifies the fields on which to sort the results * - ``returnStoredSource`` - - ``bool`` - - Specifies whether to perform a full document lookup on the - backend database or return only stored source fields directly - from Atlas Search + - ``bool`` + - Specifies whether to perform a full document lookup on the + backend database or return only stored source fields directly + from Atlas Search * - ``tracking`` - - ``array`` - - Specifies the tracking option to retrieve analytics information - on the search terms + - ``array`` + - Specifies the tracking option to retrieve analytics information + on the search terms To learn more about these parameters, see the :atlas:`Fields ` section of the @@ -200,20 +218,20 @@ string ``"jak"`` on the ``title`` field: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-auto-query - :end-before: end-auto-query + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - [ - "Dreaming of Jakarta", - "Jakob the Liar", - "Emily Calling Jake" - ] + [ + "Dreaming of Jakarta", + "Jakob the Liar", + "Emily Calling Jake" + ] You can also pass the following optional parameters to the ``autocomplete()`` method to customize the query: @@ -222,19 +240,19 @@ method to customize the query: :header-rows: 1 * - Optional Parameter - - Type - - Description - - Default Value + - Type + - Description + - Default Value * - ``fuzzy`` - - ``bool`` or ``array`` - - Enables fuzzy search and fuzzy search options - - ``false`` + - ``bool`` or ``array`` + - Enables fuzzy search and fuzzy search options + - ``false`` * - ``tokenOrder`` - - ``string`` - - Specifies order in which to search for tokens - - ``'any'`` + - ``string`` + - Specifies order in which to search for tokens + - ``'any'`` To learn more about these parameters, see the :atlas:`Options ` section of the diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 116cb75a0..22dc06246 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -56,7 +56,32 @@ documentation. Create an Atlas Vector Search Index ----------------------------------- -.. TODO in DOCSP-46230 +You can create an Atlas Search index in either of the following ways: + +- Call the ``create()`` method on the ``Schema`` facade and pass the + ``vectorSearchIndex()`` helper method with index creation details. To learn + more about this strategy, see the + :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. + +- Access a collection, then call the + :phpmethod:`MongoDB\Collection::createSearchIndex()` from the + {+php-library+}. You must specify the ``type`` option as + ``'vectorSearch'``, as shown in the following code: + + .. code-block:: php + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex([ + 'fields' => [ + [ + 'type' => 'vector', + 'numDimensions' => 4, + 'path' => 'embeddings', + 'similarity' => 'cosine' + ], + ], + ], ['name' => 'vector_index', 'type' => 'vectorSearch']); Perform Queries --------------- diff --git a/docs/includes/schema-builder/galaxies_migration.php b/docs/includes/schema-builder/galaxies_migration.php new file mode 100644 index 000000000..ca67ca10a --- /dev/null +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -0,0 +1,58 @@ +searchIndex([ + 'mappings' => [ + 'dynamic' => true, + ], + ], 'dynamic_index'); + $collection->searchIndex([ + 'mappings' => [ + 'fields' => [ + 'name' => [ + ['type' => 'string', 'analyzer' => 'lucene.english'], + ['type' => 'autocomplete', 'analyzer' => 'lucene.english'], + ['type' => 'token'], + ], + ], + ], + ], 'auto_index'); + }); + // end-create-search-indexes + + // start-create-vs-index + Schema::create('galaxies', function (Blueprint $collection) { + $collection->vectorSearchIndex([ + 'fields' => [[ + 'type' => 'vector', + 'numDimensions' => 4, + 'path' => 'vector4', + 'similarity' => 'cosine' + ]], + ], 'vs_index'); + }); + // end-create-vs-index + } + + public function down(): void + { + // begin-drop-search-index + Schema::table('galaxies', function (Blueprint $collection) { + $collection->dropSearchIndex('auto_index'); + }); + // end-drop-search-index + } +}; From 532172c3f7dc26e122bbb10c4eb2dd43f9a80a0e Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 10:40:07 -0500 Subject: [PATCH 02/12] fix --- docs/fundamentals/atlas-search.txt | 140 ++++++++++++++--------------- 1 file changed, 70 insertions(+), 70 deletions(-) diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index f7d6e4415..0b0685287 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -68,12 +68,12 @@ You can create an Atlas Search index in either of the following ways: {+php-library+}, as shown in the following code: .. code-block:: php - - $collection = DB::connection('mongodb')->getCollection('movies'); - - $collection->createSearchIndex( - ['mappings' => ['dynamic' => true]], - ['name' => 'search_index'] + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], + ['name' => 'search_index'] ); Perform Queries @@ -111,23 +111,23 @@ model's ``title`` field for the term ``'dream'``: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-search-query - :end-before: end-search-query + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query .. output:: - :language: json - :visible: false - - [ - { "title": "Dreaming of Jakarta", - "year": 1990 - }, - { "title": "See You in My Dreams", - "year": 1996 - } - ] + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] You can use the ``search()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the @@ -137,55 +137,55 @@ following optional parameters to ``search()``: :header-rows: 1 * - Optional Parameter - - Type - - Description + - Type + - Description * - ``index`` - - ``string`` - - Provides the name of the Atlas Search index to use + - ``string`` + - Provides the name of the Atlas Search index to use * - ``highlight`` - - ``array`` - - Specifies highlighting options for displaying search terms in their - original context + - ``array`` + - Specifies highlighting options for displaying search terms in their + original context * - ``concurrent`` - - ``bool`` - - Parallelizes search query across segments on dedicated search nodes + - ``bool`` + - Parallelizes search query across segments on dedicated search nodes * - ``count`` - - ``string`` - - Specifies the count options for retrieving a count of the results + - ``string`` + - Specifies the count options for retrieving a count of the results * - ``searchAfter`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately following that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately following that point * - ``searchBefore`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately preceding that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately preceding that point * - ``scoreDetails`` - - ``bool`` - - Specifies whether to retrieve a detailed breakdown of the score - for results + - ``bool`` + - Specifies whether to retrieve a detailed breakdown of the score + for results * - ``sort`` - - ``array`` - - Specifies the fields on which to sort the results + - ``array`` + - Specifies the fields on which to sort the results * - ``returnStoredSource`` - - ``bool`` - - Specifies whether to perform a full document lookup on the - backend database or return only stored source fields directly - from Atlas Search + - ``bool`` + - Specifies whether to perform a full document lookup on the + backend database or return only stored source fields directly + from Atlas Search * - ``tracking`` - - ``array`` - - Specifies the tracking option to retrieve analytics information - on the search terms + - ``array`` + - Specifies the tracking option to retrieve analytics information + on the search terms To learn more about these parameters, see the :atlas:`Fields ` section of the @@ -218,20 +218,20 @@ string ``"jak"`` on the ``title`` field: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-auto-query - :end-before: end-auto-query + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - [ - "Dreaming of Jakarta", - "Jakob the Liar", - "Emily Calling Jake" - ] + [ + "Dreaming of Jakarta", + "Jakob the Liar", + "Emily Calling Jake" + ] You can also pass the following optional parameters to the ``autocomplete()`` method to customize the query: @@ -240,19 +240,19 @@ method to customize the query: :header-rows: 1 * - Optional Parameter - - Type - - Description - - Default Value + - Type + - Description + - Default Value * - ``fuzzy`` - - ``bool`` or ``array`` - - Enables fuzzy search and fuzzy search options - - ``false`` + - ``bool`` or ``array`` + - Enables fuzzy search and fuzzy search options + - ``false`` * - ``tokenOrder`` - - ``string`` - - Specifies order in which to search for tokens - - ``'any'`` + - ``string`` + - Specifies order in which to search for tokens + - ``'any'`` To learn more about these parameters, see the :atlas:`Options ` section of the From 77d77f5e9d0b09f86a25bf6c2f7c80668d97ce7a Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 10:40:38 -0500 Subject: [PATCH 03/12] fix --- .../includes/schema-builder/galaxies_migration.php | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/includes/schema-builder/galaxies_migration.php b/docs/includes/schema-builder/galaxies_migration.php index ca67ca10a..cde49d33e 100644 --- a/docs/includes/schema-builder/galaxies_migration.php +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -36,12 +36,14 @@ public function up(): void // start-create-vs-index Schema::create('galaxies', function (Blueprint $collection) { $collection->vectorSearchIndex([ - 'fields' => [[ - 'type' => 'vector', - 'numDimensions' => 4, - 'path' => 'vector4', - 'similarity' => 'cosine' - ]], + 'fields' => [ + [ + 'type' => 'vector', + 'numDimensions' => 4, + 'path' => 'vector4', + 'similarity' => 'cosine', + ], + ], ], 'vs_index'); }); // end-create-vs-index From 0f5006580db47779a359d5d92a807013c562f76c Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 13:04:41 -0500 Subject: [PATCH 04/12] small fix --- docs/fundamentals/atlas-search.txt | 2 +- docs/fundamentals/vector-search.txt | 2 +- docs/includes/schema-builder/galaxies_migration.php | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index 0b0685287..e1ed0d190 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -64,7 +64,7 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`MongoDB\Collection::createSearchIndex()` from the + :phpmethod:`MongoDB\Collection::createSearchIndex()` method from the {+php-library+}, as shown in the following code: .. code-block:: php diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 22dc06246..cb29b0300 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -64,7 +64,7 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`MongoDB\Collection::createSearchIndex()` from the + :phpmethod:`MongoDB\Collection::createSearchIndex()` method from the {+php-library+}. You must specify the ``type`` option as ``'vectorSearch'``, as shown in the following code: diff --git a/docs/includes/schema-builder/galaxies_migration.php b/docs/includes/schema-builder/galaxies_migration.php index cde49d33e..df4188a38 100644 --- a/docs/includes/schema-builder/galaxies_migration.php +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -33,7 +33,7 @@ public function up(): void }); // end-create-search-indexes - // start-create-vs-index + // begin-create-vs-index Schema::create('galaxies', function (Blueprint $collection) { $collection->vectorSearchIndex([ 'fields' => [ From 7efe5b17cf30f16a437219ae01cf268cbaf96356 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 13:58:30 -0500 Subject: [PATCH 05/12] wip --- docs/eloquent-models/schema-builder.txt | 277 ++++++++++-------- docs/fundamentals/atlas-search.txt | 146 ++++----- docs/fundamentals/vector-search.txt | 4 +- .../schema-builder/galaxies_migration.php | 2 +- docs/query-builder.txt | 2 +- 5 files changed, 237 insertions(+), 194 deletions(-) diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 0f659bdbe..f9f6170a8 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -76,7 +76,7 @@ following changes to perform the schema changes on your MongoDB database: specifies the correct database: - Make sure your ``connections`` array item contains a valid ``mongodb`` - entry in your ``config/database.php`` file + entry in your ``config/database.php`` file - Specify ``"mongodb"`` in the ``$connection`` field of your migration class The following example migration class contains the following methods: @@ -175,30 +175,30 @@ the migration, including the default index on the ``_id`` field: .. io-code-block:: .. input:: /includes/schema-builder/flights_migration.php - :language: php - :dedent: - :start-after: begin create index - :end-before: end create index + :language: php + :dedent: + :start-after: begin create index + :end-before: end create index .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' }, - { - v: 2, - key: { launch_location: 1, launch_date: -1 }, - name: 'launch_location_1_launch_date_-1' - }, - { - v: 2, - key: { mission_id: 1 }, - name: 'unique_mission_id_idx', - unique: true - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' }, + { + v: 2, + key: { launch_location: 1, launch_date: -1 }, + name: 'launch_location_1_launch_date_-1' + }, + { + v: 2, + key: { mission_id: 1 }, + name: 'unique_mission_id_idx', + unique: true + } + ] Specify Index Options ~~~~~~~~~~~~~~~~~~~~~ @@ -215,35 +215,35 @@ field: .. io-code-block:: .. input:: /includes/schema-builder/passengers_migration.php - :language: php - :dedent: - :start-after: begin index options - :end-before: end index options + :language: php + :dedent: + :start-after: begin index options + :end-before: end index options .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { - v: 2, - key: { last_name: 1 }, - name: 'passengers_collation_idx', - collation: { - locale: 'de@collation=phonebook', - caseLevel: false, - caseFirst: 'off', - strength: 3, - numericOrdering: true, - alternate: 'non-ignorable', - maxVariable: 'punct', - normalization: false, - backwards: false, - version: '57.1' - } - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_name: 1 }, + name: 'passengers_collation_idx', + collation: { + locale: 'de@collation=phonebook', + caseLevel: false, + caseFirst: 'off', + strength: 3, + numericOrdering: true, + alternate: 'non-ignorable', + maxVariable: 'punct', + normalization: false, + backwards: false, + version: '57.1' + } + } + ] To learn more about index options, see :manual:`Options for All Index Types ` in the {+server-docs-name+}. @@ -276,25 +276,25 @@ the ``_id`` field: .. io-code-block:: .. input:: /includes/schema-builder/planets_migration.php - :language: php - :dedent: - :start-after: begin index helpers - :end-before: end index helpers + :language: php + :dedent: + :start-after: begin index helpers + :end-before: end index helpers .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true }, - { - v: 2, - key: { last_visible_dt: 1 }, - name: 'last_visible_dt_1', - expireAfterSeconds: 86400 - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + expireAfterSeconds: 86400 + } + ] You can specify sparse, TTL, and unique indexes on either a single field or compound index by specifying them in the index options. @@ -307,26 +307,26 @@ field: .. io-code-block:: .. input:: /includes/schema-builder/planets_migration.php - :language: php - :dedent: - :start-after: begin multi index helpers - :end-before: end multi index helpers + :language: php + :dedent: + :start-after: begin multi index helpers + :end-before: end multi index helpers .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { - v: 2, - key: { last_visible_dt: 1 }, - name: 'last_visible_dt_1', - unique: true, - sparse: true, - expireAfterSeconds: 3600 - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + unique: true, + sparse: true, + expireAfterSeconds: 3600 + } + ] To learn more about these indexes, see :manual:`Index Properties ` in the {+server-docs-name+}. @@ -351,25 +351,25 @@ default index on the ``_id`` field: .. io-code-block:: .. input:: /includes/schema-builder/spaceports_migration.php - :language: php - :dedent: - :start-after: begin create geospatial index - :end-before: end create geospatial index + :language: php + :dedent: + :start-after: begin create geospatial index + :end-before: end create geospatial index .. output:: - :language: json - :visible: false + :language: json + :visible: false - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { - v: 2, - key: { launchpad_location: '2dsphere' }, - name: 'launchpad_location_2dsphere', - '2dsphereIndexVersion': 3 - }, - { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' } - ] + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { launchpad_location: '2dsphere' }, + name: 'launchpad_location_2dsphere', + '2dsphereIndexVersion': 3 + }, + { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' } + ] To learn more about geospatial indexes, see @@ -437,17 +437,45 @@ Click the :guilabel:`{+code-output-label+}` button to see the Search indexes created by running the migration: .. io-code-block:: + .. input:: /includes/schema-builder/galaxies_migration.php - :language: php - :dedent: - :start-after: begin-create-search-indexes - :end-before: end-create-search-indexes + :language: php + :dedent: + :start-after: begin-create-search-indexes + :end-before: end-create-search-indexes .. output:: - :language: json - :visible: false - - WIP + :language: json + :visible: false + + { + "id": "...", + "name": "dynamic_index", + "type": "search", + "status": "READY", + "queryable": true, + "latestDefinition": { + "mappings": { "dynamic": true } + }, + ... + } + { + "id": "...", + "name": "auto_index", + "type": "search", + "status": "READY", + "queryable": true, + "latestDefinition": { + "mappings": { + "fields": { "name": [ + { "type": "string", "analyzer": "lucene.english" }, + { "type": "autocomplete", "analyzer": "lucene.english" }, + { "type": "token" } + ] } + } + }, + ... + } Vector Search ````````````` @@ -467,16 +495,31 @@ indexes created by running the migration: .. io-code-block:: .. input:: /includes/schema-builder/galaxies_migration.php - :language: php - :dedent: - :start-after: begin-create-vs-index - :end-before: end-create-vs-index + :language: php + :dedent: + :start-after: begin-create-vs-index + :end-before: end-create-vs-index .. output:: - :language: json - :visible: false - - WIP + :language: json + :visible: false + + { + "id": "...", + "name": "vs_index", + "type": "vectorSearch", + "status": "READY", + "queryable": true, + "latestDefinition": { + "fields": [ { + "type": "vector", + "numDimensions": 4, + "path": "vector4", + "similarity": "cosine" + } ] + }, + ... + } Drop a Search Index ``````````````````` diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index e1ed0d190..c10400363 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -64,17 +64,17 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`MongoDB\Collection::createSearchIndex()` method from the - {+php-library+}, as shown in the following code: + :phpmethod:`createSearchIndex() ` + method from the {+php-library+}, as shown in the following code: .. code-block:: php - - $collection = DB::connection('mongodb')->getCollection('movies'); - - $collection->createSearchIndex( - ['mappings' => ['dynamic' => true]], - ['name' => 'search_index'] - ); + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], + ['name' => 'search_index'] + ); Perform Queries --------------- @@ -111,23 +111,23 @@ model's ``title`` field for the term ``'dream'``: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-search-query - :end-before: end-search-query + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query .. output:: - :language: json - :visible: false - - [ - { "title": "Dreaming of Jakarta", - "year": 1990 - }, - { "title": "See You in My Dreams", - "year": 1996 - } - ] + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] You can use the ``search()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the @@ -137,55 +137,55 @@ following optional parameters to ``search()``: :header-rows: 1 * - Optional Parameter - - Type - - Description + - Type + - Description * - ``index`` - - ``string`` - - Provides the name of the Atlas Search index to use + - ``string`` + - Provides the name of the Atlas Search index to use * - ``highlight`` - - ``array`` - - Specifies highlighting options for displaying search terms in their - original context + - ``array`` + - Specifies highlighting options for displaying search terms in their + original context * - ``concurrent`` - - ``bool`` - - Parallelizes search query across segments on dedicated search nodes + - ``bool`` + - Parallelizes search query across segments on dedicated search nodes * - ``count`` - - ``string`` - - Specifies the count options for retrieving a count of the results + - ``string`` + - Specifies the count options for retrieving a count of the results * - ``searchAfter`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately following that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately following that point * - ``searchBefore`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately preceding that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately preceding that point * - ``scoreDetails`` - - ``bool`` - - Specifies whether to retrieve a detailed breakdown of the score - for results + - ``bool`` + - Specifies whether to retrieve a detailed breakdown of the score + for results * - ``sort`` - - ``array`` - - Specifies the fields on which to sort the results + - ``array`` + - Specifies the fields on which to sort the results * - ``returnStoredSource`` - - ``bool`` - - Specifies whether to perform a full document lookup on the - backend database or return only stored source fields directly - from Atlas Search + - ``bool`` + - Specifies whether to perform a full document lookup on the + backend database or return only stored source fields directly + from Atlas Search * - ``tracking`` - - ``array`` - - Specifies the tracking option to retrieve analytics information - on the search terms + - ``array`` + - Specifies the tracking option to retrieve analytics information + on the search terms To learn more about these parameters, see the :atlas:`Fields ` section of the @@ -218,20 +218,20 @@ string ``"jak"`` on the ``title`` field: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-auto-query - :end-before: end-auto-query + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - [ - "Dreaming of Jakarta", - "Jakob the Liar", - "Emily Calling Jake" - ] + [ + "Dreaming of Jakarta", + "Jakob the Liar", + "Emily Calling Jake" + ] You can also pass the following optional parameters to the ``autocomplete()`` method to customize the query: @@ -240,19 +240,19 @@ method to customize the query: :header-rows: 1 * - Optional Parameter - - Type - - Description - - Default Value + - Type + - Description + - Default Value * - ``fuzzy`` - - ``bool`` or ``array`` - - Enables fuzzy search and fuzzy search options - - ``false`` + - ``bool`` or ``array`` + - Enables fuzzy search and fuzzy search options + - ``false`` * - ``tokenOrder`` - - ``string`` - - Specifies order in which to search for tokens - - ``'any'`` + - ``string`` + - Specifies order in which to search for tokens + - ``'any'`` To learn more about these parameters, see the :atlas:`Options ` section of the diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index cb29b0300..1021521ba 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -64,8 +64,8 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`MongoDB\Collection::createSearchIndex()` method from the - {+php-library+}. You must specify the ``type`` option as + :phpmethod:`createSearchIndex() ` + method from the {+php-library+}. You must specify the ``type`` option as ``'vectorSearch'``, as shown in the following code: .. code-block:: php diff --git a/docs/includes/schema-builder/galaxies_migration.php b/docs/includes/schema-builder/galaxies_migration.php index df4188a38..3bcafa2e9 100644 --- a/docs/includes/schema-builder/galaxies_migration.php +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -40,7 +40,7 @@ public function up(): void [ 'type' => 'vector', 'numDimensions' => 4, - 'path' => 'vector4', + 'path' => 'embeddings', 'similarity' => 'cosine', ], ], diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 89caf8846..76a0d144a 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -678,7 +678,7 @@ a query: :end-before: end options The query builder accepts the same options that you can set for -the :phpmethod:`MongoDB\Collection::find()` method in the +the :phpmethod:`find() ` method in the {+php-library+}. Some of the options to modify query results, such as ``skip``, ``sort``, and ``limit``, are settable directly as query builder methods and are described in the From 95ea7e021f2d2fc35925bf8293f8f80328605fd6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 14:00:04 -0500 Subject: [PATCH 06/12] wip --- docs/eloquent-models/schema-builder.txt | 318 ++++++++++++------------ 1 file changed, 159 insertions(+), 159 deletions(-) diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index f9f6170a8..5ecfec695 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -76,7 +76,7 @@ following changes to perform the schema changes on your MongoDB database: specifies the correct database: - Make sure your ``connections`` array item contains a valid ``mongodb`` - entry in your ``config/database.php`` file + entry in your ``config/database.php`` file - Specify ``"mongodb"`` in the ``$connection`` field of your migration class The following example migration class contains the following methods: @@ -175,30 +175,30 @@ the migration, including the default index on the ``_id`` field: .. io-code-block:: .. input:: /includes/schema-builder/flights_migration.php - :language: php - :dedent: - :start-after: begin create index - :end-before: end create index + :language: php + :dedent: + :start-after: begin create index + :end-before: end create index .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' }, - { - v: 2, - key: { launch_location: 1, launch_date: -1 }, - name: 'launch_location_1_launch_date_-1' - }, - { - v: 2, - key: { mission_id: 1 }, - name: 'unique_mission_id_idx', - unique: true - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { mission_type: 1 }, name: 'mission_type_1' }, + { + v: 2, + key: { launch_location: 1, launch_date: -1 }, + name: 'launch_location_1_launch_date_-1' + }, + { + v: 2, + key: { mission_id: 1 }, + name: 'unique_mission_id_idx', + unique: true + } + ] Specify Index Options ~~~~~~~~~~~~~~~~~~~~~ @@ -215,35 +215,35 @@ field: .. io-code-block:: .. input:: /includes/schema-builder/passengers_migration.php - :language: php - :dedent: - :start-after: begin index options - :end-before: end index options + :language: php + :dedent: + :start-after: begin index options + :end-before: end index options .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { - v: 2, - key: { last_name: 1 }, - name: 'passengers_collation_idx', - collation: { - locale: 'de@collation=phonebook', - caseLevel: false, - caseFirst: 'off', - strength: 3, - numericOrdering: true, - alternate: 'non-ignorable', - maxVariable: 'punct', - normalization: false, - backwards: false, - version: '57.1' - } - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_name: 1 }, + name: 'passengers_collation_idx', + collation: { + locale: 'de@collation=phonebook', + caseLevel: false, + caseFirst: 'off', + strength: 3, + numericOrdering: true, + alternate: 'non-ignorable', + maxVariable: 'punct', + normalization: false, + backwards: false, + version: '57.1' + } + } + ] To learn more about index options, see :manual:`Options for All Index Types ` in the {+server-docs-name+}. @@ -276,25 +276,25 @@ the ``_id`` field: .. io-code-block:: .. input:: /includes/schema-builder/planets_migration.php - :language: php - :dedent: - :start-after: begin index helpers - :end-before: end index helpers + :language: php + :dedent: + :start-after: begin index helpers + :end-before: end index helpers .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true }, - { - v: 2, - key: { last_visible_dt: 1 }, - name: 'last_visible_dt_1', - expireAfterSeconds: 86400 - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { v: 2, key: { rings: 1 }, name: 'rings_1', sparse: true }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + expireAfterSeconds: 86400 + } + ] You can specify sparse, TTL, and unique indexes on either a single field or compound index by specifying them in the index options. @@ -307,26 +307,26 @@ field: .. io-code-block:: .. input:: /includes/schema-builder/planets_migration.php - :language: php - :dedent: - :start-after: begin multi index helpers - :end-before: end multi index helpers + :language: php + :dedent: + :start-after: begin multi index helpers + :end-before: end multi index helpers .. output:: - :language: json - :visible: false - - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { - v: 2, - key: { last_visible_dt: 1 }, - name: 'last_visible_dt_1', - unique: true, - sparse: true, - expireAfterSeconds: 3600 - } - ] + :language: json + :visible: false + + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { last_visible_dt: 1 }, + name: 'last_visible_dt_1', + unique: true, + sparse: true, + expireAfterSeconds: 3600 + } + ] To learn more about these indexes, see :manual:`Index Properties ` in the {+server-docs-name+}. @@ -351,25 +351,25 @@ default index on the ``_id`` field: .. io-code-block:: .. input:: /includes/schema-builder/spaceports_migration.php - :language: php - :dedent: - :start-after: begin create geospatial index - :end-before: end create geospatial index + :language: php + :dedent: + :start-after: begin create geospatial index + :end-before: end create geospatial index .. output:: - :language: json - :visible: false + :language: json + :visible: false - [ - { v: 2, key: { _id: 1 }, name: '_id_' }, - { - v: 2, - key: { launchpad_location: '2dsphere' }, - name: 'launchpad_location_2dsphere', - '2dsphereIndexVersion': 3 - }, - { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' } - ] + [ + { v: 2, key: { _id: 1 }, name: '_id_' }, + { + v: 2, + key: { launchpad_location: '2dsphere' }, + name: 'launchpad_location_2dsphere', + '2dsphereIndexVersion': 3 + }, + { v: 2, key: { runway_location: '2d' }, name: 'runway_location_2d' } + ] To learn more about geospatial indexes, see @@ -439,43 +439,43 @@ indexes created by running the migration: .. io-code-block:: .. input:: /includes/schema-builder/galaxies_migration.php - :language: php - :dedent: - :start-after: begin-create-search-indexes - :end-before: end-create-search-indexes + :language: php + :dedent: + :start-after: begin-create-search-indexes + :end-before: end-create-search-indexes .. output:: - :language: json - :visible: false - - { - "id": "...", - "name": "dynamic_index", - "type": "search", - "status": "READY", - "queryable": true, - "latestDefinition": { - "mappings": { "dynamic": true } - }, - ... - } - { - "id": "...", - "name": "auto_index", - "type": "search", - "status": "READY", - "queryable": true, - "latestDefinition": { - "mappings": { - "fields": { "name": [ - { "type": "string", "analyzer": "lucene.english" }, - { "type": "autocomplete", "analyzer": "lucene.english" }, - { "type": "token" } - ] } - } - }, - ... - } + :language: json + :visible: false + + { + "id": "...", + "name": "dynamic_index", + "type": "search", + "status": "READY", + "queryable": true, + "latestDefinition": { + "mappings": { "dynamic": true } + }, + ... + } + { + "id": "...", + "name": "auto_index", + "type": "search", + "status": "READY", + "queryable": true, + "latestDefinition": { + "mappings": { + "fields": { "name": [ + { "type": "string", "analyzer": "lucene.english" }, + { "type": "autocomplete", "analyzer": "lucene.english" }, + { "type": "token" } + ] } + } + }, + ... + } Vector Search ````````````` @@ -495,31 +495,31 @@ indexes created by running the migration: .. io-code-block:: .. input:: /includes/schema-builder/galaxies_migration.php - :language: php - :dedent: - :start-after: begin-create-vs-index - :end-before: end-create-vs-index + :language: php + :dedent: + :start-after: begin-create-vs-index + :end-before: end-create-vs-index .. output:: - :language: json - :visible: false - - { - "id": "...", - "name": "vs_index", - "type": "vectorSearch", - "status": "READY", - "queryable": true, - "latestDefinition": { - "fields": [ { - "type": "vector", - "numDimensions": 4, - "path": "vector4", - "similarity": "cosine" - } ] - }, - ... - } + :language: json + :visible: false + + { + "id": "...", + "name": "vs_index", + "type": "vectorSearch", + "status": "READY", + "queryable": true, + "latestDefinition": { + "fields": [ { + "type": "vector", + "numDimensions": 4, + "path": "vector4", + "similarity": "cosine" + } ] + }, + ... + } Drop a Search Index ``````````````````` From 85fb2c9e0a8fd7eb50692a6b35d256425b36adb6 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 14:00:35 -0500 Subject: [PATCH 07/12] wip --- docs/fundamentals/atlas-search.txt | 142 ++++++++++++++--------------- 1 file changed, 71 insertions(+), 71 deletions(-) diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index c10400363..ab957f9fa 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -68,13 +68,13 @@ You can create an Atlas Search index in either of the following ways: method from the {+php-library+}, as shown in the following code: .. code-block:: php - - $collection = DB::connection('mongodb')->getCollection('movies'); - - $collection->createSearchIndex( - ['mappings' => ['dynamic' => true]], - ['name' => 'search_index'] - ); + + $collection = DB::connection('mongodb')->getCollection('movies'); + + $collection->createSearchIndex( + ['mappings' => ['dynamic' => true]], + ['name' => 'search_index'] + ); Perform Queries --------------- @@ -111,23 +111,23 @@ model's ``title`` field for the term ``'dream'``: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-search-query - :end-before: end-search-query + :language: php + :dedent: + :start-after: start-search-query + :end-before: end-search-query .. output:: - :language: json - :visible: false - - [ - { "title": "Dreaming of Jakarta", - "year": 1990 - }, - { "title": "See You in My Dreams", - "year": 1996 - } - ] + :language: json + :visible: false + + [ + { "title": "Dreaming of Jakarta", + "year": 1990 + }, + { "title": "See You in My Dreams", + "year": 1996 + } + ] You can use the ``search()`` method to perform many types of Atlas Search queries. Depending on your desired query, you can pass the @@ -137,55 +137,55 @@ following optional parameters to ``search()``: :header-rows: 1 * - Optional Parameter - - Type - - Description + - Type + - Description * - ``index`` - - ``string`` - - Provides the name of the Atlas Search index to use + - ``string`` + - Provides the name of the Atlas Search index to use * - ``highlight`` - - ``array`` - - Specifies highlighting options for displaying search terms in their - original context + - ``array`` + - Specifies highlighting options for displaying search terms in their + original context * - ``concurrent`` - - ``bool`` - - Parallelizes search query across segments on dedicated search nodes + - ``bool`` + - Parallelizes search query across segments on dedicated search nodes * - ``count`` - - ``string`` - - Specifies the count options for retrieving a count of the results + - ``string`` + - Specifies the count options for retrieving a count of the results * - ``searchAfter`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately following that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately following that point * - ``searchBefore`` - - ``string`` - - Specifies a reference point for returning documents starting - immediately preceding that point + - ``string`` + - Specifies a reference point for returning documents starting + immediately preceding that point * - ``scoreDetails`` - - ``bool`` - - Specifies whether to retrieve a detailed breakdown of the score - for results + - ``bool`` + - Specifies whether to retrieve a detailed breakdown of the score + for results * - ``sort`` - - ``array`` - - Specifies the fields on which to sort the results + - ``array`` + - Specifies the fields on which to sort the results * - ``returnStoredSource`` - - ``bool`` - - Specifies whether to perform a full document lookup on the - backend database or return only stored source fields directly - from Atlas Search + - ``bool`` + - Specifies whether to perform a full document lookup on the + backend database or return only stored source fields directly + from Atlas Search * - ``tracking`` - - ``array`` - - Specifies the tracking option to retrieve analytics information - on the search terms + - ``array`` + - Specifies the tracking option to retrieve analytics information + on the search terms To learn more about these parameters, see the :atlas:`Fields ` section of the @@ -218,20 +218,20 @@ string ``"jak"`` on the ``title`` field: :copyable: true .. input:: /includes/fundamentals/as-avs/AtlasSearchTest.php - :language: php - :dedent: - :start-after: start-auto-query - :end-before: end-auto-query + :language: php + :dedent: + :start-after: start-auto-query + :end-before: end-auto-query .. output:: - :language: json - :visible: false + :language: json + :visible: false - [ - "Dreaming of Jakarta", - "Jakob the Liar", - "Emily Calling Jake" - ] + [ + "Dreaming of Jakarta", + "Jakob the Liar", + "Emily Calling Jake" + ] You can also pass the following optional parameters to the ``autocomplete()`` method to customize the query: @@ -240,19 +240,19 @@ method to customize the query: :header-rows: 1 * - Optional Parameter - - Type - - Description - - Default Value + - Type + - Description + - Default Value * - ``fuzzy`` - - ``bool`` or ``array`` - - Enables fuzzy search and fuzzy search options - - ``false`` + - ``bool`` or ``array`` + - Enables fuzzy search and fuzzy search options + - ``false`` * - ``tokenOrder`` - - ``string`` - - Specifies order in which to search for tokens - - ``'any'`` + - ``string`` + - Specifies order in which to search for tokens + - ``'any'`` To learn more about these parameters, see the :atlas:`Options ` section of the From d1c2cfe8e32c7c48f28a05ed0f8c7ade58ceb7f4 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 14:02:18 -0500 Subject: [PATCH 08/12] wip --- docs/fundamentals/atlas-search.txt | 2 +- docs/fundamentals/vector-search.txt | 2 +- docs/query-builder.txt | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index ab957f9fa..5c17584c6 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -64,7 +64,7 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`createSearchIndex() ` + :phpmethod:`createSearchIndex() ` method from the {+php-library+}, as shown in the following code: .. code-block:: php diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 1021521ba..5dcdd18f1 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -64,7 +64,7 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`createSearchIndex() ` + :phpmethod:`createSearchIndex() ` method from the {+php-library+}. You must specify the ``type`` option as ``'vectorSearch'``, as shown in the following code: diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 76a0d144a..82633e982 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -678,7 +678,7 @@ a query: :end-before: end options The query builder accepts the same options that you can set for -the :phpmethod:`find() ` method in the +the :phpmethod:`find() ` method in the {+php-library+}. Some of the options to modify query results, such as ``skip``, ``sort``, and ``limit``, are settable directly as query builder methods and are described in the From 1b87a679321b89a40b356f98619545d6ed9acfcc Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 14:07:48 -0500 Subject: [PATCH 09/12] test php link --- docs/query-builder.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/query-builder.txt b/docs/query-builder.txt index 82633e982..76a0d144a 100644 --- a/docs/query-builder.txt +++ b/docs/query-builder.txt @@ -678,7 +678,7 @@ a query: :end-before: end options The query builder accepts the same options that you can set for -the :phpmethod:`find() ` method in the +the :phpmethod:`find() ` method in the {+php-library+}. Some of the options to modify query results, such as ``skip``, ``sort``, and ``limit``, are settable directly as query builder methods and are described in the From 2104ca7ddc750e994c6aebf7e9eb07f30997b4d9 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 14:15:10 -0500 Subject: [PATCH 10/12] test php link --- docs/eloquent-models/schema-builder.txt | 2 +- docs/fundamentals/atlas-search.txt | 2 +- docs/fundamentals/vector-search.txt | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 5ecfec695..87f86c28d 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -514,7 +514,7 @@ indexes created by running the migration: "fields": [ { "type": "vector", "numDimensions": 4, - "path": "vector4", + "path": "embeddings", "similarity": "cosine" } ] }, diff --git a/docs/fundamentals/atlas-search.txt b/docs/fundamentals/atlas-search.txt index 5c17584c6..ab957f9fa 100644 --- a/docs/fundamentals/atlas-search.txt +++ b/docs/fundamentals/atlas-search.txt @@ -64,7 +64,7 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`createSearchIndex() ` + :phpmethod:`createSearchIndex() ` method from the {+php-library+}, as shown in the following code: .. code-block:: php diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 5dcdd18f1..c06b28320 100644 --- a/docs/fundamentals/vector-search.txt +++ b/docs/fundamentals/vector-search.txt @@ -64,10 +64,10 @@ You can create an Atlas Search index in either of the following ways: :ref:`laravel-schema-builder-atlas-idx` section of the Schema Builder guide. - Access a collection, then call the - :phpmethod:`createSearchIndex() ` + :phpmethod:`createSearchIndex() ` method from the {+php-library+}. You must specify the ``type`` option as ``'vectorSearch'``, as shown in the following code: - + .. code-block:: php $collection = DB::connection('mongodb')->getCollection('movies'); From b478ece998e57e056ba6f799d30c7b721cbd1e27 Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 11 Feb 2025 14:39:33 -0500 Subject: [PATCH 11/12] RM PR fixes 1 --- docs/eloquent-models/schema-builder.txt | 104 ++++++++++++++++-------- 1 file changed, 69 insertions(+), 35 deletions(-) diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index 87f86c28d..3cdec0f03 100644 --- a/docs/eloquent-models/schema-builder.txt +++ b/docs/eloquent-models/schema-builder.txt @@ -157,10 +157,15 @@ drop various types of indexes on a collection. Create an Index ~~~~~~~~~~~~~~~ -To create indexes, call the ``create()`` method on the ``Schema`` facade -in your migration file. Pass it the collection name and a callback -method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the -index creation details on the ``Blueprint`` instance. +To create indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade + in your migration file. + +#. Pass it the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Specify the index creation details on the ``Blueprint`` instance. The following example migration creates indexes on the following collection fields: @@ -262,11 +267,16 @@ indexes: - Unique indexes, which prevent inserting documents that contain duplicate values for the indexed field -To create these index types, call the ``create()`` method on the ``Schema`` facade -in your migration file. Pass ``create()`` the collection name and a callback -method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the -appropriate helper method on the ``Blueprint`` instance and pass the -index creation details. +To create these index types, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade + in your migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Call the appropriate helper method for the index type on the + ``Blueprint`` instance and pass the index creation details. The following migration code shows how to create a sparse and a TTL index by using the index helpers. Click the :guilabel:`{+code-output-label+}` button to see @@ -339,10 +349,16 @@ Create a Geospatial Index In MongoDB, geospatial indexes let you query geospatial coordinate data for inclusion, intersection, and proximity. -To create geospatial indexes, call the ``create()`` method on the ``Schema`` facade -in your migration file. Pass ``create()`` the collection name and a callback -method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. Specify the -geospatial index creation details on the ``Blueprint`` instance. +To create geospatial indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade + in your migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Specify the geospatial index creation details on the ``Blueprint`` + instance. The following example migration creates a ``2d`` and ``2dsphere`` geospatial index on the ``spaceports`` collection. Click the :guilabel:`{+code-output-label+}` @@ -379,11 +395,16 @@ the {+server-docs-name+}. Drop an Index ~~~~~~~~~~~~~ -To drop indexes from a collection, call the ``table()`` method on the -``Schema`` facade in your migration file. Pass it the table name and a -callback method with a ``MongoDB\Laravel\Schema\Blueprint`` parameter. -Call the ``dropIndex()`` method with the index name on the ``Blueprint`` -instance. +To drop indexes from a collection, perform the following actions: + +1. Call the ``table()`` method on the ``Schema`` facade in your + migration file. + +#. Pass it the table name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Call the ``dropIndex()`` method with the index name on the + ``Blueprint`` instance. .. note:: @@ -420,12 +441,16 @@ Vector Search features: Atlas Search ```````````` -To create Atlas Search indexes, call the ``create()`` method on the -``Schema`` facade in your migration file. Pass ``create()`` the -collection name and a callback method with a -``MongoDB\Laravel\Schema\Blueprint`` parameter. Pass the Atlas index -creation details to the ``searchIndex()`` method on the ``Blueprint`` -instance. +To create Atlas Search indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade in your + migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Pass the Atlas index creation details to the ``searchIndex()`` method + on the ``Blueprint`` instance. This example migration creates the following Atlas Search indexes on the ``galaxies`` collection: @@ -480,12 +505,16 @@ indexes created by running the migration: Vector Search ````````````` -To create Vector Search indexes, call the ``create()`` method on the -``Schema`` facade in your migration file. Pass ``create()`` the -collection name and a callback method with a -``MongoDB\Laravel\Schema\Blueprint`` parameter. Pass the Atlas index -creation details to the ``vectorSearchIndex()`` method on the ``Blueprint`` -instance. +To create Vector Search indexes, perform the following actions: + +1. Call the ``create()`` method on the ``Schema`` facade in your + migration file. + +#. Pass ``create()`` the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Pass the vector index creation details to the ``vectorSearchIndex()`` + method on the ``Blueprint`` instance. The following example migration creates a Vector Search index called ``vs_index`` on the ``galaxies`` collection. @@ -524,11 +553,16 @@ indexes created by running the migration: Drop a Search Index ``````````````````` -To drop an Atlas Search or Vector Search index from a collection, call -the ``table()`` method on the ``Schema`` facade in your migration file. -Pass it the collection name and a callback method with a -``MongoDB\Laravel\Schema\Blueprint`` parameter. Call the ``dropSearchIndex()`` -method with the Search index name on the ``Blueprint`` instance. +To drop an Atlas Search or Vector Search index from a collection, +perform the following actions: + +1. Call the ``table()`` method on the ``Schema`` facade in your migration file. + +#. Pass it the collection name and a callback method with a + ``MongoDB\Laravel\Schema\Blueprint`` parameter. + +#. Call the ``dropSearchIndex()`` method with the Search index name on + the ``Blueprint`` instance. The following example migration drops an index called ``auto_index`` from the ``galaxies`` collection: From bd1463c68c030c387f324e687ebf326defad7c1e Mon Sep 17 00:00:00 2001 From: rustagir Date: Tue, 25 Feb 2025 10:18:13 -0500 Subject: [PATCH 12/12] JT suggestion - move code to tests --- .../schema-builder/galaxies_migration.php | 73 +++++++++++++++++-- 1 file changed, 66 insertions(+), 7 deletions(-) diff --git a/docs/includes/schema-builder/galaxies_migration.php b/docs/includes/schema-builder/galaxies_migration.php index 3bcafa2e9..fc92ff026 100644 --- a/docs/includes/schema-builder/galaxies_migration.php +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -2,15 +2,22 @@ declare(strict_types=1); -use Illuminate\Database\Migrations\Migration; +namespace App\Http\Controllers; + use Illuminate\Support\Facades\Schema; +use MongoDB\Collection; use MongoDB\Laravel\Schema\Blueprint; +use MongoDB\Laravel\Tests\TestCase; -return new class extends Migration -{ - protected $connection = 'mongodb'; +use function assert; - public function up(): void +class AtlasIdxSchemaBuilderTest extends TestCase +{ + /** + * @runInSeparateProcess + * @preserveGlobalState disabled + */ + public function testAtlasSearchIdx(): void { // begin-create-search-indexes Schema::create('galaxies', function (Blueprint $collection) { @@ -33,6 +40,22 @@ public function up(): void }); // end-create-search-indexes + $index = $this->getSearchIndex('galaxies', 'dynamic_index'); + self::assertNotNull($index); + + self::assertSame('dynamic_index', $index['name']); + self::assertSame('search', $index['type']); + self::assertTrue($index['latestDefinition']['mappings']['dynamic']); + + $index = $this->getSearchIndex('galaxies', 'auto_index'); + self::assertNotNull($index); + + self::assertSame('auto_index', $index['name']); + self::assertSame('search', $index['type']); + } + + public function testVectorSearchIdx(): void + { // begin-create-vs-index Schema::create('galaxies', function (Blueprint $collection) { $collection->vectorSearchIndex([ @@ -47,14 +70,50 @@ public function up(): void ], 'vs_index'); }); // end-create-vs-index + + $index = $this->getSearchIndex('galaxies', 'vs_index'); + self::assertNotNull($index); + + self::assertSame('vs_index', $index['name']); + self::assertSame('vectorSearch', $index['type']); + self::assertSame('vector', $index['latestDefinition']['fields'][0]['type']); } - public function down(): void + public function testDropIndexes(): void { // begin-drop-search-index Schema::table('galaxies', function (Blueprint $collection) { $collection->dropSearchIndex('auto_index'); }); // end-drop-search-index + + Schema::table('galaxies', function (Blueprint $collection) { + $collection->dropSearchIndex('dynamic_index'); + }); + + Schema::table('galaxies', function (Blueprint $collection) { + $collection->dropSearchIndex('vs_index'); + }); + + $index = $this->getSearchIndex('galaxies', 'auto_index'); + self::assertNull($index); + + $index = $this->getSearchIndex('galaxies', 'dynamic_index'); + self::assertNull($index); + + $index = $this->getSearchIndex('galaxies', 'vs_index'); + self::assertNull($index); + } + + protected function getSearchIndex(string $collection, string $name): ?array + { + $collection = $this->getConnection('mongodb')->getCollection($collection); + assert($collection instanceof Collection); + + foreach ($collection->listSearchIndexes(['name' => $name, 'typeMap' => ['root' => 'array', 'array' => 'array', 'document' => 'array']]) as $index) { + return $index; + } + + return null; } -}; +}