Skip to main content

Explainable CRUD API for PyMongo

Project description

Info:Explain collections in PyMongo. See GitHub for the latest source.
Author: Julius Park


This package provides an ExplainCollection class that allows PyMongo’s Collection methods to be explained


To install this package simply use pip:

pip install pymongoexplain

Support / Feedback

For questions, discussions, or general technical support, visit the MongoDB Community Forums. The MongoDB Community Forums are a centralized place to connect with other MongoDB users, ask questions, and get answers.

Bugs / Feature Requests

Think you’ve found a bug? Want to see a new feature in PyMongoExplain? Please open an issue on this GitHub repository.

How To Ask For Help

Please include all of the following information when opening an issue:

  • Detailed steps to reproduce the problem, including full traceback, if possible.

  • The exact python version used, with patch level:

    $ python -c "import sys; print(sys.version)"
  • The exact version of PyMongo used (if applicable), with patch level:

    $ python -c "import pymongo; print(pymongo.version); print(pymongo.has_c())"
  • The exact version of PyMongoExplain used:

    $ python -c "import pymongoexplain; print(pymongoexplain.version)"


PyMongoExplain requires CPython 3.5+, and PyPy3.5+.

PyMongoExplain requires PyMongo>=3.10,<4


The easiest way to run the tests is to run python test in the root of the distribution.


PyMongo operations in existing application code can be explained by swapping Collection objects with ExplainCollection objects. The ExplainCollection class provides all CRUD API methods provided by PyMongo’s Collection, but using this class to run operations runs explain on them, instead of executing them.

To run explain on a command, first instantiate an ExplainCollection from the Collection object originally used to run the command:

collection = client.db.products
explain = ExplainCollection(collection)

Now you are ready to explain some commands. Remember that explaining a command does not execute it:

result = explain.update_one({"quantity": 1057, "category": "apparel"}, {"$set": {"reorder": True}})

Now result will contain the output of running explain on the given update_one command:

{'ok': 1.0,
 'operationTime': Timestamp(1595603051, 3),
 'queryPlanner': {'indexFilterSet': False,
                  'namespace': 'db.products',
                  'parsedQuery': {'$and': [{'category': {'$eq': 'apparel'}},
                                           {'quantity': {'$eq': 1057}}]},
                  'planCacheKey': 'CD8F6D8F',
                  'plannerVersion': 1,
                  'queryHash': 'CD8F6D8F',
                  'rejectedPlans': [],
                  'winningPlan': {'inputStage': {'direction': 'forward',
                                                 'filter': {'$and': [{'category': {'$eq': 'apparel'}},
                                                                     {'quantity': {'$eq': 1057}}]},
                                                 'stage': 'COLLSCAN'},
                                  'stage': 'UPDATE'}},
 'serverInfo': {'gitVersion': '27f5c1ee9f513f29fe30b8ebefed99581428c6e1',
                'host': '',
                'port': 27017,
                'version': '4.4.0-rc13'}}

Since ExplainCollection instances provide all the same methods provided by Collection instances, explaining operations in your application code is a simple matter of replacing Collection instances in your application code with ExplainCollection instances.

Explaining commands in a script

You can also run explain on all commands within a Python script using our CLI tool. Given a script that contains pymongo commands within it, you can simply run:

python3 -m pymongoexplain <path/to/your/>

This will log the explain output for every single command within the specified script, in addition to running every command in the script itself. Do note that because the explain output is generated using the logging module, if your script configures logging module there are certain things to keep in mind:

  • if your script sets the logging level
    higher than INFO, the explain output will be suppressed entirely.
  • the explain output will be sent to whatever stream your script configures the logging module to send output to.

Any positional parameters or arguments required by your script can be simply be appended to the invocation as follows:

python3 -m pymongoexplain <path/to/your/> [PARAMS] [--optname OPTS]

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pymongoexplain, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size pymongoexplain-1.0.0-py3-none-any.whl (15.0 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size pymongoexplain-1.0.0.tar.gz (11.9 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page