From 1c40a12e083e2e610adf9e669e90aa047e2de5bf Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Wed, 28 Jun 2023 10:08:05 -0600 Subject: [PATCH 01/16] improve test assertions --- source/index-management/tests/createSearchIndex.json | 6 ++++-- source/index-management/tests/createSearchIndex.yml | 2 ++ source/index-management/tests/createSearchIndexes.json | 9 ++++++--- source/index-management/tests/createSearchIndexes.yml | 3 +++ source/index-management/tests/dropSearchIndex.json | 3 ++- source/index-management/tests/dropSearchIndex.yml | 2 +- source/index-management/tests/listSearchIndexes.json | 9 ++++++--- source/index-management/tests/listSearchIndexes.yml | 3 +++ source/index-management/tests/updateSearchIndex.json | 3 ++- source/index-management/tests/updateSearchIndex.yml | 3 ++- 10 files changed, 31 insertions(+), 12 deletions(-) diff --git a/source/index-management/tests/createSearchIndex.json b/source/index-management/tests/createSearchIndex.json index da664631e7..04cffbe9c9 100644 --- a/source/index-management/tests/createSearchIndex.json +++ b/source/index-management/tests/createSearchIndex.json @@ -54,7 +54,8 @@ } }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], @@ -100,7 +101,8 @@ } }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], diff --git a/source/index-management/tests/createSearchIndex.yml b/source/index-management/tests/createSearchIndex.yml index 0eb5c1ab1d..3f923edaed 100644 --- a/source/index-management/tests/createSearchIndex.yml +++ b/source/index-management/tests/createSearchIndex.yml @@ -31,6 +31,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: @@ -50,6 +51,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: diff --git a/source/index-management/tests/createSearchIndexes.json b/source/index-management/tests/createSearchIndexes.json index b78b3ea6c8..95dbedde77 100644 --- a/source/index-management/tests/createSearchIndexes.json +++ b/source/index-management/tests/createSearchIndexes.json @@ -48,7 +48,8 @@ "models": [] }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], @@ -87,7 +88,8 @@ ] }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], @@ -135,7 +137,8 @@ ] }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], diff --git a/source/index-management/tests/createSearchIndexes.yml b/source/index-management/tests/createSearchIndexes.yml index dc01c1b166..877fc0fa01 100644 --- a/source/index-management/tests/createSearchIndexes.yml +++ b/source/index-management/tests/createSearchIndexes.yml @@ -31,6 +31,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: @@ -51,6 +52,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: @@ -70,6 +72,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: diff --git a/source/index-management/tests/dropSearchIndex.json b/source/index-management/tests/dropSearchIndex.json index b73447f602..0f21a5b68d 100644 --- a/source/index-management/tests/dropSearchIndex.json +++ b/source/index-management/tests/dropSearchIndex.json @@ -48,7 +48,8 @@ "name": "test index" }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], diff --git a/source/index-management/tests/dropSearchIndex.yml b/source/index-management/tests/dropSearchIndex.yml index 5ffef7d17e..bfd6159281 100644 --- a/source/index-management/tests/dropSearchIndex.yml +++ b/source/index-management/tests/dropSearchIndex.yml @@ -31,6 +31,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: @@ -39,4 +40,3 @@ tests: dropSearchIndex: *collection0 name: *indexName $db: *database0 - diff --git a/source/index-management/tests/listSearchIndexes.json b/source/index-management/tests/listSearchIndexes.json index 41e2655fb3..24c51ad88c 100644 --- a/source/index-management/tests/listSearchIndexes.json +++ b/source/index-management/tests/listSearchIndexes.json @@ -45,7 +45,8 @@ "name": "listSearchIndexes", "object": "collection0", "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], @@ -79,7 +80,8 @@ "name": "test index" }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], @@ -119,7 +121,8 @@ } }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], diff --git a/source/index-management/tests/listSearchIndexes.yml b/source/index-management/tests/listSearchIndexes.yml index 7d3c3187b9..c912eae83c 100644 --- a/source/index-management/tests/listSearchIndexes.yml +++ b/source/index-management/tests/listSearchIndexes.yml @@ -29,6 +29,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: @@ -48,6 +49,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: @@ -70,6 +72,7 @@ tests: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: diff --git a/source/index-management/tests/updateSearchIndex.json b/source/index-management/tests/updateSearchIndex.json index 00cd7e7541..88a46a3069 100644 --- a/source/index-management/tests/updateSearchIndex.json +++ b/source/index-management/tests/updateSearchIndex.json @@ -49,7 +49,8 @@ "definition": {} }, "expectError": { - "isError": true + "isError": true, + "errorContains": "Search index commands are only supported with Atlas" } } ], diff --git a/source/index-management/tests/updateSearchIndex.yml b/source/index-management/tests/updateSearchIndex.yml index 215dbc42f9..03d248b3dc 100644 --- a/source/index-management/tests/updateSearchIndex.yml +++ b/source/index-management/tests/updateSearchIndex.yml @@ -28,10 +28,11 @@ tests: arguments: name: &indexName 'test index' definition: &definition {} - expectError: + expectError: # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing # against an Atlas cluster and the expectError will be removed. isError: true + errorContains: Search index commands are only supported with Atlas expectEvents: - client: *client0 events: From fc656d1cbc392a5b2adf4f5971982d9e195f1e74 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Thu, 29 Jun 2023 16:52:42 -0600 Subject: [PATCH 02/16] add prose tests to e2e test search index commands --- source/index-management/tests/README.rst | 154 ++++++++++++++++++++++- 1 file changed, 152 insertions(+), 2 deletions(-) diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index e697dab348..79b05d5ba2 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -31,7 +31,6 @@ For each of the configurations: indicated indexes act on Tests ------ - Run the driver's method that returns a list of index names, and: @@ -45,4 +44,155 @@ Tests - verify the "unique" flags show up for the unique index - verify there are no duplicates in the returned list - if the result consists of statically defined index models that include an ``ns`` field, verify - that its value is accurate \ No newline at end of file + that its value is accurate + +Search Index Management Helpers +------------------------------- + +These tests are intended to smoke test the search management helpers e2e. The search index management commands +are asynchronous and mongod/mongos returns before the changes to a clusters' search indexes have completed. When +these prose tests specify "waiting for the changes", drivers should repeatedly poll the cluster with ``listSearchIndexes`` +until the changes are visible. Each test specifies the criteria which counts as complete. + +Since these commands can take a while to run, drivers should raise the timeout for each test to avoid timeout errors. 5 minutes +is a sufficiently large timeout that any timeout that occurs indicates a real failure. + +There is a server-side limitation that prevents multiple search indexes from being created with the same name, definition and +collection name. This limitation does not take into account collection uuid. Because these commands are asynchronous, any cleanup +code that may run after a test (cleaning a database or dropping search indexes) may not have completed by the next iteration of the +test (or the next test run, if running locally). To address this issue, each test uses a randomly generated collection name. Drivers +may generate this collection name however they like, but a suggested implementation is a hex representation of an +ObjectId (``new ObjectId().toHexString()`` in Node). + +Setup +~~~~~ + +These tests must run against an Atlas cluster with a 7.0+ server. Tools are available drivers-evergreen-tools which can setup and teardown +Atlas clusters. To ensure that the Atlas cluster is cleaned up after each CI run, drivers should configure evergreen to run these tests +as a part of a task group. If a driver has an existing task group that creates an Atlas cluster (such as for FAAS testing), this +task group may be reused as long as the Atlas cluster provisioned satisfies the needs for these tests. + +Case 1: Driver can successfully create and list search indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a new search index on ``coll0`` with the following definition: + + .. code:: typescript + + { + name: 'test-search-index', + definition: { + mappings: { dynamic: false } + } + } + +#. Assert that the command does not error and the server responds with a success. +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: + 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. + 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. +#. Assert that ``index`` has a property ``mappings`` whose value is ``{ dynamic: false }`` + +Case 2: Driver can successfully create multiple indexes in batch +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create two new search indexes on ``coll0`` with the ``createSearchIndexes`` command. Use the following + definitions when creating the indexes. These definitions are referred to as ``indexDefinitions``. + + .. code:: typescript + + { + name: 'test-search-index-1', + definition: { + mappings: { dynamic: false } + } + } + { + name: 'test-search-index-2', + definition: { + mappings: { dynamic: false } + } + } + +#. Assert that the command does not error and the server responds with a success. +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied. Store + the result in ``indexes``. + 1. An index with the ``name`` of ``test-search-index-1`` is present. The ``latestDefinition`` property + of the search index has the field ``queryable`` with a value of ``true``. + 2. An index with the ``name`` of ``test-search-index-2`` is present. The ``latestDefinition`` property + of the search index has the field ``queryable`` with a value of ``true``. +#. For each ``index`` in ``indexDefinitions`` + 1. Find the matching index definition in ``indexes`` by matching on ``index.name``. If no index exists, raise an error. + 2. Assert that the matching index ``mappings``, whose value is ``{ dynamic: false }`` + +Case 3: Driver can successfully drop search indexes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a new search index on ``coll0`` with the following definition: + + .. code:: typescript + + { + name: 'test-search-index', + definition: { + mappings: { dynamic: false } + } + } + +#. Assert that the command does not error and the server responds with a success. +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: + 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. + 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + +#. Run a ``dropSearchIndexes`` on ``coll0``, using ``test-search-index`` for the name. +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until ``listSearchIndexes`` returns an empty array. + +This test fails if it times out waiting for the deletion to succeed. + +Case 4: Driver can update a search index +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a new search index on ``coll0`` with the following definition: + + .. code:: typescript + + { + name: 'test-search-index', + definition: { + mappings: { dynamic: false } + } + } + +#. Assert that the command does not error and the server responds with a success. +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: + 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. + 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + +#. Run a ``updateSearchIndex`` on ``coll0``, using the following definition. + + .. code:: typescript + + { + name: 'test-search-index', + definition: { + mappings: { dynamic: true } + } + } + +#. Assert that the command does not error and the server responds with a success. +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: + 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. + 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + 3. The ``latestDefinition`` property of the search index has the field ``status`` with the value of ``READY``. + +#. Assert that an index is present with the name ``test-search-index`` and the definition has a + property ``mappings``, whose value is ``{ dynamic: true }`` + +Case 5: ``dropSearchIndex`` suppresses namespace not found errors +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +#. Create a driver-side collection object for a randomly generated collection name. Do not create this collection on the server. +#. Run a ``dropSearchIndex`` command and assert that no error is thrown. \ No newline at end of file From fab4493c3e51bdffd201d589da2d54cb7c0a47d0 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Thu, 13 Jul 2023 14:00:15 -0600 Subject: [PATCH 03/16] add clarifations --- .../client-side-operations-timeout.rst | 2 +- source/index-management/index-management.rst | 39 +++++++++++++++++-- source/index-management/tests/README.rst | 13 ++++--- 3 files changed, 45 insertions(+), 9 deletions(-) diff --git a/source/client-side-operations-timeout/client-side-operations-timeout.rst b/source/client-side-operations-timeout/client-side-operations-timeout.rst index 69619d13b9..32a59ee85d 100644 --- a/source/client-side-operations-timeout/client-side-operations-timeout.rst +++ b/source/client-side-operations-timeout/client-side-operations-timeout.rst @@ -131,7 +131,7 @@ specifications: - `Enumerating Collections <../enumerate-collections.rst>`__ - `Enumerating Databases <../enumerate-databases.rst>`__ - `GridFS <../gridfs/gridfs-spec.rst>`__ -- `Index Management <../index-management.rst>`__ +- `Index Management <../index-management/index-management.rst>`__ - `Transactions <../transactions/transactions.rst>`__ - `Convenient API for Transactions <../transactions-convenient-api/transactions-convenient-api.rst>`__ diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index 1f601a1866..29bf0cb97f 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -414,6 +414,10 @@ Index View API * For drivers that cannot make IndexView iterable, they MUST implement this method to * return a list of indexes. In the case of async drivers, this MAY return a Future * or language/implementation equivalent. + * + * If drivers are unable to make the IndexView iterable, they MAY opt to provide the options for + * listing search indexes via the `list` method instead of the `Collection.listSearchIndexes` method. + */ list(): Cursor; @@ -873,8 +877,8 @@ search index management helpers. options as outline in the `CRUD specification `_. Drivers MAY combine the aggregation options with any future ``listSearchIndexes`` stage options, if that is idiomatic for a driver's language. -Notes ------ +Asynchronicity +-------------- The search index commands are asynchronous and return from the server before the index is successfully updated, created or dropped. In order to determine when an index has been created / updated, users are expected to run the ``listSearchIndexes`` repeatedly @@ -888,7 +892,33 @@ An example, from Javascript: while (!(await collection.listSearchIndexes({ name }).hasNext())) { await setTimeout(1000); } - + +Where are read concern and write concern? +----------------------------------------- + +Th + +Consistency with Existing APIs +------------------------------ + +Drivers SHOULD strive for a search index management API that is as consistent with their existing search index management API as much as possible. + + +NamespaceNotFound Errors +------------------------ + +Some drivers suppress NamespaceNotFound errors for CRUD helpers. Drivers MAY suppress NamespaceNotFound errors from +the search index management helpers. + +Drivers MUST suppress NamespaceNotFound errors for the ``dropSearchIndex`` helper. Drop operations should be idempotent: + +.. code:: typescript + await collection.dropSearchIndex('my-test-index'); + // subsequent calls should behave the same for the user as the first call + await collection.dropSearchIndex('my-test-index'); + await collection.dropSearchIndex('my-test-index'); + + Common Interfaces ----------------- @@ -990,6 +1020,9 @@ Index View API for Search Indexes * For drivers that cannot make SearchIndexView iterable, they MUST implement this method to * return a list of indexes. In the case of async drivers, this MAY return a Future * or language/implementation equivalent. + * + * If drivers are unable to make the SearchIndexView iterable, they MAY opt to provide the options for + * listing search indexes via the `list` method instead of the `Collection.listSearchIndexes` method. */ list(): Cursor; diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index 79b05d5ba2..b514875cad 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -49,13 +49,16 @@ Tests Search Index Management Helpers ------------------------------- -These tests are intended to smoke test the search management helpers e2e. The search index management commands -are asynchronous and mongod/mongos returns before the changes to a clusters' search indexes have completed. When +These tests are intended to smoke test the search management helpers end-to-end against a live Atlas cluster. + +The search index management commands are asynchronous and mongod/mongos returns before the changes to a clusters' search indexes have completed. When these prose tests specify "waiting for the changes", drivers should repeatedly poll the cluster with ``listSearchIndexes`` -until the changes are visible. Each test specifies the criteria which counts as complete. +until the changes are visible. Each test specifies the condition that is considered "ready". For example, when creating a +new search index, waiting until the inserted index has a status ``queryable: true`` indicates that the index was successfully +created. -Since these commands can take a while to run, drivers should raise the timeout for each test to avoid timeout errors. 5 minutes -is a sufficiently large timeout that any timeout that occurs indicates a real failure. +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 +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. There is a server-side limitation that prevents multiple search indexes from being created with the same name, definition and collection name. This limitation does not take into account collection uuid. Because these commands are asynchronous, any cleanup From b9d1a3f136857fcae4da3c3094d67de69eb09af2 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Thu, 13 Jul 2023 14:07:24 -0600 Subject: [PATCH 04/16] save file and recommit --- source/index-management/index-management.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index 29bf0cb97f..be3602b452 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -896,7 +896,8 @@ An example, from Javascript: Where are read concern and write concern? ----------------------------------------- -Th +These commands internally proxy the search index management commands to a separate process that runs alongside an Atlas cluster. As such, read concern and +write concern are not relevant for the search index management commands. Consistency with Existing APIs ------------------------------ From 89da8413992d7b98f2870a54afa368ee079f3c73 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Fri, 14 Jul 2023 10:25:07 -0600 Subject: [PATCH 05/16] clarify overloads on search indexes --- source/index-management/index-management.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index be3602b452..ee298626c9 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -957,7 +957,7 @@ Standard API for Search Indexes * takes an SearchIndexModel as a parameter, or for those languages with method * overloading MAY decide to implement both. */ - createSearchIndex(name: String, definition: Document, options: Optional): String; + createSearchIndex(definition: Document, name: Optional, options: Optional): String; /** * Convenience method for creating a single index. @@ -1037,7 +1037,7 @@ Index View API for Search Indexes * takes an SearchIndexModel as a parameter, or for those languages with method * overloading MAY decide to implement both. */ - createOne(name: String, definition: Document, options: Optional): String; + createOne(definition: Document, name: Optional, options: Optional): String; /** * This is a convenience method for creating a single index. From 7f23a773f6d190ec5badacf0daebb40d0c3b813e Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Fri, 14 Jul 2023 11:55:40 -0600 Subject: [PATCH 06/16] remove note on sharing task groups --- source/index-management/tests/README.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index b514875cad..3fcc1b2c4d 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -72,8 +72,9 @@ Setup These tests must run against an Atlas cluster with a 7.0+ server. Tools are available drivers-evergreen-tools which can setup and teardown Atlas clusters. To ensure that the Atlas cluster is cleaned up after each CI run, drivers should configure evergreen to run these tests -as a part of a task group. If a driver has an existing task group that creates an Atlas cluster (such as for FAAS testing), this -task group may be reused as long as the Atlas cluster provisioned satisfies the needs for these tests. +as a part of a task group. Be sure that the cluster gets torn down! + +When working locally on these tests, the same Atlas setup and teardown scripts can be used locally to provision a cluster for development. Case 1: Driver can successfully create and list search indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 594d1967c0dfc70e3e2a77248073712b16cfe195 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Fri, 14 Jul 2023 12:14:45 -0600 Subject: [PATCH 07/16] fix rst lint issues --- source/index-management/tests/README.rst | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index 3fcc1b2c4d..9e94579f2f 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -122,10 +122,8 @@ Case 2: Driver can successfully create multiple indexes in batch #. Assert that the command does not error and the server responds with a success. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied. Store the result in ``indexes``. - 1. An index with the ``name`` of ``test-search-index-1`` is present. The ``latestDefinition`` property - of the search index has the field ``queryable`` with a value of ``true``. - 2. An index with the ``name`` of ``test-search-index-2`` is present. The ``latestDefinition`` property - of the search index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index-1`` is present. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + 2. An index with the ``name`` of ``test-search-index-2`` is present. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. #. For each ``index`` in ``indexDefinitions`` 1. Find the matching index definition in ``indexes`` by matching on ``index.name``. If no index exists, raise an error. 2. Assert that the matching index ``mappings``, whose value is ``{ dynamic: false }`` From bd2092e47f6c45f4602105c3e4bf11ac473b6779 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Mon, 17 Jul 2023 09:24:23 -0600 Subject: [PATCH 08/16] Incorporate fixes from https://github.com/mongodb/specifications/pull/1441 --- source/index-management/index-management.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index ee298626c9..a441643933 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -914,6 +914,7 @@ the search index management helpers. Drivers MUST suppress NamespaceNotFound errors for the ``dropSearchIndex`` helper. Drop operations should be idempotent: .. code:: typescript + await collection.dropSearchIndex('my-test-index'); // subsequent calls should behave the same for the user as the first call await collection.dropSearchIndex('my-test-index'); @@ -1005,7 +1006,7 @@ Index View API for Search Indexes /** * Returns the search index view for this collection. */ - searchIndexes(name: Optional, aggregateOptions: Optional, options: Optional): SearchIndexView; + searchIndexes(name: Optional, aggregateOptions: Optional, options: Optional): SearchIndexView; } interface SearchIndexView extends Iterable { @@ -1065,7 +1066,7 @@ Index View API for Search Indexes /** * Updates a single search index from the collection by the index name. */ - updateOne(name: String, options: Optional): Result; + updateOne(name: String, definition: Document, options: Optional): Result; } --------- From 78554de6a78fc996fa8d1ef9733b123a29ad8309 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Wed, 19 Jul 2023 12:04:36 -0600 Subject: [PATCH 09/16] address comments from Jerome --- source/index-management/index-management.rst | 1 + source/index-management/tests/README.rst | 30 +++++++++----------- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index a441643933..b40c4994c5 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -1128,3 +1128,4 @@ Changelog :2023-05-10: Merge index enumeration and index management specs and get rid of references to legacy server versions. :2023-05-18: Add the search index management API. +:2023-07-17: Add search index management clarifications. \ No newline at end of file diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index 9e94579f2f..dfbb6e8533 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -80,7 +80,7 @@ Case 1: Driver can successfully create and list search indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Create a collection with a randomly generated name (referred to as ``coll0``). -#. Create a new search index on ``coll0`` with the following definition: +#. Create a new search index on ``coll0`` with the ``createSearchIndex`` helper. Use the following definition: .. code:: typescript @@ -91,17 +91,17 @@ Case 1: Driver can successfully create and list search indexes } } -#. Assert that the command does not error and the server responds with a success. +#. Assert that the command returns the name of the index: ``"test-search-index"``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: - 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. - 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index`` is present and index has the field ``queryable`` with a value of ``true``. + #. Assert that ``index`` has a property ``mappings`` whose value is ``{ dynamic: false }`` Case 2: Driver can successfully create multiple indexes in batch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ #. Create a collection with a randomly generated name (referred to as ``coll0``). -#. Create two new search indexes on ``coll0`` with the ``createSearchIndexes`` command. Use the following +#. Create two new search indexes on ``coll0`` with the ``createSearchIndexes`` helper. Use the following definitions when creating the indexes. These definitions are referred to as ``indexDefinitions``. .. code:: typescript @@ -119,11 +119,11 @@ Case 2: Driver can successfully create multiple indexes in batch } } -#. Assert that the command does not error and the server responds with a success. +#. Assert that the command returns an array containing the new indexes' names: ``["test-search-index-1", "test-search-index-2"]``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied. Store the result in ``indexes``. - 1. An index with the ``name`` of ``test-search-index-1`` is present. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. - 2. An index with the ``name`` of ``test-search-index-2`` is present. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index-1`` is present and index has the field ``queryable`` with a value of ``true``. + 2. An index with the ``name`` of ``test-search-index-2`` is present and index has the field ``queryable`` with a value of ``true``. #. For each ``index`` in ``indexDefinitions`` 1. Find the matching index definition in ``indexes`` by matching on ``index.name``. If no index exists, raise an error. 2. Assert that the matching index ``mappings``, whose value is ``{ dynamic: false }`` @@ -143,10 +143,9 @@ Case 3: Driver can successfully drop search indexes } } -#. Assert that the command does not error and the server responds with a success. +#. Assert that the command returns the name of the index: ``"test-search-index"``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: - 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. - 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index`` is present and index has the field ``queryable`` with a value of ``true``. #. Run a ``dropSearchIndexes`` on ``coll0``, using ``test-search-index`` for the name. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until ``listSearchIndexes`` returns an empty array. @@ -168,10 +167,9 @@ Case 4: Driver can update a search index } } -#. Assert that the command does not error and the server responds with a success. +#. Assert that the command returns the name of the index: ``"test-search-index"``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: - 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. - 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index`` is present and index has the field ``queryable`` with a value of ``true``. #. Run a ``updateSearchIndex`` on ``coll0``, using the following definition. @@ -187,8 +185,8 @@ Case 4: Driver can update a search index #. Assert that the command does not error and the server responds with a success. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. - 2. The ``latestDefinition`` property of the search index has the field ``queryable`` with a value of ``true``. - 3. The ``latestDefinition`` property of the search index has the field ``status`` with the value of ``READY``. + 2. The index has a field ``queryable`` with a value of ``true``. + 3. The index has a ``latestDefinition`` property. The ``latestDefinition`` field has a property ``status`` with the value of ``READY``. #. Assert that an index is present with the name ``test-search-index`` and the definition has a property ``mappings``, whose value is ``{ dynamic: true }`` From 48a2d61e33fa91c8ffd0c70546bee94c5dfa506c Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Fri, 21 Jul 2023 13:48:38 -0600 Subject: [PATCH 10/16] fix wording in updateSearchIndexes --- source/index-management/tests/README.rst | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index dfbb6e8533..05f1e48443 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -93,7 +93,7 @@ Case 1: Driver can successfully create and list search indexes #. Assert that the command returns the name of the index: ``"test-search-index"``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: - 1. An index with the ``name`` of ``test-search-index`` is present and index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index`` is present and the index has a field ``queryable`` with a value of ``true``. #. Assert that ``index`` has a property ``mappings`` whose value is ``{ dynamic: false }`` @@ -122,8 +122,8 @@ Case 2: Driver can successfully create multiple indexes in batch #. Assert that the command returns an array containing the new indexes' names: ``["test-search-index-1", "test-search-index-2"]``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied. Store the result in ``indexes``. - 1. An index with the ``name`` of ``test-search-index-1`` is present and index has the field ``queryable`` with a value of ``true``. - 2. An index with the ``name`` of ``test-search-index-2`` is present and index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index-1`` is present and index has a field ``queryable`` with the value of ``true``. + 2. An index with the ``name`` of ``test-search-index-2`` is present and index has a field ``queryable`` with the value of ``true``. #. For each ``index`` in ``indexDefinitions`` 1. Find the matching index definition in ``indexes`` by matching on ``index.name``. If no index exists, raise an error. 2. Assert that the matching index ``mappings``, whose value is ``{ dynamic: false }`` @@ -145,7 +145,7 @@ Case 3: Driver can successfully drop search indexes #. Assert that the command returns the name of the index: ``"test-search-index"``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: - 1. An index with the ``name`` of ``test-search-index`` is present and index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index`` is present and index has a field ``queryable`` with the value of ``true``. #. Run a ``dropSearchIndexes`` on ``coll0``, using ``test-search-index`` for the name. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until ``listSearchIndexes`` returns an empty array. @@ -169,7 +169,7 @@ Case 4: Driver can update a search index #. Assert that the command returns the name of the index: ``"test-search-index"``. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: - 1. An index with the ``name`` of ``test-search-index`` is present and index has the field ``queryable`` with a value of ``true``. + 1. An index with the ``name`` of ``test-search-index`` is present and index has a field ``queryable`` with the value of ``true``. #. Run a ``updateSearchIndex`` on ``coll0``, using the following definition. @@ -185,8 +185,7 @@ Case 4: Driver can update a search index #. Assert that the command does not error and the server responds with a success. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: 1. An index with the ``name`` of ``test-search-index`` is present. This index is referred to as ``index``. - 2. The index has a field ``queryable`` with a value of ``true``. - 3. The index has a ``latestDefinition`` property. The ``latestDefinition`` field has a property ``status`` with the value of ``READY``. + 2. The index has a field ``queryable`` with a value of ``true`` and has a field ``status`` with the value of ``READY``. #. Assert that an index is present with the name ``test-search-index`` and the definition has a property ``mappings``, whose value is ``{ dynamic: true }`` From 0d8639a2c484b6665c12defd1e454fa63d66cb7b Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Mon, 24 Jul 2023 14:47:49 -0600 Subject: [PATCH 11/16] address Daria's comments --- source/index-management/index-management.rst | 2 +- source/index-management/tests/createSearchIndex.yml | 8 ++++---- .../index-management/tests/createSearchIndexes.yml | 12 ++++++------ source/index-management/tests/dropSearchIndex.yml | 4 ++-- source/index-management/tests/listSearchIndexes.yml | 12 ++++++------ source/index-management/tests/updateSearchIndex.yml | 4 ++-- 6 files changed, 21 insertions(+), 21 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index b40c4994c5..1480380308 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -902,7 +902,7 @@ write concern are not relevant for the search index management commands. Consistency with Existing APIs ------------------------------ -Drivers SHOULD strive for a search index management API that is as consistent with their existing search index management API as much as possible. +Drivers SHOULD strive for a search index management API that is as consistent with their existing index management API as much as possible. NamespaceNotFound Errors diff --git a/source/index-management/tests/createSearchIndex.yml b/source/index-management/tests/createSearchIndex.yml index 3f923edaed..6aa56f3bc4 100644 --- a/source/index-management/tests/createSearchIndex.yml +++ b/source/index-management/tests/createSearchIndex.yml @@ -28,8 +28,8 @@ tests: arguments: model: { definition: &definition { mappings: { dynamic: true } } } expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: @@ -48,8 +48,8 @@ tests: arguments: model: { definition: &definition { mappings: { dynamic: true } } , name: 'test index' } expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: diff --git a/source/index-management/tests/createSearchIndexes.yml b/source/index-management/tests/createSearchIndexes.yml index 877fc0fa01..54a6e84ccb 100644 --- a/source/index-management/tests/createSearchIndexes.yml +++ b/source/index-management/tests/createSearchIndexes.yml @@ -28,8 +28,8 @@ tests: arguments: models: [] expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: @@ -49,8 +49,8 @@ tests: arguments: models: [ { definition: &definition { mappings: { dynamic: true } } } ] expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: @@ -69,8 +69,8 @@ tests: arguments: models: [ { definition: &definition { mappings: { dynamic: true } } , name: 'test index' } ] expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: diff --git a/source/index-management/tests/dropSearchIndex.yml b/source/index-management/tests/dropSearchIndex.yml index bfd6159281..e384cf26c5 100644 --- a/source/index-management/tests/dropSearchIndex.yml +++ b/source/index-management/tests/dropSearchIndex.yml @@ -28,8 +28,8 @@ tests: arguments: name: &indexName 'test index' expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: diff --git a/source/index-management/tests/listSearchIndexes.yml b/source/index-management/tests/listSearchIndexes.yml index c912eae83c..a50becdf1d 100644 --- a/source/index-management/tests/listSearchIndexes.yml +++ b/source/index-management/tests/listSearchIndexes.yml @@ -26,8 +26,8 @@ tests: - name: listSearchIndexes object: *collection0 expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: @@ -46,8 +46,8 @@ tests: arguments: name: &indexName "test index" expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: @@ -69,8 +69,8 @@ tests: aggregationOptions: batchSize: 10 expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: diff --git a/source/index-management/tests/updateSearchIndex.yml b/source/index-management/tests/updateSearchIndex.yml index 03d248b3dc..bb18ab512e 100644 --- a/source/index-management/tests/updateSearchIndex.yml +++ b/source/index-management/tests/updateSearchIndex.yml @@ -29,8 +29,8 @@ tests: name: &indexName 'test index' definition: &definition {} expectError: - # Search indexes are only available on 7.0+ atlas clusters. DRIVERS-2630 will add e2e testing - # against an Atlas cluster and the expectError will be removed. + # This test always errors in a non-Atlas environment. The test functions as a unit test by asserting + # that the driver constructs and sends the correct command. isError: true errorContains: Search index commands are only supported with Atlas expectEvents: From e19e67d2ccf5620a971434eaf7feeb4bbcb911c8 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Tue, 25 Jul 2023 13:42:24 -0600 Subject: [PATCH 12/16] address comments --- source/index-management/tests/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index 05f1e48443..767c4d79c7 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -92,7 +92,7 @@ Case 1: Driver can successfully create and list search indexes } #. Assert that the command returns the name of the index: ``"test-search-index"``. -#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied and store the value in a variable ``index``: 1. An index with the ``name`` of ``test-search-index`` is present and the index has a field ``queryable`` with a value of ``true``. #. Assert that ``index`` has a property ``mappings`` whose value is ``{ dynamic: false }`` From 91abe38551bac276754ac74f7bd5a538360481c0 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Tue, 25 Jul 2023 13:44:13 -0600 Subject: [PATCH 13/16] address comments --- source/index-management/index-management.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index 1480380308..b3bf0a79c2 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -902,8 +902,7 @@ write concern are not relevant for the search index management commands. Consistency with Existing APIs ------------------------------ -Drivers SHOULD strive for a search index management API that is as consistent with their existing index management API as much as possible. - +Drivers SHOULD strive for a search index management API that is as consistent as possible with their existing index management API. NamespaceNotFound Errors ------------------------ @@ -934,6 +933,11 @@ Common Interfaces name: Optional; } + interface SearchIndexOptions { + // The name for this index, if present. + name: Optional; + } + /** * The following interfaces are empty but are provided as placeholders for drivers that cannot * add options in a non-breaking manner, if options are added in the future. @@ -957,8 +961,10 @@ Standard API for Search Indexes * @note Drivers MAY opt to implement this method signature, the signature that * takes an SearchIndexModel as a parameter, or for those languages with method * overloading MAY decide to implement both. + * + * @note Drivers MAY combine the `indexOptions` with the `createSearchIndexOptions`, if that is idiomatic for their language. */ - createSearchIndex(definition: Document, name: Optional, options: Optional): String; + createSearchIndex(definition: Document, indexOptions: SearchIndexOptions, createSearchIndexOptions: Optional): String; /** * Convenience method for creating a single index. @@ -1037,8 +1043,10 @@ Index View API for Search Indexes * @note Drivers MAY opt to implement this method signature, the signature that * takes an SearchIndexModel as a parameter, or for those languages with method * overloading MAY decide to implement both. + * + * @note Drivers MAY combine the `indexOptions` with the `createSearchIndexOptions`, if that is idiomatic for their language. */ - createOne(definition: Document, name: Optional, options: Optional): String; + createOne(definition: Document, indexOptions: SearchIndexOptions, createSearchIndexOptions: Optional): String; /** * This is a convenience method for creating a single index. From bdf1ab8efee4b5d4b95e42577470a9bc4a4b5803 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Thu, 27 Jul 2023 09:47:05 -0600 Subject: [PATCH 14/16] Apply suggestions from code review Co-authored-by: Kevin Albertson --- source/index-management/index-management.rst | 4 ++-- source/index-management/tests/README.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index b3bf0a79c2..53b22c71fe 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -416,7 +416,7 @@ Index View API * or language/implementation equivalent. * * If drivers are unable to make the IndexView iterable, they MAY opt to provide the options for - * listing search indexes via the `list` method instead of the `Collection.listSearchIndexes` method. + * listing search indexes via the `list` method instead of the `Collection.indexes` method. */ list(): Cursor; @@ -1030,7 +1030,7 @@ Index View API for Search Indexes * or language/implementation equivalent. * * If drivers are unable to make the SearchIndexView iterable, they MAY opt to provide the options for - * listing search indexes via the `list` method instead of the `Collection.listSearchIndexes` method. + * listing search indexes via the `list` method instead of the `Collection.searchIndexes` method. */ list(): Cursor; diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index 767c4d79c7..5d7eee2107 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -70,7 +70,7 @@ ObjectId (``new ObjectId().toHexString()`` in Node). Setup ~~~~~ -These tests must run against an Atlas cluster with a 7.0+ server. Tools are available drivers-evergreen-tools which can setup and teardown +These tests must run against an Atlas cluster with a 7.0+ server. `Scripts are available `_ in drivers-evergreen-tools which can setup and teardown Atlas clusters. To ensure that the Atlas cluster is cleaned up after each CI run, drivers should configure evergreen to run these tests as a part of a task group. Be sure that the cluster gets torn down! From a10c4bf7fcb9f8232e58c237f362315494ed2100 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Thu, 27 Jul 2023 10:08:21 -0600 Subject: [PATCH 15/16] address comments --- source/index-management/index-management.rst | 4 +-- source/index-management/tests/README.rst | 26 +++++++++----------- 2 files changed, 13 insertions(+), 17 deletions(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index 53b22c71fe..7a5df75d32 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -964,7 +964,7 @@ Standard API for Search Indexes * * @note Drivers MAY combine the `indexOptions` with the `createSearchIndexOptions`, if that is idiomatic for their language. */ - createSearchIndex(definition: Document, indexOptions: SearchIndexOptions, createSearchIndexOptions: Optional): String; + createSearchIndex(definition: Document, indexOptions: Optional, createSearchIndexOptions: Optional): String; /** * Convenience method for creating a single index. @@ -1046,7 +1046,7 @@ Index View API for Search Indexes * * @note Drivers MAY combine the `indexOptions` with the `createSearchIndexOptions`, if that is idiomatic for their language. */ - createOne(definition: Document, indexOptions: SearchIndexOptions, createSearchIndexOptions: Optional): String; + createOne(definition: Document, indexOptions: Optional, createSearchIndexOptions: Optional): String; /** * This is a convenience method for creating a single index. diff --git a/source/index-management/tests/README.rst b/source/index-management/tests/README.rst index 5d7eee2107..9cf8f6d6b9 100644 --- a/source/index-management/tests/README.rst +++ b/source/index-management/tests/README.rst @@ -79,7 +79,7 @@ When working locally on these tests, the same Atlas setup and teardown scripts c Case 1: Driver can successfully create and list search indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a collection with the "create" command using a randomly generated name (referred to as ``coll0``). #. Create a new search index on ``coll0`` with the ``createSearchIndex`` helper. Use the following definition: .. code:: typescript @@ -95,12 +95,12 @@ Case 1: Driver can successfully create and list search indexes #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied and store the value in a variable ``index``: 1. An index with the ``name`` of ``test-search-index`` is present and the index has a field ``queryable`` with a value of ``true``. -#. Assert that ``index`` has a property ``mappings`` whose value is ``{ dynamic: false }`` +#. Assert that ``index`` has a property ``latestDefinition`` whose value is ``{ 'mappings': { 'dynamic': false } }`` Case 2: Driver can successfully create multiple indexes in batch ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a collection with the "create" command using a randomly generated name (referred to as ``coll0``). #. Create two new search indexes on ``coll0`` with the ``createSearchIndexes`` helper. Use the following definitions when creating the indexes. These definitions are referred to as ``indexDefinitions``. @@ -120,18 +120,14 @@ Case 2: Driver can successfully create multiple indexes in batch } #. Assert that the command returns an array containing the new indexes' names: ``["test-search-index-1", "test-search-index-2"]``. -#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied. Store - the result in ``indexes``. - 1. An index with the ``name`` of ``test-search-index-1`` is present and index has a field ``queryable`` with the value of ``true``. - 2. An index with the ``name`` of ``test-search-index-2`` is present and index has a field ``queryable`` with the value of ``true``. -#. For each ``index`` in ``indexDefinitions`` - 1. Find the matching index definition in ``indexes`` by matching on ``index.name``. If no index exists, raise an error. - 2. Assert that the matching index ``mappings``, whose value is ``{ dynamic: false }`` - +#. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied. + 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``. + 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``. +#. Assert that ``index1`` and ``index2`` have the property ``latestDefinition`` whose value is ``{ "mappings" : { "dynamic" : false } }`` Case 3: Driver can successfully drop search indexes ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a collection with the "create" command using a randomly generated name (referred to as ``coll0``). #. Create a new search index on ``coll0`` with the following definition: .. code:: typescript @@ -147,7 +143,7 @@ Case 3: Driver can successfully drop search indexes #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until the following condition is satisfied: 1. An index with the ``name`` of ``test-search-index`` is present and index has a field ``queryable`` with the value of ``true``. -#. Run a ``dropSearchIndexes`` on ``coll0``, using ``test-search-index`` for the name. +#. Run a ``dropSearchIndex`` on ``coll0``, using ``test-search-index`` for the name. #. Run ``coll0.listSearchIndexes()`` repeatedly every 5 seconds until ``listSearchIndexes`` returns an empty array. This test fails if it times out waiting for the deletion to succeed. @@ -155,7 +151,7 @@ This test fails if it times out waiting for the deletion to succeed. Case 4: Driver can update a search index ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -#. Create a collection with a randomly generated name (referred to as ``coll0``). +#. Create a collection with the "create" command using a randomly generated name (referred to as ``coll0``). #. Create a new search index on ``coll0`` with the following definition: .. code:: typescript @@ -188,7 +184,7 @@ Case 4: Driver can update a search index 2. The index has a field ``queryable`` with a value of ``true`` and has a field ``status`` with the value of ``READY``. #. Assert that an index is present with the name ``test-search-index`` and the definition has a - property ``mappings``, whose value is ``{ dynamic: true }`` + property ``latestDefinition`` whose value is ``{ 'mappings': { 'dynamic': true } }``. Case 5: ``dropSearchIndex`` suppresses namespace not found errors ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 21ec41f19b7ac6d8044d3ed3ca157d329e1ad050 Mon Sep 17 00:00:00 2001 From: Bailey Pearson Date: Thu, 27 Jul 2023 13:09:21 -0600 Subject: [PATCH 16/16] Update source/index-management/index-management.rst --- source/index-management/index-management.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index-management/index-management.rst b/source/index-management/index-management.rst index 7a5df75d32..b92753d879 100644 --- a/source/index-management/index-management.rst +++ b/source/index-management/index-management.rst @@ -1136,4 +1136,4 @@ Changelog :2023-05-10: Merge index enumeration and index management specs and get rid of references to legacy server versions. :2023-05-18: Add the search index management API. -:2023-07-17: Add search index management clarifications. \ No newline at end of file +:2023-07-27: Add search index management clarifications. \ No newline at end of file