diff --git a/source/includes/extracts-note.yaml b/source/includes/extracts-note.yaml index 69346085..cf8b8480 100644 --- a/source/includes/extracts-note.yaml +++ b/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 ` diff --git a/source/includes/indexes/indexes.php b/source/includes/indexes/indexes.php index 3b293fb1..f7947e02 100644 --- a/source/includes/indexes/indexes.php +++ b/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) { diff --git a/source/indexes.txt b/source/indexes.txt index 29afd6ed..dfe80727 100644 --- a/source/indexes.txt +++ b/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:`Atlas Search ` and :atlas:`Vector +Search ` 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 diff --git a/source/indexes/atlas-search-index.txt b/source/indexes/atlas-search-index.txt index eb8762aa..c3d8fce4 100644 --- a/source/indexes/atlas-search-index.txt +++ b/source/indexes/atlas-search-index.txt @@ -20,16 +20,19 @@ 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 -`. +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 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 `. 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()`` @@ -37,15 +40,16 @@ to manage your Atlas Search indexes: - ``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: @@ -53,8 +57,9 @@ 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,17 +69,30 @@ 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 ` 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: @@ -82,7 +100,7 @@ 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``: diff --git a/source/reference/method/MongoDBCollection-createIndexes.txt b/source/reference/method/MongoDBCollection-createIndexes.txt index b1f4c7c7..244b3bec 100644 --- a/source/reference/method/MongoDBCollection-createIndexes.txt +++ b/source/reference/method/MongoDBCollection-createIndexes.txt @@ -2,7 +2,6 @@ MongoDB\\Collection::createIndexes() ==================================== - .. contents:: On this page :local: :backlinks: none diff --git a/source/reference/method/MongoDBCollection-createSearchIndex.txt b/source/reference/method/MongoDBCollection-createSearchIndex.txt index 840281ec..a229a153 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndex.txt +++ b/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 ` command reference in the MongoDB manual - `Atlas Search `__ documentation in the MongoDB Manual diff --git a/source/reference/method/MongoDBCollection-createSearchIndexes.txt b/source/reference/method/MongoDBCollection-createSearchIndexes.txt index f9124f57..6c1b4981 100644 --- a/source/reference/method/MongoDBCollection-createSearchIndexes.txt +++ b/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 ` command reference in the MongoDB manual - `Atlas Search `__ documentation in the MongoDB Manual diff --git a/source/whats-new.txt b/source/whats-new.txt index 3b60fb17..656ba387 100644 --- a/source/whats-new.txt +++ b/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 ` on GitHub.