DOCSP-43365: type specification for createSearchIndex(es)

Author: rustagir

source/includes/extracts-note.yaml

@@ -20,7 +20,7 @@ content: |
 ---
 ref: note-atlas-search-async
 content: |
-  Atlas Search indexes are managed asynchronously. After creating or updating an
+  Atlas Search and Vector Search indexes are managed asynchronously. After creating or updating an
   index, you can periodically execute
   :phpmethod:`MongoDB\Collection::listSearchIndexes()` and check the
   ``queryable`` :manual:`output field  </reference/operator/aggregation/listSearchIndexes/#output>`

source/includes/indexes/indexes.php

@@ -57,36 +57,48 @@
 // end-index-array-query
 
 // start-create-search-index
-$indexName = $collection->createSearchIndex(
+$searchIndexName = $collection->createSearchIndex(
     ['mappings' => ['dynamic' => true]],
     ['name' => 'mySearchIdx']
 );
 // end-create-search-index
 
-// start-create-search-indexes
-$indexNames = $collection->createSearchIndexes(
+// start-create-vector-index
+$vectorSearchIndexName = $collection->createSearchIndex(
     [
-        [
-            'name' => 'SearchIdx_dynamic',
-            'definition' => ['mappings' => ['dynamic' => true]],
-        ],
-        [
-            'name' => 'SearchIdx_simple',
-            'definition' => [
-                'mappings' => [
-                    'dynamic' => false,
-                    'fields' => [
-                        'title' => [
-                            'type' => 'string',
-                            'analyzer' => 'lucene.simple'
-                        ]
-                    ]
-                ]
-            ],
-        ],
-    ]
+        'fields' => [[
+            'type' => 'vector',
+            'path' => 'plot_embedding',
+            'numDimensions' => 1536,
+            'similarity' => 'dotProduct'
+        ]]
+    ],
+    ['name' => 'myVSidx', 'type' => 'vectorSearch']
+);
+// end-create-vector-index
+
+// start-create-multiple-indexes
+$indexNames = $collection->createSearchIndexes(
+	[
+		[
+			'name' => 'SearchIdx',
+			'definition' => ['mappings' => ['dynamic' => true]],
+		],
+		[
+			'name' => 'VSidx',
+			'type' => 'vectorSearch',
+			'definition' => [
+				'fields' => [[
+					'type' => 'vector',
+					'path' => 'plot_embedding',
+					'numDimensions' => 1536,
+					'similarity' => 'dotProduct'
+				]]
+			],
+		],
+	]
 );
-// end-create-search-indexes
+// end-create-multiple-indexes
 
 // start-list-search-indexes
 foreach ($collection->listSearchIndexes() as $indexInfo) {

source/indexes/atlas-search-index.txt

@@ -20,41 +20,46 @@ Atlas Search Indexes
 Overview
 --------
 
-The MongoDB Atlas Search feature enables you to perform full-text
-searches on collections hosted on Atlas. Before you can perform Atlas
-Search queries, you must create indexes that specify which
-fields to index and how they are indexed.
+In this guide, you can learn how to programmatically manage your Atlas
+Search and Atlas Vector Search indexes by using the {+library-short+}.
 
-To learn more about Atlas Search, see the :atlas:`Atlas Search Overview
-</atlas-search/atlas-search-overview/>`.
+The Atlas Search feature enables you to perform full-text searches on
+collections hosted on MongoDB Atlas. To learn more about Atlas Search,
+see the :atlas:`Atlas Search Overview </atlas-search/atlas-search-overview/>`.
+
+Atlas Vector Search enables you to perform semantic searches on vector
+embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search,
+see the :atlas:`Atlas Vector Search Overview </atlas-vector-search/vector-search-overview/>`.
 
 You can use the following methods on a ``MongoDB\Collection`` instance
-to manage your Atlas Search indexes:
+to manage your Atlas Search and Vector Search indexes:
 
 - ``MongoDB\Collection::createSearchIndex()``
 - ``MongoDB\Collection::createSearchIndexes()``
 - ``MongoDB\Collection::listSearchIndexes()``
 - ``MongoDB\Collection::updateSearchIndex()``
 - ``MongoDB\Collection::dropSearchIndex()``
 
-.. note:: Atlas Search Index Management is Asynchronous
+.. note:: Search and Vector Search Index Management is Asynchronous
 
-   The {+php-library+} manages Atlas Search indexes asynchronously. The
-   library methods described in the following sections return the server
-   response immediately, but the changes to your Search indexes take
-   place in the background and might not complete until some time later.
+   The {+php-library+} manages Atlas Search and Vector Search indexes
+   asynchronously. The library methods described in the following
+   sections return the server response immediately, but the changes to
+   your Search indexes take place in the background and might not
+   complete until some time later.
 
 The following sections provide code examples that demonstrate how to use
-each Atlas Search index management method.
+each of the preceding methods.
 
 .. _php-atlas-search-index-create:
 
 Create a Search Index
 ---------------------
 
 You can use the ``createSearchIndex()`` method to create a single Atlas
-Search index on a collection, or the ``createSearchIndexes()`` method to
-create multiple indexes simultaneously.
+Search or Vector Search index on a collection, or the
+``createSearchIndexes()`` method to create multiple indexes
+simultaneously.
 
 The following code example shows how to create a single Atlas Search
 index:
@@ -64,25 +69,38 @@ index:
    :start-after: start-create-search-index
    :end-before: end-create-search-index
 
-The following code example shows how to create multiple Atlas Search
-indexes:
+The following code example shows how to create a single Atlas Vector
+Search index:
+
+.. literalinclude:: /includes/indexes/indexes.php
+   :language: php
+   :start-after: start-create-vector-index
+   :end-before: end-create-vector-index
+
+The following code example shows how to create Search and
+Vector Search indexes in one call:
 
 .. literalinclude:: /includes/indexes/indexes.php
    :language: php
-   :start-after: start-create-search-indexes
-   :end-before: end-create-search-indexes
+   :start-after: start-create-multiple-indexes
+   :end-before: end-create-multiple-indexes
+
+After you create Atlas Search or Atlas Vector Search indexes, you can
+perform the corresponding query types on your documents.
 
-After you create a Search index, you can perform Atlas Search queries on
-your collection. To learn more, see :atlas:`Create and Run Atlas Search
-Queries </atlas-search/searching/>` in the Atlas documentation.
+.. 
+   TODO uncomment when https://github.com/mongodb/docs-php-library/pull/197 is merged 
+   To learn more, see the following guides:
+   - :ref:`php-atlas-search`
+   - :ref:`php-vector-search`
 
 .. _php-atlas-search-index-list:
 
 List Search Indexes
 -------------------
 
 You can use the ``listSearchIndexes()`` method to return an array of the
-Atlas Search indexes on a collection:
+Atlas Search and Vector Search indexes on a collection:
 
 .. literalinclude:: /includes/indexes/indexes.php
    :language: php
@@ -96,9 +114,8 @@ Update a Search Index
 ---------------------
 
 You can use the ``updateSearchIndex()``
-method to update an Atlas Search index. You can use this method to
-change the name of a Search index or change the configuration of the
-index.
+method to update an Atlas Search or Vector Search index. You can use this method to
+change the name or configuration of an existing index.
 
 The following code shows how to update a search index to use a simple
 analyzer on the ``title`` field:
@@ -115,7 +132,7 @@ Delete a Search Index
 ---------------------
 
 You can use the ``dropSearchIndex()`` method to remove an Atlas Search
-index from a collection.
+or Vector Search index from a collection.
 
 The following code shows how to delete the Atlas Search index named
 ``mySearchIdx``:

source/reference/method/MongoDBCollection-createIndexes.txt

@@ -2,7 +2,6 @@
 MongoDB\\Collection::createIndexes()
 ====================================
 
-
 .. contents:: On this page
    :local:
    :backlinks: none

source/reference/method/MongoDBCollection-createSearchIndex.txt

@@ -4,7 +4,6 @@ MongoDB\\Collection::createSearchIndex()
 
 .. versionadded:: 1.17
 
-
 .. contents:: On this page
    :local:
    :backlinks: none
@@ -16,14 +15,14 @@ Definition
 
 .. phpmethod:: MongoDB\Collection::createSearchIndex()
 
-   Create an Atlas Search index for the collection.
+   Create an Atlas Search or Vector Search index for the collection.
 
    .. code-block:: php
 
-      function createSearchIndex(
-          array|object $definition,
-          array $options = []
-      ): string
+	  function createSearchIndex(
+		  array|object $definition,
+		  array $options = []
+	  ): string
 
    .. include:: /includes/extracts/note-atlas-search-requirement.rst
 
@@ -38,28 +37,33 @@ Parameters
   An array specifying the desired options.
 
   .. list-table::
-     :header-rows: 1
-     :widths: 20 20 80
+	 :header-rows: 1
+	 :widths: 20 20 80
 
-     * - Name
-       - Type
-       - Description
+	 * - Name
+	   - Type
+	   - Description
 
-     * - comment
-       - mixed
-       - .. include:: /includes/extracts/common-option-comment.rst
+	 * - comment
+	   - mixed
+	   - .. include:: /includes/extracts/common-option-comment.rst
 
-     * - name
-       - string
-       - Name of the search index to create.
+	 * - name
+	   - string
+	   - | Name of the search index to create.
+		 | You cannot create multiple indexes with the same name on a single
+		   collection. If you do not specify a name, the index is named ``default``.
 
-         You cannot create multiple indexes with the same name on a single
-         collection. If you do not specify a name, the index is named "default".
+	 * - type
+	   - string
+	   - Type of index to create. Accepted values are ``'search'`` and
+		 ``'vectorSearch'``. If you omit this option, the default
+		 value is ``'search'`` and the method creates an Atlas Search index.
 
 Return Values
 -------------
 
-The name of the created Atlas Search index as a string.
+The name of the created Atlas Search or Vector Search index as a string.
 
 Errors/Exceptions
 -----------------
@@ -91,8 +95,8 @@ to index all document fields containing
    $collection = (new MongoDB\Client)->getCollection('test', 'articles');
 
    $indexName = $collection->createSearchIndex(
-      ['mappings' => ['dynamic' => true]],
-      ['name' => 'test-search-index']
+	  ['mappings' => ['dynamic' => true]],
+	  ['name' => 'test-search-index']
    );
 
    var_dump($indexName);
@@ -110,6 +114,7 @@ See Also
 - :phpmethod:`MongoDB\Collection::dropSearchIndex()`
 - :phpmethod:`MongoDB\Collection::listSearchIndexes()`
 - :phpmethod:`MongoDB\Collection::updateSearchIndex()`
+- :ref:`php-atlas-search-index` guide
 - :manual:`createSearchIndexes </reference/command/createSearchIndexes>` command
   reference in the MongoDB manual
 - `Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__ documentation in the MongoDB Manual

source/reference/method/MongoDBCollection-createSearchIndexes.txt

@@ -16,7 +16,7 @@ Definition
 
 .. phpmethod:: MongoDB\Collection::createSearchIndexes()
 
-   Create one or more Atlas Search indexes for the collection.
+   Create one or more Atlas Search or Vector Search indexes for the collection.
 
    .. code-block:: php
 
@@ -41,6 +41,10 @@ Parameters
   create. You cannot create multiple indexes with the same name on a single
   collection. If you do not specify a name, the index is named "default".
 
+  An optional ``type`` string field specifies the type of search index to
+  create. Accepted values are ``'search'`` and ``'vectorSearch'``. If
+  you do not specify a type, the method creates an Atlas Search index.
+
 ``$options`` : array
   An array specifying the desired options.
 
@@ -59,7 +63,8 @@ Parameters
 Return Values
 -------------
 
-The names of the created Atlas Search indexes as an array of strings.
+The names of the created Atlas Search and Vector Search indexes as an
+array of strings.
 
 Errors/Exceptions
 -----------------
@@ -117,6 +122,7 @@ See Also
 - :phpmethod:`MongoDB\Collection::dropSearchIndex()`
 - :phpmethod:`MongoDB\Collection::listSearchIndexes()`
 - :phpmethod:`MongoDB\Collection::updateSearchIndex()`
+- :ref:`php-atlas-search-index` guide
 - :manual:`createSearchIndexes </reference/command/createSearchIndexes>` command
   reference in the MongoDB manual
 - `Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__ documentation in the MongoDB Manual