About

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

PyMongoExplain greatly simplifies the amount of effort needed to explain commands. For example, suppose we wanted to explain the following update_one:

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

Before PyMongoExplain, one would need to convert the update_one into the equivalent MongoDB command:

collection.database.command(SON([('explain', SON([('update', 'products'), ('updates', [{'q': {'quantity': 1057, 'category': 'apparel'}, 'upsert': False, 'multi': False, 'u': {'$set': {'reorder': True}}}])])), ('verbosity', 'queryPlanner')]))

After PyMongoExplain:

ExplainableCollection(collection).update_one({"quantity": 1057, "category": "apparel"},{"$set": {"reorder": True}})

Installation

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.

Dependencies

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

PyMongoExplain requires PyMongo>=3.10,<4

Testing

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

Tutorial

PyMongo operations in existing application code can be explained by swapping Collection objects with ExplainableCollection objects. The ExplainableCollection 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 ExplainableCollection from the Collection object originally used to run the command:

from pymongoexplain import ExplainableCollection

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

If you wish to configure the options for the explain command itself, pass them to the ExplainableCollection constructor like so:

explain = ExplainableCollection(collection, verbosity="queryPlanner",
                                comment="I'm a comment")

For more information see the documentation for the explain command.

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': 'Juliuss-MBP.verizon.net',
                'port': 27017,
                'version': '4.4.0-rc13'}}

Since ExplainableCollection 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 ExplainableCollection instances.

python3 -m pymongoexplain <path/to/your/script.py>

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

ExplainableCollection(collection).find({}).sort(...)

ExplainableCollection(collection).find({}, sort=...)