You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: source/index-management/index-management.rst
+51-7Lines changed: 51 additions & 7 deletions
Original file line number
Diff line number
Diff line change
@@ -414,6 +414,10 @@ Index View API
414
414
* For drivers that cannot make IndexView iterable, they MUST implement this method to
415
415
* return a list of indexes. In the case of async drivers, this MAY return a Future<Cursor>
416
416
* or language/implementation equivalent.
417
+
*
418
+
* If drivers are unable to make the IndexView iterable, they MAY opt to provide the options for
419
+
* listing search indexes via the `list` method instead of the `Collection.indexes` method.
420
+
417
421
*/
418
422
list():Cursor;
419
423
@@ -873,8 +877,8 @@ search index management helpers.
873
877
options as outline in the `CRUD specification <https://github.com/mongodb/specifications/blob/master/source/crud/crud.rst#read>`_. Drivers MAY combine the aggregation options with
874
878
any future ``listSearchIndexes`` stage options, if that is idiomatic for a driver's language.
875
879
876
-
Notes
877
-
-----
880
+
Asynchronicity
881
+
--------------
878
882
879
883
The search index commands are asynchronous and return from the server before the index is successfully updated, created or dropped.
880
884
In order to determine when an index has been created / updated, users are expected to run the ``listSearchIndexes`` repeatedly
@@ -888,7 +892,34 @@ An example, from Javascript:
888
892
while (!(await collection.listSearchIndexes({ name }).hasNext())) {
889
893
await setTimeout(1000);
890
894
}
891
-
895
+
896
+
Where are read concern and write concern?
897
+
-----------------------------------------
898
+
899
+
These commands internally proxy the search index management commands to a separate process that runs alongside an Atlas cluster. As such, read concern and
900
+
write concern are not relevant for the search index management commands.
901
+
902
+
Consistency with ExistingAPIs
903
+
------------------------------
904
+
905
+
DriversSHOULD strive for a search index management API that is as consistent as possible with their existing index management API.
906
+
907
+
NamespaceNotFoundErrors
908
+
------------------------
909
+
910
+
Some drivers suppress NamespaceNotFound errors forCRUD helpers. DriversMAY suppress NamespaceNotFound errors from
911
+
the search index management helpers.
912
+
913
+
DriversMUST suppress NamespaceNotFound errors for the ``dropSearchIndex`` helper. Drop operations should be idempotent:
Copy file name to clipboardExpand all lines: source/index-management/tests/README.rst
+147-2Lines changed: 147 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -31,7 +31,6 @@ For each of the configurations:
31
31
indicated indexes act on
32
32
33
33
Tests
34
-
-----
35
34
36
35
- Run the driver's method that returns a list of index names, and:
37
36
@@ -45,4 +44,150 @@ Tests
45
44
- verify the "unique" flags show up for the unique index
46
45
- verify there are no duplicates in the returned list
47
46
- if the result consists of statically defined index models that include an ``ns`` field, verify
48
-
that its value is accurate
47
+
that its value is accurate
48
+
49
+
Search Index Management Helpers
50
+
-------------------------------
51
+
52
+
These tests are intended to smoke test the search management helpers end-to-end against a live Atlas cluster.
53
+
54
+
The search index management commands are asynchronous and mongod/mongos returns before the changes to a clusters' search indexes have completed. When
55
+
these prose tests specify "waiting for the changes", drivers should repeatedly poll the cluster with ``listSearchIndexes``
56
+
until the changes are visible. Each test specifies the condition that is considered "ready". For example, when creating a
57
+
new search index, waiting until the inserted index has a status ``queryable: true`` indicates that the index was successfully
58
+
created.
59
+
60
+
The commands tested in these prose tests take a while to successfully complete. Drivers should raise the timeout for each test to avoid timeout errors if
61
+
the test timeout is too low. 5 minutes is a sufficiently large timeout that any timeout that occurs indicates a real failure, but this value is not required and can be tweaked per-driver.
62
+
63
+
There is a server-side limitation that prevents multiple search indexes from being created with the same name, definition and
64
+
collection name. This limitation does not take into account collection uuid. Because these commands are asynchronous, any cleanup
65
+
code that may run after a test (cleaning a database or dropping search indexes) may not have completed by the next iteration of the
66
+
test (or the next test run, if running locally). To address this issue, each test uses a randomly generated collection name. Drivers
67
+
may generate this collection name however they like, but a suggested implementation is a hex representation of an
68
+
ObjectId (``new ObjectId().toHexString()`` in Node).
69
+
70
+
Setup
71
+
~~~~~
72
+
73
+
These tests must run against an Atlas cluster with a 7.0+ server. `Scripts are available <https://github.com/mongodb-labs/drivers-evergreen-tools/tree/master/.evergreen/atlas>`_ in drivers-evergreen-tools which can setup and teardown
74
+
Atlas clusters. To ensure that the Atlas cluster is cleaned up after each CI run, drivers should configure evergreen to run these tests
75
+
as a part of a task group. Be sure that the cluster gets torn down!
76
+
77
+
When working locally on these tests, the same Atlas setup and teardown scripts can be used locally to provision a cluster for development.
78
+
79
+
Case 1: Driver can successfully create and list search indexes
#. Create a collection with the "create" command using a randomly generated name (referred to as ``coll0``).
83
+
#. Create a new search index on ``coll0`` with the ``createSearchIndex`` helper. Use the following definition:
84
+
85
+
.. code:: typescript
86
+
87
+
{
88
+
name: 'test-search-index',
89
+
definition: {
90
+
mappings: { dynamic: false }
91
+
}
92
+
}
93
+
94
+
#. Assert that the command returns the name of the index: ``"test-search-index"``.
95
+
#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied and store the value in a variable ``index``:
96
+
1. An index with the ``name`` of ``test-search-index`` is present and the index has a field ``queryable`` with a value of ``true``.
97
+
98
+
#. Assert that ``index`` has a property ``latestDefinition`` whose value is ``{ 'mappings': { 'dynamic': false } }``
99
+
100
+
Case 2: Driver can successfully create multiple indexes in batch
#. Create a collection with the "create" command using a randomly generated name (referred to as ``coll0``).
104
+
#. Create two new search indexes on ``coll0`` with the ``createSearchIndexes`` helper. Use the following
105
+
definitions when creating the indexes. These definitions are referred to as ``indexDefinitions``.
106
+
107
+
.. code:: typescript
108
+
109
+
{
110
+
name: 'test-search-index-1',
111
+
definition: {
112
+
mappings: { dynamic: false }
113
+
}
114
+
}
115
+
{
116
+
name: 'test-search-index-2',
117
+
definition: {
118
+
mappings: { dynamic: false }
119
+
}
120
+
}
121
+
122
+
#. Assert that the command returns an array containing the new indexes' names: ``["test-search-index-1", "test-search-index-2"]``.
123
+
#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied.
124
+
1. An index with the ``name`` of ``test-search-index-1`` is present and index has a field ``queryable`` with the value of ``true``. Store result in ``index1``.
125
+
2. An index with the ``name`` of ``test-search-index-2`` is present and index has a field ``queryable`` with the value of ``true``. Store result in ``index2``.
126
+
#. Assert that ``index1`` and ``index2`` have the property ``latestDefinition`` whose value is ``{ "mappings" : { "dynamic" : false } }``
127
+
Case 3: Driver can successfully drop search indexes
0 commit comments