add explain functionality to ops

Author: HanaPearlman

lib/aggregation_cursor.js

@@ -322,7 +322,13 @@ AggregationCursor.prototype.get = AggregationCursor.prototype.toArray;
 
 /**
  * Execute the explain for the cursor
+ *
+ * For backwards compatibility, a verbosity of true is interpreted as "allPlansExecution"
+ * and false as "queryPlanner". Prior to server version 3.6, aggregate()
+ * ignores the verbosity parameter and executes in "queryPlanner".
+ *
  * @method AggregationCursor.prototype.explain
+ * @param {string|boolean=true} verbosity - An optional mode in which to run the explain.
  * @param {AggregationCursor~resultCallback} [callback] The result callback.
  * @return {Promise} returns Promise if no callback passed
  */

lib/collection.js

@@ -287,7 +287,7 @@ const DEPRECATED_FIND_OPTIONS = ['maxScan', 'fields', 'snapshot', 'oplogReplay']
  * @param {object} [options.fields] **Deprecated** Use `options.projection` instead
  * @param {number} [options.skip=0] Set to skip N documents ahead in your query (useful for pagination).
  * @param {Object} [options.hint] Tell the query to use specific indexes in the query. Object of indexes to use, {'_id':1}
- * @param {boolean} [options.explain=false] Explain the query instead of returning the data.
+ * @param {string|boolean} [options.explain] The verbosity mode for the explain output.
  * @param {boolean} [options.snapshot=false] DEPRECATED: Snapshot query.
  * @param {boolean} [options.timeout=false] Specify if the cursor can timeout.
  * @param {boolean} [options.tailable=false] Specify if the cursor is tailable.
@@ -1044,7 +1044,7 @@ Collection.prototype.save = deprecate(function(doc, options, callback) {
  * @param {object} [options.fields] **Deprecated** Use `options.projection` instead
  * @param {number} [options.skip=0] Set to skip N documents ahead in your query (useful for pagination).
  * @param {Object} [options.hint] Tell the query to use specific indexes in the query. Object of indexes to use, {'_id':1}
- * @param {boolean} [options.explain=false] Explain the query instead of returning the data.
+ * @param {string|boolean} [options.explain] The verbosity mode for the explain output.
  * @param {boolean} [options.snapshot=false] DEPRECATED: Snapshot query.
  * @param {boolean} [options.timeout=false] Specify if the cursor can timeout.
  * @param {boolean} [options.tailable=false] Specify if the cursor is tailable.
@@ -1831,7 +1831,7 @@ Collection.prototype.findAndRemove = deprecate(function(query, sort, options, ca
  * @param {number} [options.batchSize=1000] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @param {object} [options.cursor] Return the query as cursor, on 2.6 > it returns as a real cursor on pre 2.6 it returns as an emulated cursor.
  * @param {number} [options.cursor.batchSize=1000] Deprecated. Use `options.batchSize`
- * @param {boolean} [options.explain=false] Explain returns the aggregation execution plan (requires mongodb 2.6 >).
+ * @param {string|boolean} [options.explain] The verbosity mode for the explain output.
  * @param {boolean} [options.allowDiskUse=false] allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 >).
  * @param {number} [options.maxTimeMS] maxTimeMS specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point.
  * @param {number} [options.maxAwaitTimeMS] The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query.

lib/core/wireprotocol/query.js

@@ -8,6 +8,8 @@ const isSharded = require('./shared').isSharded;
 const maxWireVersion = require('../utils').maxWireVersion;
 const applyCommonQueryOptions = require('./shared').applyCommonQueryOptions;
 const command = require('./command');
+const decorateWithExplain = require('../../utils').decorateWithExplain;
+const Explain = require('../../explain');
 
 function query(server, ns, cmd, cursorState, options, callback) {
   options = options || {};
@@ -31,7 +33,14 @@ function query(server, ns, cmd, cursorState, options, callback) {
   }
 
   const readPreference = getReadPreference(cmd, options);
-  const findCmd = prepareFindCommand(server, ns, cmd, cursorState, options);
+  let findCmd = prepareFindCommand(server, ns, cmd, cursorState, options);
+
+  // 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
@@ -59,7 +68,7 @@ function query(server, ns, cmd, cursorState, options, callback) {
 
 function prepareFindCommand(server, ns, cmd, cursorState) {
   cursorState.batchSize = cmd.batchSize || cursorState.batchSize;
-  let findCmd = {
+  const findCmd = {
     find: collectionNamespace(ns)
   };
 
@@ -143,14 +152,6 @@ function prepareFindCommand(server, ns, cmd, cursorState) {
   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;
 }
 
@@ -188,7 +189,7 @@ function prepareLegacyFindQuery(server, ns, cmd, cursorState, options) {
   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);

lib/core/wireprotocol/write_command.js

@@ -3,6 +3,8 @@
 const MongoError = require('../error').MongoError;
 const collectionNamespace = require('./shared').collectionNamespace;
 const command = require('./command');
+const decorateWithExplain = require('../../utils').decorateWithExplain;
+const Explain = require('../../explain');
 
 function writeCommand(server, type, opsField, ns, ops, options, callback) {
   if (ops.length === 0) throw new MongoError(`${type} must contain at least one document`);
@@ -15,7 +17,7 @@ function writeCommand(server, type, opsField, ns, ops, options, callback) {
   const ordered = typeof options.ordered === 'boolean' ? options.ordered : true;
   const writeConcern = options.writeConcern;
 
-  const writeCommand = {};
+  let writeCommand = {};
   writeCommand[type] = collectionNamespace(ns);
   writeCommand[opsField] = ops;
   writeCommand.ordered = ordered;
@@ -36,6 +38,13 @@ function writeCommand(server, type, opsField, ns, ops, options, callback) {
     writeCommand.bypassDocumentValidation = options.bypassDocumentValidation;
   }
 
+  // If a command is to be explained, we need to reformat the command after
+  // the other command properties are specified.
+  const explain = Explain.fromOptions(options);
+  if (explain) {
+    writeCommand = decorateWithExplain(writeCommand, explain);
+  }
+
   const commandOptions = Object.assign(
     {
       checkKeys: type === 'insert',

lib/cursor.js

@@ -12,6 +12,8 @@ const Map = require('./core').BSON.Map;
 const maybePromise = require('./utils').maybePromise;
 const executeOperation = require('./operations/execute_operation');
 const formattedOrderClause = require('./utils').formattedOrderClause;
+const Explain = require('./explain');
+const Aspect = require('./operations/operation').Aspect;
 
 const each = require('./operations/cursor_ops').each;
 const CountOperation = require('./operations/count');
@@ -999,25 +1001,25 @@ class Cursor extends CoreCursor {
 
   /**
    * Execute the explain for the cursor
+   *
+   * For backwards compatibility, a verbosity of true is interpreted as "allPlansExecution"
+   * and false as "queryPlanner". Prior to server version 3.6, aggregate()
+   * ignores the verbosity parameter and executes in "queryPlanner".
+   *
    * @method
+   * @param {string|boolean=true} verbosity - An optional mode in which to run the explain.
    * @param {Cursor~resultCallback} [callback] The result callback.
    * @return {Promise} returns Promise if no callback passed
    */
-  explain(callback) {
-    // NOTE: the next line includes a special case for operations which do not
-    //       subclass `CommandOperationV2`. To be removed asap.
-    if (this.operation && this.operation.cmd == null) {
-      this.operation.options.explain = true;
-      this.operation.fullResponse = false;
-      return executeOperation(this.topology, this.operation, callback);
-    }
-
-    this.cmd.explain = true;
+  explain(verbosity, callback) {
+    if (typeof verbosity === 'function') (callback = verbosity), (verbosity = true);
+    if (verbosity === undefined) verbosity = true;
 
-    // Do we have a readConcern
-    if (this.cmd.readConcern) {
-      delete this.cmd['readConcern'];
+    if (!this.operation || !this.operation.hasAspect(Aspect.EXPLAINABLE)) {
+      throw new MongoError('This command cannot be explained');
     }
+    this.operation.explain = new Explain(verbosity);
+
     return maybePromise(this, callback, cb => {
       CoreCursor.prototype._next.apply(this, [cb]);
     });

lib/db.js

@@ -312,7 +312,7 @@ Db.prototype.command = function(command, options, callback) {
  * @param {number} [options.batchSize=1000] The number of documents to return per batch. See {@link https://docs.mongodb.com/manual/reference/command/aggregate|aggregation documentation}.
  * @param {object} [options.cursor] Return the query as cursor, on 2.6 > it returns as a real cursor on pre 2.6 it returns as an emulated cursor.
  * @param {number} [options.cursor.batchSize=1000] Deprecated. Use `options.batchSize`
- * @param {boolean} [options.explain=false] Explain returns the aggregation execution plan (requires mongodb 2.6 >).
+ * @param {string|boolean} [options.explain] The verbosity mode for the explain output.
  * @param {boolean} [options.allowDiskUse=false] allowDiskUse lets the server know if it can use disk to store temporary results for the aggregation (requires mongodb 2.6 >).
  * @param {number} [options.maxTimeMS] maxTimeMS specifies a cumulative time limit in milliseconds for processing operations on the cursor. MongoDB interrupts the operation at the earliest following interrupt point.
  * @param {number} [options.maxAwaitTimeMS] The maximum amount of time for the server to wait on new documents to satisfy a tailable cursor query.

lib/explain.js

@@ -0,0 +1,40 @@
+'use strict';
+
+/**
+ * @class
+ * @property {string} verbosity The verbosity mode for the explain output
+ */
+class Explain {
+  /**
+   * Constructs an Explain from the explain verbosity.
+   *
+   * 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".
+   *
+   * @param {string|boolean} [verbosity] The verbosity mode for the explain output ({'queryPlanner'|'queryPlannerExtended'|'executionStats'|'allPlansExecution'|boolean})
+   */
+  constructor(verbosity) {
+    if (typeof verbosity === 'boolean') {
+      this.verbosity = verbosity ? 'allPlansExecution' : 'queryPlanner';
+    } else {
+      this.verbosity = verbosity;
+    }
+  }
+
+  /**
+   * Construct an Explain given an options object.
+   *
+   * @param {object} options The options object from which to extract the explain.
+   * @return {Explain}
+   */
+  static fromOptions(options) {
+    if (options == null || options.explain === undefined) {
+      return;
+    }
+
+    return new Explain(options.explain);
+  }
+}
+
+module.exports = Explain;

lib/operations/aggregate.js

@@ -37,10 +37,8 @@ class AggregateOperation extends CommandOperationV2 {
       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 (this.explain && this.writeConcern) {
+      throw new MongoError('"explain" cannot be used on an aggregate call with writeConcern');
     }
 
     if (options.cursor != null && typeof options.cursor !== 'object') {
@@ -83,9 +81,8 @@ class AggregateOperation extends CommandOperationV2 {
       command.hint = options.hint;
     }
 
-    if (options.explain) {
+    if (this.explain) {
       options.full = false;
-      command.explain = options.explain;
     }
 
     command.cursor = options.cursor || {};
@@ -100,7 +97,8 @@ class AggregateOperation extends CommandOperationV2 {
 defineAspects(AggregateOperation, [
   Aspect.READ_OPERATION,
   Aspect.RETRYABLE,
-  Aspect.EXECUTE_WITH_SELECTION
+  Aspect.EXECUTE_WITH_SELECTION,
+  Aspect.EXPLAINABLE
 ]);
 
 module.exports = AggregateOperation;

lib/operations/command_v2.js

@@ -6,6 +6,7 @@ const ReadPreference = require('../core').ReadPreference;
 const ReadConcern = require('../read_concern');
 const WriteConcern = require('../write_concern');
 const maxWireVersion = require('../core/utils').maxWireVersion;
+const decorateWithExplain = require('../utils').decorateWithExplain;
 const commandSupportsReadConcern = require('../core/sessions').commandSupportsReadConcern;
 const MongoError = require('../core/error').MongoError;
 
@@ -22,7 +23,6 @@ class CommandOperationV2 extends OperationBase {
       : ReadPreference.resolve(propertyProvider, this.options);
     this.readConcern = resolveReadConcern(propertyProvider, this.options);
     this.writeConcern = resolveWriteConcern(propertyProvider, this.options);
-    this.explain = false;
 
     if (operationOptions && typeof operationOptions.fullResponse === 'boolean') {
       this.fullResponse = true;
@@ -79,6 +79,15 @@ class CommandOperationV2 extends OperationBase {
       cmd.comment = options.comment;
     }
 
+    if (this.hasAspect(Aspect.EXPLAINABLE) && 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);
+      }
+    }
+
     if (this.logger && this.logger.isDebug()) {
       this.logger.debug(`executing command ${JSON.stringify(cmd)} against ${this.ns}`);
     }

lib/operations/common_functions.js

@@ -11,6 +11,7 @@ const MongoError = require('../core').MongoError;
 const ReadPreference = require('../core').ReadPreference;
 const toError = require('../utils').toError;
 const CursorState = require('../core/cursor').CursorState;
+const maxWireVersion = require('../core/utils').maxWireVersion;
 
 /**
  * Build the count command.
@@ -57,14 +58,6 @@ function buildCountCommand(collectionOrCursor, query, options) {
   return cmd;
 }
 
-function deleteCallback(err, r, callback) {
-  if (callback == null) return;
-  if (err && callback) return callback(err);
-  if (r == null) return callback(null, { result: { ok: 1 } });
-  r.deletedCount = r.result.n;
-  if (callback) callback(null, r);
-}
-
 /**
  * Find and update a document.
  *
@@ -308,6 +301,12 @@ function removeDocuments(coll, selector, options, callback) {
     return callback(err, null);
   }
 
+  if (options.explain !== undefined && maxWireVersion(coll.s.topology) < 3) {
+    return callback
+      ? callback(new MongoError(`server does not support explain on remove`))
+      : undefined;
+  }
+
   // Execute the remove
   coll.s.topology.remove(coll.s.namespace, [op], finalOptions, (err, result) => {
     if (callback == null) return;
@@ -369,6 +368,12 @@ function updateDocuments(coll, selector, document, options, callback) {
     return callback(err, null);
   }
 
+  if (options.explain !== undefined && maxWireVersion(coll.s.topology) < 3) {
+    return callback
+      ? callback(new MongoError(`server does not support explain on update`))
+      : undefined;
+  }
+
   // Update options
   coll.s.topology.update(coll.s.namespace, [op], finalOptions, (err, result) => {
     if (callback == null) return;
@@ -382,31 +387,13 @@ function updateDocuments(coll, selector, document, options, callback) {
   });
 }
 
-function updateCallback(err, r, callback) {
-  if (callback == null) return;
-  if (err) return callback(err);
-  if (r == null) return callback(null, { result: { ok: 1 } });
-  r.modifiedCount = r.result.nModified != null ? r.result.nModified : r.result.n;
-  r.upsertedId =
-    Array.isArray(r.result.upserted) && r.result.upserted.length > 0
-      ? r.result.upserted[0] // FIXME(major): should be `r.result.upserted[0]._id`
-      : null;
-  r.upsertedCount =
-    Array.isArray(r.result.upserted) && r.result.upserted.length ? r.result.upserted.length : 0;
-  r.matchedCount =
-    Array.isArray(r.result.upserted) && r.result.upserted.length > 0 ? 0 : r.result.n;
-  callback(null, r);
-}
-
 module.exports = {
   buildCountCommand,
-  deleteCallback,
   findAndModify,
   indexInformation,
   nextObject,
   prepareDocs,
   insertDocuments,
   removeDocuments,
-  updateDocuments,
-  updateCallback
+  updateDocuments
 };