add explain functionality to find and agg

Author: HanaPearlman

src/cmap/wire_protocol/query.ts

@@ -1,12 +1,13 @@
 import { command, CommandOptions } from './command';
 import { Query } from '../commands';
 import { MongoError } from '../../error';
-import { maxWireVersion, collectionNamespace, Callback } from '../../utils';
+import { maxWireVersion, collectionNamespace, Callback, decorateWithExplain } from '../../utils';
 import { getReadPreference, isSharded, applyCommonQueryOptions } from './shared';
 import { Document, pluckBSONSerializeOptions } from '../../bson';
 import type { Server } from '../../sdam/server';
 import type { ReadPreferenceLike } from '../../read_preference';
 import type { FindOptions } from '../../operations/find';
+import { Explain } from '../../explain';
 
 /** @internal */
 export interface QueryOptions extends CommandOptions {
@@ -26,7 +27,7 @@ export function query(
     return callback(new MongoError(`command ${JSON.stringify(cmd)} does not return a cursor`));
   }
 
-  if (maxWireVersion(server) < 4) {
+  if (shouldUseLegacyQuery(server, options)) {
     const query = prepareLegacyFindQuery(server, ns, cmd, options);
     const queryOptions = applyCommonQueryOptions(
       {},
@@ -43,7 +44,14 @@ export function query(
   }
 
   const readPreference = getReadPreference(cmd, options);
-  const findCmd = prepareFindCommand(server, ns, cmd);
+  let findCmd = prepareFindCommand(server, ns, cmd);
+
+  // If we have explain, we need to rewrite the find command
+  // to wrap it in the explain command
+  const explain = Explain.fromOptions(options);
+  if (explain) {
+    findCmd = decorateWithExplain(findCmd, explain);
+  }
 
   // NOTE: This actually modifies the passed in cmd, and our code _depends_ on this
   //       side-effect. Change this ASAP
@@ -61,8 +69,15 @@ export function query(
   command(server, ns, findCmd, commandOptions, callback);
 }
 
+// Typically, a legacy find query is used for wire versions prior to 4. However, for explain with
+// find on wire versions between 3 and 4, we can't use a legacy find command.
+function shouldUseLegacyQuery(server: Server, options: FindOptions): boolean {
+  const wireVersion = maxWireVersion(server);
+  return wireVersion <= 3 || (wireVersion < 4 && options.explain === undefined);
+}
+
 function prepareFindCommand(server: Server, ns: string, cmd: Document) {
-  let findCmd: Document = {
+  const findCmd: Document = {
     find: collectionNamespace(ns)
   };
 
@@ -146,14 +161,6 @@ function prepareFindCommand(server: Server, ns: string, cmd: Document) {
   if (cmd.collation) findCmd.collation = cmd.collation;
   if (cmd.readConcern) findCmd.readConcern = cmd.readConcern;
 
-  // If we have explain, we need to rewrite the find command
-  // to wrap it in the explain command
-  if (cmd.explain) {
-    findCmd = {
-      explain: findCmd
-    };
-  }
-
   return findCmd;
 }
 
@@ -195,7 +202,7 @@ function prepareLegacyFindQuery(
   if (typeof cmd.showDiskLoc !== 'undefined') findCmd['$showDiskLoc'] = cmd.showDiskLoc;
   if (cmd.comment) findCmd['$comment'] = cmd.comment;
   if (cmd.maxTimeMS) findCmd['$maxTimeMS'] = cmd.maxTimeMS;
-  if (cmd.explain) {
+  if (options.explain !== undefined) {
     // nToReturn must be 0 (match all) or negative (match N and close cursor)
     // nToReturn > 0 will give explain results equivalent to limit(0)
     numberToReturn = -Math.abs(cmd.limit || 0);

src/cursor/cursor.ts

@@ -13,12 +13,13 @@ import { PromiseProvider } from '../promise_provider';
 import type { OperationTime, ResumeToken } from '../change_stream';
 import type { CloseOptions } from '../cmap/connection_pool';
 import type { CollationOptions } from '../cmap/wire_protocol/write_command';
-import type { Hint, OperationBase } from '../operations/operation';
+import { Aspect, Hint, OperationBase } from '../operations/operation';
 import type { Topology } from '../sdam/topology';
-import type { CommandOperationOptions } from '../operations/command';
+import { CommandOperation, CommandOperationOptions } from '../operations/command';
 import type { ReadConcern } from '../read_concern';
 import type { Server } from '../sdam/server';
 import type { ClientSession } from '../sessions';
+import { Explain, ExplainVerbosityLike } from '../explain';
 
 const kCursor = Symbol('cursor');
 
@@ -1300,26 +1301,22 @@ export class Cursor<
   /**
    * Execute the explain for the cursor
    *
+   * @param verbosity - The mode in which to run the explain.
    * @param callback - The result callback.
    */
-  explain(): Promise<unknown>;
-  explain(callback: Callback): void;
-  explain(callback?: Callback): Promise<unknown> | void {
-    // NOTE: the next line includes a special case for operations which do not
-    //       subclass `CommandOperationV2`. To be removed asap.
-    // TODO NODE-2853: This had to be removed during NODE-2852; fix while re-implementing
-    // cursor explain
-    // if (this.operation && this.operation.cmd == null) {
-    //   this.operation.options.explain = true;
-    //   return executeOperation(this.topology, this.operation as any, callback);
-    // }
-
-    this.cmd.explain = true;
-
-    // Do we have a readConcern
-    if (this.cmd.readConcern) {
-      delete this.cmd['readConcern'];
-    }
+  explain(verbosity?: ExplainVerbosityLike): Promise<unknown>;
+  explain(verbosity?: ExplainVerbosityLike, callback?: Callback): Promise<unknown> | void {
+    if (typeof verbosity === 'function') (callback = verbosity), (verbosity = true);
+    if (verbosity === undefined) verbosity = true;
+
+    // TODO: For now, we need to manually do these checks. This will change after cursor refactor.
+    if (
+      !(this.operation instanceof CommandOperation) ||
+      !this.operation.hasAspect(Aspect.EXPLAINABLE)
+    ) {
+      throw new MongoError('This command cannot be explained');
+    }
+    this.operation.explain = new Explain(verbosity);
 
     return maybePromise(callback, cb => nextFunction(this, cb));
   }

src/explain.ts

@@ -9,8 +9,9 @@ export const ExplainVerbosity = {
 } as const;
 
 /**
- * For backwards compatibility, true is interpreted as
- * "allPlansExecution" and false as "queryPlanner".
+ * For backwards compatibility, true is interpreted as "allPlansExecution"
+ * and false as "queryPlanner". Prior to server version 3.6, aggregate()
+ * ignores the verbosity parameter and executes in "queryPlanner".
  * @public
  */
 export type ExplainVerbosityLike = keyof typeof ExplainVerbosity | boolean;

src/operations/aggregate.ts

@@ -65,10 +65,8 @@ export class AggregateOperation<T = Document> extends CommandOperation<Aggregate
       this.readPreference = ReadPreference.primary;
     }
 
-    if (options?.explain && (this.readConcern || this.writeConcern)) {
-      throw new MongoError(
-        '"explain" cannot be used on an aggregate call with readConcern/writeConcern'
-      );
+    if (options?.explain && this.writeConcern) {
+      throw new MongoError('"explain" cannot be used on an aggregate call with writeConcern');
     }
 
     if (options?.cursor != null && typeof options.cursor !== 'object') {
@@ -111,10 +109,6 @@ export class AggregateOperation<T = Document> extends CommandOperation<Aggregate
       command.hint = options.hint;
     }
 
-    if (options.explain) {
-      command.explain = options.explain;
-    }
-
     command.cursor = options.cursor || {};
     if (options.batchSize && !this.hasWriteStage) {
       command.cursor.batchSize = options.batchSize;
@@ -124,4 +118,4 @@ export class AggregateOperation<T = Document> extends CommandOperation<Aggregate
   }
 }
 
-defineAspects(AggregateOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE]);
+defineAspects(AggregateOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE, Aspect.EXPLAINABLE]);

src/operations/command.ts

@@ -145,7 +145,12 @@ export abstract class CommandOperation<
     }
 
     if (this.hasAspect(Aspect.EXPLAINABLE) && this.explain) {
-      cmd = decorateWithExplain(cmd, this.explain);
+      if (serverWireVersion < 6 && cmd.aggregate) {
+        // Prior to 3.6, with aggregate, verbosity is ignored, and we must pass in "explain: true"
+        cmd.explain = true;
+      } else {
+        cmd = decorateWithExplain(cmd, this.explain);
+      }
     }
 
     server.command(

src/operations/find.ts

@@ -212,6 +212,11 @@ export class FindOperation extends CommandOperation<FindOptions, Document> {
       findCommand.allowDiskUse = options.allowDiskUse;
     }
 
+    if (this.explain) {
+      // TODO: For now, we need to manually ensure explain is in the options. This will change after cursor refactor.
+      this.options.explain = this.explain.verbosity;
+    }
+
     // TODO: use `MongoDBNamespace` through and through
     server.query(
       this.ns.toString(),
@@ -222,4 +227,4 @@ export class FindOperation extends CommandOperation<FindOptions, Document> {
   }
 }
 
-defineAspects(FindOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE]);
+defineAspects(FindOperation, [Aspect.READ_OPERATION, Aspect.RETRYABLE, Aspect.EXPLAINABLE]);

src/operations/find_one.ts

@@ -5,6 +5,7 @@ import type { FindOptions } from './find';
 import { MongoError } from '../error';
 import type { Server } from '../sdam/server';
 import { CommandOperation } from './command';
+import { Aspect, defineAspects } from './operation';
 
 /** @internal */
 export class FindOneOperation extends CommandOperation<FindOptions, Document> {
@@ -36,3 +37,5 @@ export class FindOneOperation extends CommandOperation<FindOptions, Document> {
     }
   }
 }
+
+defineAspects(FindOneOperation, [Aspect.EXPLAINABLE]);