Skip to content

Commit 6cc2ea7

Browse files
authored
Merge pull request #199 from rustagir/DOCSP-43365-createsearchindex-type-param
DOCSP-43365: type specification for createSearchIndex(es)
2 parents 1442347 + 7d9bfe8 commit 6cc2ea7

File tree

8 files changed

+103
-54
lines changed

8 files changed

+103
-54
lines changed

source/includes/extracts-note.yaml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ content: |
2020
---
2121
ref: note-atlas-search-async
2222
content: |
23-
Atlas Search indexes are managed asynchronously. After creating or updating an
23+
Atlas Search and Vector Search indexes are managed asynchronously. After creating or updating an
2424
index, you can periodically execute
2525
:phpmethod:`MongoDB\Collection::listSearchIndexes()` and check the
2626
``queryable`` :manual:`output field </reference/operator/aggregation/listSearchIndexes/#output>`

source/includes/indexes/indexes.php

Lines changed: 26 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -57,36 +57,48 @@
5757
// end-index-array-query
5858

5959
// start-create-search-index
60-
$indexName = $collection->createSearchIndex(
60+
$searchIndexName = $collection->createSearchIndex(
6161
['mappings' => ['dynamic' => true]],
6262
['name' => 'mySearchIdx']
6363
);
6464
// end-create-search-index
6565

66-
// start-create-search-indexes
66+
// start-create-vector-index
67+
$vectorSearchIndexName = $collection->createSearchIndex(
68+
[
69+
'fields' => [[
70+
'type' => 'vector',
71+
'path' => 'plot_embedding',
72+
'numDimensions' => 1536,
73+
'similarity' => 'dotProduct'
74+
]]
75+
],
76+
['name' => 'myVSidx', 'type' => 'vectorSearch']
77+
);
78+
// end-create-vector-index
79+
80+
// start-create-multiple-indexes
6781
$indexNames = $collection->createSearchIndexes(
6882
[
6983
[
70-
'name' => 'SearchIdx_dynamic',
84+
'name' => 'SearchIdx',
7185
'definition' => ['mappings' => ['dynamic' => true]],
7286
],
7387
[
74-
'name' => 'SearchIdx_simple',
88+
'name' => 'VSidx',
89+
'type' => 'vectorSearch',
7590
'definition' => [
76-
'mappings' => [
77-
'dynamic' => false,
78-
'fields' => [
79-
'title' => [
80-
'type' => 'string',
81-
'analyzer' => 'lucene.simple'
82-
]
83-
]
84-
]
91+
'fields' => [[
92+
'type' => 'vector',
93+
'path' => 'plot_embedding',
94+
'numDimensions' => 1536,
95+
'similarity' => 'dotProduct'
96+
]]
8597
],
8698
],
8799
]
88100
);
89-
// end-create-search-indexes
101+
// end-create-multiple-indexes
90102

91103
// start-list-search-indexes
92104
foreach ($collection->listSearchIndexes() as $indexInfo) {

source/indexes.txt

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -229,9 +229,10 @@ Atlas Search Index Management
229229
-----------------------------
230230

231231
The following sections contain code examples that describe how to manage
232-
:atlas:`Atlas Search indexes </atlas-search/manage-indexes/>`.
232+
:atlas:`Atlas Search </atlas-search/manage-indexes/>` and :atlas:`Vector
233+
Search </atlas-vector-search/vector-search-type/>` indexes.
233234

234-
.. note:: Atlas Search Index Management is Asynchronous
235+
.. note:: Atlas Search and Vector Search Index Management is Asynchronous
235236

236237
The {+php-library+} manages Atlas Search indexes asynchronously. The
237238
library methods described in the following sections return the server

source/indexes/atlas-search-index.txt

Lines changed: 44 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -20,41 +20,46 @@ Atlas Search Indexes
2020
Overview
2121
--------
2222

23-
The MongoDB Atlas Search feature enables you to perform full-text
24-
searches on collections hosted on Atlas. Before you can perform Atlas
25-
Search queries, you must create indexes that specify which
26-
fields to index and how they are indexed.
23+
In this guide, you can learn how to programmatically manage your Atlas
24+
Search and Atlas Vector Search indexes by using the {+library-short+}.
2725

28-
To learn more about Atlas Search, see the :atlas:`Atlas Search Overview
29-
</atlas-search/atlas-search-overview/>`.
26+
The Atlas Search feature enables you to perform full-text searches on
27+
collections hosted on MongoDB Atlas. To learn more about Atlas Search,
28+
see the :atlas:`Atlas Search Overview </atlas-search/atlas-search-overview/>`.
29+
30+
Atlas Vector Search enables you to perform semantic searches on vector
31+
embeddings stored in MongoDB Atlas. To learn more about Atlas Vector Search,
32+
see the :atlas:`Atlas Vector Search Overview </atlas-vector-search/vector-search-overview/>`.
3033

3134
You can use the following methods on a ``MongoDB\Collection`` instance
32-
to manage your Atlas Search indexes:
35+
to manage your Atlas Search and Vector Search indexes:
3336

3437
- ``MongoDB\Collection::createSearchIndex()``
3538
- ``MongoDB\Collection::createSearchIndexes()``
3639
- ``MongoDB\Collection::listSearchIndexes()``
3740
- ``MongoDB\Collection::updateSearchIndex()``
3841
- ``MongoDB\Collection::dropSearchIndex()``
3942

40-
.. note:: Atlas Search Index Management is Asynchronous
43+
.. note:: Atlas Search and Vector Search Index Management is Asynchronous
4144

42-
The {+php-library+} manages Atlas Search indexes asynchronously. The
43-
library methods described in the following sections return the server
44-
response immediately, but the changes to your Search indexes take
45-
place in the background and might not complete until some time later.
45+
The {+php-library+} manages Atlas Search and Vector Search indexes
46+
asynchronously. The library methods described in the following
47+
sections return the server response immediately, but the changes to
48+
your Search indexes take place in the background and might not
49+
complete until some time later.
4650

4751
The following sections provide code examples that demonstrate how to use
48-
each Atlas Search index management method.
52+
each of the preceding methods.
4953

5054
.. _php-atlas-search-index-create:
5155

5256
Create a Search Index
5357
---------------------
5458

5559
You can use the ``createSearchIndex()`` method to create a single Atlas
56-
Search index on a collection, or the ``createSearchIndexes()`` method to
57-
create multiple indexes simultaneously.
60+
Search or Vector Search index on a collection, or the
61+
``createSearchIndexes()`` method to create multiple indexes
62+
simultaneously.
5863

5964
The following code example shows how to create a single Atlas Search
6065
index:
@@ -64,25 +69,38 @@ index:
6469
:start-after: start-create-search-index
6570
:end-before: end-create-search-index
6671

67-
The following code example shows how to create multiple Atlas Search
68-
indexes:
72+
The following code example shows how to create a single Atlas Vector
73+
Search index:
74+
75+
.. literalinclude:: /includes/indexes/indexes.php
76+
:language: php
77+
:start-after: start-create-vector-index
78+
:end-before: end-create-vector-index
79+
80+
The following code example shows how to create Atlas Search and
81+
Vector Search indexes in one call:
6982

7083
.. literalinclude:: /includes/indexes/indexes.php
7184
:language: php
72-
:start-after: start-create-search-indexes
73-
:end-before: end-create-search-indexes
85+
:start-after: start-create-multiple-indexes
86+
:end-before: end-create-multiple-indexes
87+
88+
After you create Atlas Search or Atlas Vector Search indexes, you can
89+
perform the corresponding query types on your documents.
7490

75-
After you create a Search index, you can perform Atlas Search queries on
76-
your collection. To learn more, see :atlas:`Create and Run Atlas Search
77-
Queries </atlas-search/searching/>` in the Atlas documentation.
91+
..
92+
TODO uncomment when https://github.com/mongodb/docs-php-library/pull/197 is merged
93+
To learn more, see the following guides:
94+
- :ref:`php-atlas-search`
95+
- :ref:`php-vector-search`
7896

7997
.. _php-atlas-search-index-list:
8098

8199
List Search Indexes
82100
-------------------
83101

84102
You can use the ``listSearchIndexes()`` method to return an array of the
85-
Atlas Search indexes on a collection:
103+
Atlas Search and Vector Search indexes on a collection:
86104

87105
.. literalinclude:: /includes/indexes/indexes.php
88106
:language: php
@@ -96,9 +114,8 @@ Update a Search Index
96114
---------------------
97115

98116
You can use the ``updateSearchIndex()``
99-
method to update an Atlas Search index. You can use this method to
100-
change the name of a Search index or change the configuration of the
101-
index.
117+
method to update an Atlas Search or Vector Search index. You can use this method to
118+
change the name or configuration of an existing index.
102119

103120
The following code shows how to update a search index to use a simple
104121
analyzer on the ``title`` field:
@@ -115,7 +132,7 @@ Delete a Search Index
115132
---------------------
116133

117134
You can use the ``dropSearchIndex()`` method to remove an Atlas Search
118-
index from a collection.
135+
or Vector Search index from a collection.
119136

120137
The following code shows how to delete the Atlas Search index named
121138
``mySearchIdx``:

source/reference/method/MongoDBCollection-createIndexes.txt

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,6 @@
22
MongoDB\\Collection::createIndexes()
33
====================================
44

5-
65
.. contents:: On this page
76
:local:
87
:backlinks: none

source/reference/method/MongoDBCollection-createSearchIndex.txt

Lines changed: 12 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,6 @@ MongoDB\\Collection::createSearchIndex()
44

55
.. versionadded:: 1.17
66

7-
87
.. contents:: On this page
98
:local:
109
:backlinks: none
@@ -16,7 +15,7 @@ Definition
1615

1716
.. phpmethod:: MongoDB\Collection::createSearchIndex()
1817

19-
Create an Atlas Search index for the collection.
18+
Create an Atlas Search or Vector Search index for the collection.
2019

2120
.. code-block:: php
2221

@@ -51,15 +50,21 @@ Parameters
5150

5251
* - name
5352
- string
54-
- Name of the search index to create.
53+
- | Name of the search index to create.
54+
| You cannot create multiple indexes with the same name on a single
55+
collection. If you do not specify a name, the default index
56+
name is ``default``.
5557

56-
You cannot create multiple indexes with the same name on a single
57-
collection. If you do not specify a name, the index is named "default".
58+
* - type
59+
- string
60+
- Type of index to create. Accepted values are ``'search'`` and
61+
``'vectorSearch'``. If you omit this option, the default
62+
value is ``'search'`` and the method creates an Atlas Search index.
5863

5964
Return Values
6065
-------------
6166

62-
The name of the created Atlas Search index as a string.
67+
The name of the created Atlas Search or Vector Search index as a string.
6368

6469
Errors/Exceptions
6570
-----------------
@@ -110,6 +115,7 @@ See Also
110115
- :phpmethod:`MongoDB\Collection::dropSearchIndex()`
111116
- :phpmethod:`MongoDB\Collection::listSearchIndexes()`
112117
- :phpmethod:`MongoDB\Collection::updateSearchIndex()`
118+
- :ref:`php-atlas-search-index` guide
113119
- :manual:`createSearchIndexes </reference/command/createSearchIndexes>` command
114120
reference in the MongoDB manual
115121
- `Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__ documentation in the MongoDB Manual

source/reference/method/MongoDBCollection-createSearchIndexes.txt

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ Definition
1616

1717
.. phpmethod:: MongoDB\Collection::createSearchIndexes()
1818

19-
Create one or more Atlas Search indexes for the collection.
19+
Create one or more Atlas Search or Vector Search indexes for the collection.
2020

2121
.. code-block:: php
2222

@@ -39,7 +39,12 @@ Parameters
3939

4040
An optional ``name`` string field specifies the name of the search index to
4141
create. You cannot create multiple indexes with the same name on a single
42-
collection. If you do not specify a name, the index is named "default".
42+
collection. If you do not specify a name, the default index name is
43+
``default``.
44+
45+
An optional ``type`` string field specifies the type of search index to
46+
create. Accepted values are ``'search'`` and ``'vectorSearch'``. If
47+
you do not specify a type, the method creates an Atlas Search index.
4348

4449
``$options`` : array
4550
An array specifying the desired options.
@@ -59,7 +64,8 @@ Parameters
5964
Return Values
6065
-------------
6166

62-
The names of the created Atlas Search indexes as an array of strings.
67+
The names of the created Atlas Search and Vector Search indexes as an
68+
array of strings.
6369

6470
Errors/Exceptions
6571
-----------------
@@ -117,6 +123,7 @@ See Also
117123
- :phpmethod:`MongoDB\Collection::dropSearchIndex()`
118124
- :phpmethod:`MongoDB\Collection::listSearchIndexes()`
119125
- :phpmethod:`MongoDB\Collection::updateSearchIndex()`
126+
- :ref:`php-atlas-search-index` guide
120127
- :manual:`createSearchIndexes </reference/command/createSearchIndexes>` command
121128
reference in the MongoDB manual
122129
- `Atlas Search <https://www.mongodb.com/docs/atlas/atlas-search/>`__ documentation in the MongoDB Manual

source/whats-new.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,13 @@ improvements, and fixes:
164164
encryption and decryption of the data key locally, ensuring that the
165165
encryption key never leaves the KMIP server.
166166

167+
- Adds the ``type`` option in Search index specifications for
168+
the :phpmethod:`MongoDB\Collection::createIndex()` and
169+
:phpmethod:`MongoDB\Collection::createSearchIndexes()` methods. This
170+
change allows you to create Atlas Vector Search indexes
171+
programmatically. To learn more and view examples, see the
172+
:ref:`php-atlas-search-index` guide.
173+
167174
For more information about the changes in this version, see the
168175
:github:`v1.20 release notes
169176
</mongodb/mongo-php-library/releases/tag/1.20.0>` on GitHub.

0 commit comments

Comments
 (0)