DOCSP-13820 explain method (#92)

kyuan-mongodb · web-flow · commit b836511bf424 · 2021-06-14T17:32:22.000-04:00
* added explain method
diff --git a/source/fundamentals/aggregation.txt b/source/fundamentals/aggregation.txt
@@ -150,6 +150,49 @@ The above aggregation should produce the following results:
    {"_id": 4, "count": 2}
    {"_id": 5, "count": 1}
 
+Explain Aggregation Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To view information about how MongoDB executes your operation, use the
+``explain()`` method of the ``AggregateIterable`` class. The ``explain()``
+method returns **execution plans** and performance statistics. An execution
+plan is a potential way MongoDB can complete an operation. 
+The ``explain()`` method provides both the winning plan (the plan MongoDB
+executed) and rejected plans. 
+
+.. include:: /includes/fundamentals/explain-verbosity.rst
+
+In the following example, we print the JSON representation of the
+winning plan for aggregation stages that produce execution plans: 
+
+.. literalinclude:: /includes/fundamentals/code-snippets/AggTour.java
+   :language: java
+   :dedent:
+   :start-after: begin aggregation three
+   :end-before: end aggregation three
+
+The above code snippet should produce the following output:
+
+.. code-block:: none
+   :copyable: false
+
+   { "stage": "PROJECTION_SIMPLE", 
+     "transformBy": {"stars": 1, "_id": 0},
+     "inputStage": {
+      "stage": "COLLSCAN", 
+      "filter": {
+         "categories": {"$eq":"bakery"}}, 
+     "direction": "forward"}} 
+
+For more information about the topics mentioned in this section, see the
+following resources:
+
+- :manual:`Explain Output </reference/explain-results/>` Server Manual Entry
+- :manual:`Query Plans </core/query-plans/>` Server Manual Entry
+- :java-core-api:`ExplainVerbosity <com/mongodb/ExplainVerbosity>` API Documentation
+- :java-docs:`explain() <apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#explain()>` API Documentation
+- :java-docs:`AggregateIterable <apidocs/mongodb-driver-sync/com/mongodb/client/AggregateIterable.html>` API Documentation
+
 Aggregation Expression Example
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
diff --git a/source/fundamentals/crud/read-operations/cursor.txt b/source/fundamentals/crud/read-operations/cursor.txt
@@ -4,6 +4,12 @@ Access Data From a Cursor
 
 .. default-domain:: mongodb
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 Read operations that return multiple documents do not immediately return
 all values matching the query. Because a query can potentially match
 large number of documents, we need to be able to access or store the
@@ -25,7 +31,7 @@ instance of a ``FindIterable``.
 
 A ``FindIterable`` consists of documents matched by your search criteria
 and allows you to further specify which documents to see by setting
-paramaters though methods. 
+parameters though methods. 
 
 Terminal Methods
 ----------------
@@ -37,8 +43,8 @@ operation.
 First
 ~~~~~
 
-Use the :java-docs:`first() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#first()>`
-method to retireve the first document in your query results:
+Use the ``first()`` method to retrieve the first document in your query
+results: 
 
 .. literalinclude:: /includes/fundamentals/code-snippets/Cursor.java
    :language: java
@@ -52,8 +58,7 @@ document, such as when filtering by a unique index.
 Into
 ~~~~
 
-Use the :java-docs:`into() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#into(A)>`
-method to store your query results in a ``List``: 
+Use the ``into()`` method to store your query results in a ``List``: 
 
 .. literalinclude:: /includes/fundamentals/code-snippets/Cursor.java
    :language: java
@@ -67,9 +72,8 @@ of documents that can fit into available memory.
 Cursor
 ~~~~~~
 
-Use the :java-docs:`cursor() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#cursor()>`
-method to iterate through fetched documents and ensure that the cursor
-closes if there is an early termination:
+Use the ``cursor()`` method to iterate through fetched documents and
+ensure that the cursor closes if there is an early termination:
 
 .. code-block:: java
    :copyable: true
@@ -78,6 +82,51 @@ closes if there is an early termination:
 
 For more information on how to ensure a cursor closes, see the :ref:`cursor cleanup section <cursor_cleanup>`.
 
+Explain
+~~~~~~~
+
+Use the ``explain()`` method to view information about how MongoDB
+executes your operation. 
+
+The ``explain()`` method returns **execution plans** and performance
+statistics. An execution plan is a potential way MongoDB
+can complete an operation. The ``explain()`` method provides both the
+winning plan (the plan MongoDB executed) and rejected plans. 
+
+.. include:: /includes/fundamentals/explain-verbosity.rst
+
+The following example prints the JSON representation of the
+winning plan for aggregation stages that produce execution plans: 
+
+.. literalinclude:: /includes/fundamentals/code-snippets/Cursor.java
+   :language: java
+   :dedent:
+   :start-after: begin explainExample
+   :end-before: end explainExample
+
+The above code snippet should produce the following output:
+
+.. code-block:: none
+   :copyable: false
+
+   { "stage": "COLLSCAN", "direction": "forward" }
+
+For more information on the explain operation, see the following
+Server Manual Entries: 
+
+- :manual:`Explain Output </reference/explain-results/>` 
+- :manual:`Query Plans </core/query-plans/>`
+
+For more information about the methods and classes mentioned in this
+section, see the following API documentation:
+
+- :java-docs:`first() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#first()>`
+- :java-docs:`into() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#into(A)>`
+- :java-docs:`cursor() <apidocs/mongodb-driver-sync/com/mongodb/client/MongoIterable.html#cursor()>`
+- :java-docs:`explain() <apidocs/mongodb-driver-sync/com/mongodb/client/FindIterable.html#explain()>`
+- :java-core-api:`ExplainVerbosity <com/mongodb/ExplainVerbosity>`
+
+
 Usage Patterns
 --------------
 
diff --git a/source/includes/fundamentals/code-snippets/AggTour.java b/source/includes/fundamentals/code-snippets/AggTour.java
@@ -6,6 +6,7 @@
 import com.mongodb.client.MongoClients;
 import com.mongodb.client.MongoCollection;
 import com.mongodb.client.MongoDatabase;
+import com.mongodb.ExplainVerbosity;
 import com.mongodb.client.model.Accumulators;
 import com.mongodb.client.model.Aggregates;
 import com.mongodb.client.model.Filters;
@@ -22,7 +23,7 @@ public class AggTour {
     public static void main(String[] args) {
         // Replace the uri string with your MongoDB deployment's connection string
         final String uri = "mongodb+srv://<user>:<password>@<cluster-url>?retryWrites=true&w=majority";
-
+        
         MongoClient mongoClient = MongoClients.create(uri);
         MongoDatabase database = mongoClient.getDatabase("aggregation");
         MongoCollection<Document> collection = database.getCollection("restaurants");
@@ -52,6 +53,24 @@ public static void main(String[] args) {
             )
         ).forEach(doc -> System.out.println(doc.toJson()));
         // end aggregation one
+        // begin aggregation three
+        Document explanation = collection.aggregate(
+            Arrays.asList(
+                    Aggregates.match(Filters.eq("categories", "bakery")),
+                    Aggregates.group("$stars", Accumulators.sum("count", 1))
+            )
+        ).explain(ExplainVerbosity.EXECUTION_STATS);
+
+        List<Document> stages = explanation.get("stages", List.class);
+        List<String> keys = Arrays.asList("queryPlanner", "winningPlan");
+
+        for (Document stage : stages) {
+            Document cursorStage = stage.get("$cursor", Document.class);
+            if (cursorStage != null) {
+                System.out.println(cursorStage.getEmbedded(keys, Document.class).toJson());
+            }
+        }
+        // end aggregation three
         // begin aggregation two
         collection.aggregate(
             Arrays.asList(
diff --git a/source/includes/fundamentals/code-snippets/Cursor.java b/source/includes/fundamentals/code-snippets/Cursor.java
@@ -4,6 +4,7 @@
 import com.mongodb.client.MongoClients;
 import com.mongodb.client.MongoCollection;
 import com.mongodb.client.MongoDatabase;
+import com.mongodb.ExplainVerbosity;
 import com.mongodb.client.*;
 
 import org.bson.conversions.Bson;
@@ -38,6 +39,9 @@ public static void main(String [] args){
         System.out.println("First Example");
         c.firstExample();
 
+        System.out.println("Explain Example");
+        c.explainExample();
+
         System.out.println("Into Example");
         c.intoExample();
 
@@ -65,6 +69,14 @@ private void firstExample(){
         // end firstExample
     }
 
+    private void explainExample(){
+        // begin explainExample
+        Document explanation = collection.find().explain(ExplainVerbosity.EXECUTION_STATS);
+        List<String> keys = Arrays.asList("queryPlanner", "winningPlan");
+        System.out.println(explanation.getEmbedded(keys, Document.class).toJson());
+        // end explainExample
+    }
+
     private void intoExample(){
         // begin intoExample
         List<Document> results = new ArrayList<>();
diff --git a/source/includes/fundamentals/explain-verbosity.rst b/source/includes/fundamentals/explain-verbosity.rst
@@ -0,0 +1,24 @@
+You can specify the level of detail of your explanation by passing a
+verbosity level to the ``explain()`` method.  
+
+The following table shows all verbosity levels for explanations and
+their intended use cases: 
+
+.. list-table::
+   :header-rows: 1
+   :stub-columns: 1
+   :widths: 40 60
+
+   * - Verbosity Level
+     - Use Case
+
+   * - ALL_PLANS_EXECUTIONS
+     - You want to know which plan MongoDB will choose to run your query.
+
+   * - EXECUTION_STATS
+     - You want to know if your query is performing well.
+
+   * - QUERY_PLANNER
+     - You have a problem with your query and you want as much information
+       as possible to diagnose the issue.
+     
