Uploaded image for project: 'Python Driver'
  1. Python Driver
  2. PYTHON-1656

Document that explain() uses the explain command default verbosity

    • Type: Icon: Improvement Improvement
    • Resolution: Fixed
    • Priority: Icon: Minor - P4 Minor - P4
    • 3.8
    • Affects Version/s: None
    • Component/s: Docs
    • None

      When PyMongo switched to the explain command for Cursor.explain() with MongoDB 3.2 it used the explain command's default verbosity mode, allPlansExecution. This is surprising to some users since the mongo shell was implemented to override the default and use the queryPlanner mode. PyMongo's documentation for Cursor.explain() should note this behavior. We won't make the verbosity configurable since we still have to support much older versions of MongoDB. Users who require configurable verbosity should use the explain command directly through Database.command, which can be used to explain a wide variety of server commands.

      Original description follows
      -----------------------------------

      Mongo's default mode in explain() is 'queryPlanner'[1]. It returns a bson with the winningPlan and rejectedPlans but does not execute either.

      pymongo's explain() by default does "allPlansExecution". This is not documented [2]

      pymongo's explain() has no parameters, so there is not way to execute explain with 'queryPlanner' or 'executionStats'.

      I've tested this with pymongo 3.7.2 (both python2 and python3) inside docker python:2 and python:3 image (from docker hub) on linux.

       

      I propose as a solution:

      • Document the current pymongo behavior.
      • Add an optional parameter in explain() so I can do explain({'version': 'queryPlanner'})

       

      BTW: I created this issue because I need to do queryPlanner via pymongo. So my solution may be biased.

       

      [1] "Default mode is "queryPlanner"." https://docs.mongodb.com/manual/reference/method/cursor.explain/

      [2] https://api.mongodb.com/python/current/api/pymongo/cursor.html?highlight=explain#pymongo.cursor.Cursor.explain

       

            Assignee:
            bernie@mongodb.com Bernie Hackett
            Reporter:
            CrimsonGlory Crimson Glory
            Votes:
            0 Vote for this issue
            Watchers:
            3 Start watching this issue

              Created:
              Updated:
              Resolved: