diff --git a/docs/eloquent-models/schema-builder.txt b/docs/eloquent-models/schema-builder.txt index dad3c8eed..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:: @@ -399,4 +420,155 @@ 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, 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: + +- ``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 + + { + "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 +````````````` + +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. + +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 + + { + "id": "...", + "name": "vs_index", + "type": "vectorSearch", + "status": "READY", + "queryable": true, + "latestDefinition": { + "fields": [ { + "type": "vector", + "numDimensions": 4, + "path": "embeddings", + "similarity": "cosine" + } ] + }, + ... + } + +Drop a Search Index +``````````````````` + +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: + +.. 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..ab957f9fa 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:`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'] + ); Perform Queries --------------- diff --git a/docs/fundamentals/vector-search.txt b/docs/fundamentals/vector-search.txt index 116cb75a0..c06b28320 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:`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'); + + $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..fc92ff026 --- /dev/null +++ b/docs/includes/schema-builder/galaxies_migration.php @@ -0,0 +1,119 @@ +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 + + $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([ + 'fields' => [ + [ + 'type' => 'vector', + 'numDimensions' => 4, + 'path' => 'embeddings', + 'similarity' => 'cosine', + ], + ], + ], '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 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; + } +} 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