rnd 2

Author: baileympearson

source/client-side-operations-timeout/client-side-operations-timeout.md

@@ -427,6 +427,16 @@ check the command document for the presence of a `maxTimeMS` field.
 
 See [runCommand behavior](#runcommand-behavior).
 
+### Explain Helpers
+
+If a driver provides an explain helper, drivers MUST take care to ensure that timeoutMS is correctly applied to the top-level
+explain command, when specified.  Care should be taken by drivers with a fluent API - the following example
+should apply a timeoutMS of 1000 to the `explain` command:
+
+```typescript
+collection.find({}, { timeoutMS: 1000 }).explain();
+```
+
 ## Test Plan
 
 See the [README.rst](tests/README.md) in the tests directory.
@@ -650,6 +660,7 @@ timeout for each database operation. This would mimic using `timeoutMode=ITERATI
 
 ## Changelog
 
+- 2024-08-23: Specify that explain helpers support support timeoutMS.
 - 2023-12-07: Migrated from reStructuredText to Markdown.
 - 2022-11-17: Use minimum RTT for maxTimeMS calculation instead of 90th percentile RTT.
 - 2022-10-05: Remove spec front matter.

source/crud/crud.md

@@ -2198,6 +2198,26 @@ the [$readPreference global command argument](../message/OP_MSG.md#global-comman
 [passing read preference to mongos and load balancers](../server-selection/server-selection.md#passing-read-preference-to-mongos-and-load-balancers)
 (if applicable).
 
+
+### Explain
+
+Drivers MAY provide explain helpers.  If a driver does provide explain helpers, the driver MUST ensure that its helper permits users to
+specify maxTimeMS for the explain command specifically.  An example, using Node, might look like:
+
+```typescript
+collection.find({ name: 'john doe' }).explain({ maxTimeMS: 1000 });
+
+// sends:
+{ 
+  explain: { find: <collection>, query: { name: 'john doe' } },
+  maxTimeMS: 1000
+}
+```
+
+Drivers SHOULD be careful to 
+
+Drivers MUST document how users can specify options on their explain helpers.
+
 ## Test Plan
 
 See the [README](tests/README.md) for tests.
@@ -2305,8 +2325,11 @@ unfortunate, we felt it better to have the bulk api be consistent with the rest
 operations. However, the fluent-bulk-api is still able to be used as this change is non-backwards breaking. Any driver
 which implemented the fluent bulk API should deprecate it and drivers that have not built it should not do so.
 
-Q: What about explain?\
-Explain has been determined to be not a normal use-case for a driver. We'd like users to use the
+Q: Should drivers offer explain helpers?\
+Originally, it was determined that explain should not be exposed via specialized APIs in drivers (runCommand was always an option after server 3.0.).  However, some drivers historically have offered explain APIs and continue to do
+so.  
+
+Explain helpers are not required because it has been determined to be not a normal use-case for a driver. We'd like users to use the
 shell for this purpose. However, explain is still possible from a driver. For find, it can be passed as a modifier.
 Aggregate can be run using a runCommand method passing the explain option. In addition, server 3.0 offers an explain
 command that can be run using a runCommand method.
@@ -2369,6 +2392,8 @@ aforementioned allowance in the SemVer spec.
 
 ## Changelog
 
+- 2024-08-23: Specify that explain helpers support maxTimeMS.
+
 - 2024-02-20: Migrated from reStructuredText to Markdown.
 
 - 2022-10-05: Remove spec front matter and reformat changelog.

source/crud/tests/README.md

@@ -676,3 +676,14 @@ InsertOne {
 
 Execute `bulkWrite` on `client` with `model`. Assert that an error (referred to as `error`) is returned. Assert that
 `error` is a client error containing the message: "bulkWrite does not currently support automatic encryption".
+
+### 14. `explain` helpers allow users to specify `maxTimeMS`
+
+Create a MongoClient with command monitoring enabled (referred to as `client`).
+
+Create a collection, referred to as `collection`, with the namespace `explain-test.collection`.
+
+Run an explained find on `collection`.  The find will have the query predicate `{ name: 'john doe' }`.  Specify
+a maxTimeMS value of 2000ms for the `explain`.
+
+Obtain the command started event for the explain.  Confirm that the top-level explain command should has a `maxTimeMS` value of `2000`.