Merge pull request #199 from rustagir/DOCSP-43365-createsearchindex-type-param

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
+// start-create-vector-index
+$vectorSearchIndexName = $collection->createSearchIndex(
+    [
+        '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_dynamic',
+            'name' => 'SearchIdx',
             'definition' => ['mappings' => ['dynamic' => true]],
         ],
         [
-            'name' => 'SearchIdx_simple',
+            'name' => 'VSidx',
+            'type' => 'vectorSearch',
             'definition' => [
-                'mappings' => [
-                    'dynamic' => false,
-                    'fields' => [
-                        'title' => [
-                            'type' => 'string',
-                            'analyzer' => 'lucene.simple'
-                        ]
-                    ]
-                ]
+                '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.txt

@@ -229,9 +229,10 @@ Atlas Search Index Management
 -----------------------------
 
 The following sections contain code examples that describe how to manage
-:atlas:`Atlas Search indexes </atlas-search/manage-indexes/>`. 
+:atlas:`Atlas Search </atlas-search/manage-indexes/>` and :atlas:`Vector
+Search </atlas-vector-search/vector-search-type/>` indexes.
 
-.. note:: Atlas Search Index Management is Asynchronous
+.. note:: Atlas 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

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:: Atlas 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 Atlas 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,7 +15,7 @@ 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
 
@@ -51,15 +50,21 @@ Parameters
 
      * - name
        - string
-       - Name of the search index to create.
+       - | 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 default index
+           name is ``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
 -----------------
@@ -110,6 +115,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
 
@@ -39,7 +39,12 @@ Parameters
 
   An optional ``name`` string field specifies the 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".
+  collection. If you do not specify a name, the default index name is
+  ``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 +64,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 +123,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/whats-new.txt

@@ -164,6 +164,13 @@ improvements, and fixes:
   encryption and decryption of the data key locally, ensuring that the
   encryption key never leaves the KMIP server.
 
+- Adds the ``type`` option in Search index specifications for
+  the :phpmethod:`MongoDB\Collection::createIndex()` and
+  :phpmethod:`MongoDB\Collection::createSearchIndexes()` methods. This
+  change allows you to create Atlas Vector Search indexes
+  programmatically. To learn more and view examples, see the
+  :ref:`php-atlas-search-index` guide.
+
 For more information about the changes in this version, see the
 :github:`v1.20 release notes
 </mongodb/mongo-php-library/releases/tag/1.20.0>` on GitHub.