A Python Object-Document-Mapper for working with MongoDB



Info: MongoEngine is an ORM-like layer on top of PyMongo.
Repository: https://github.com/MongoEngine/mongoengine
Author: Harry Marr (http://github.com/hmarr)
Maintainer: Stefan Wójcik (http://github.com/wojcikstefan)
https://travis-ci.org/MongoEngine/mongoengine.svg?branch=master https://coveralls.io/repos/github/MongoEngine/mongoengine/badge.svg?branch=master


MongoEngine is a Python Object-Document Mapper for working with MongoDB. Documentation is available at https://mongoengine-odm.readthedocs.io - there is currently a tutorial, a user guide, and an API reference.

Supported MongoDB Versions

MongoEngine is currently tested against MongoDB v3.4, v3.6 and v4.0. Future versions should be supported as well, but aren't actively tested at the moment. Make sure to open an issue or submit a pull request if you experience any problems with MongoDB version > 4.0.


We recommend the use of virtualenv and of pip. You can then use python -m pip install -U mongoengine. You may also have setuptools and thus you can use easy_install -U mongoengine. Another option is pipenv. You can then use pipenv install mongoengine to both create the virtual environment and install the package. Otherwise, you can download the source from GitHub and run python setup.py install.

The support for Python2 was dropped with MongoEngine 0.20.0


All of the dependencies can easily be installed via python -m pip. At the very least, you'll need these two packages to use MongoEngine:

  • pymongo>=3.4

If you utilize a DateTimeField, you might also use a more flexible date parser:

  • dateutil>=2.1.0

If you need to use an ImageField or ImageGridFsProxy:

  • Pillow>=2.0.0

If you need to use signals:

  • blinker>=1.3


Some simple examples of what MongoEngine code looks like:

from mongoengine import *

class BlogPost(Document):
    title = StringField(required=True, max_length=200)
    posted = DateTimeField(default=datetime.datetime.utcnow)
    tags = ListField(StringField(max_length=50))
    meta = {'allow_inheritance': True}

class TextPost(BlogPost):
    content = StringField(required=True)

class LinkPost(BlogPost):
    url = StringField(required=True)

# Create a text-based post
>>> post1 = TextPost(title='Using MongoEngine', content='See the tutorial')
>>> post1.tags = ['mongodb', 'mongoengine']
>>> post1.save()

# Create a link-based post
>>> post2 = LinkPost(title='MongoEngine Docs', url='hmarr.com/mongoengine')
>>> post2.tags = ['mongoengine', 'documentation']
>>> post2.save()

# Iterate over all posts using the BlogPost superclass
>>> for post in BlogPost.objects:
...     print('===', post.title, '===')
...     if isinstance(post, TextPost):
...         print(post.content)
...     elif isinstance(post, LinkPost):
...         print('Link:', post.url)

# Count all blog posts and its subtypes
>>> BlogPost.objects.count()
>>> TextPost.objects.count()
>>> LinkPost.objects.count()

# Count tagged posts
>>> BlogPost.objects(tags='mongoengine').count()
>>> BlogPost.objects(tags='mongodb').count()


To run the test suite, ensure you are running a local instance of MongoDB on the standard port and have pytest installed. Then, run python setup.py test or simply pytest.

To run the test suite on every supported Python and PyMongo version, you can use tox. You'll need to make sure you have each supported Python version installed in your environment and then:

# Install tox
$ python -m pip install tox
# Run the test suites
$ tox

If you wish to run a subset of tests, use the pytest convention:

# Run all the tests in a particular test file
$ pytest tests/fields/test_fields.py
# Run only particular test class in that file
$ pytest tests/fields/test_fields.py::TestField



We welcome contributions! See the Contribution guidelines

  • Pymongo3 compatibility

    Pymongo3 compatibility

    Hi guys,

    Now everything is fixed and is fully compatible for both PyMongo 2.X and 3.X

    I'm awaiting some feedback for:

    1. ~~The way I introduced differential behaviour based on PyMongo version~~
    2. ~~The behaviour for save() when a document is created with a given primary key, source of 5 of remaining issues. Here particularly, I have removed the check for self._created since we used to modify this why changing/switching db on the fly. This whole behaviour has changed in PyMongo3 and IMHO doesn't make sense anymore.~~
    3. ~~Your opinion if the test_hint failure could point to a bug in PyMongo3~~
    4. ~~A hand on the other error on test_geo_indexes_recursion~~
    5. ~~A problem with binary field used as primary index that was always there and only discovered now by a better test that became mandatory by the use of a work-around concerning a PyMongo 3.0 bug already fixed in the upcoming 3.0.1~~

    Cheers, Matthieu

    Review on Reviewable

    opened by MRigal 113
  • Tox support for cross-versions testing

    Tox support for cross-versions testing

    Mongoengine is tested on different PyMongo versions, different Python versions... This pull-request add a tox.ini file allowing to run the test suite on every supported version composition . This allow to do proper testing before submitting pull-requests without having to wait for TravisCI cross-versions testing.

    To run the test in tox, simply run:

    $ tox

    It will create a virtualenv for each combination and run the same test suite (like TravisCI).

    Review on Reviewable

    opened by noirbizarre 78
  • Fixes #934 - Added option to disable field existence check.

    Fixes #934 - Added option to disable field existence check.

    I threw together this patch as an idea to fix #934.

    I haven't dug too deep into Mongoengine to know what else this might affect, but I used _from_son in BaseDocument object as my injection point. The idea being that if one tries to define in code a field that does not exist, an error is still raised, but if one pulls in data from a PyMongo object, we don't raise an error.

    Review on Reviewable

    opened by gordol 64
  • mark_as_changed issue

    mark_as_changed issue

    fix mark_as_changed: rm lower level changed fields otherwise may cause conflict update error this issue appears when retrieve from db

    In [34]: class Foo(mongoengine.Document):
        bar = mongoengine.DictField()
    In [35]: Foo.objects.delete()
    Out[35]: 1
    In [36]: foo = Foo()
    In [37]: foo.save()
    Out[37]: <Foo: Foo object>
    In [38]: foo = Foo.objects.first()
    In [39]: foo.bar['what'] = 'ever'
    In [40]: foo.bar['other'] = {}
    In [41]: foo._changed_fields
    Out[41]: ['bar.what', 'bar.other']
    In [42]: foo.bar['other']['what'] = 'ever'
    In [43]: foo._changed_fields
    Out[43]: ['bar.what', 'bar.other', 'bar.other.what']
    In [44]: foo.save()
    OperationError                            Traceback (most recent call last)
    <ipython-input-44-e6645f54a3c0> in <module>()
    ----> 1 foo.save()
    .../mongoengine/document.pyc in save(self, force_insert, validate, clean, write_concern, cascade, cascade_kwargs, _refs, save_condition, **kwargs)
        365                 message = u'Tried to save duplicate unique keys (%s)'
        366                 raise NotUniqueError(message % unicode(err))
    --> 367             raise OperationError(message % unicode(err))
        368         id_field = self._meta['id_field']
        369         if created or id_field not in self._meta.get('shard_key', []):
    OperationError: Could not save document (Cannot update 'bar.other' and 'bar.other.what' at the same time)

    Review on Reviewable

    opened by Catstyle 53
  • _get_changed_fields fix for embedded documents with id field.

    _get_changed_fields fix for embedded documents with id field.

    When id field presented in Embedded document, changes inside this document was ignored in method _get_changed_fields because it's id was added to inspected array before processing it fields. Also modify unittests for _delta method, which fails without code modification.

    Review on Reviewable

    opened by elephanter 45
  • Delete returns None but expected a dict

    Delete returns None but expected a dict

    I'm trying to delete a document with self.delete() but it raises and error: File "/Users/garito/TimeFounder/App/0.3/env/lib/python2.7/site-packages/mongoengine/queryset/base.py", line 467, in delete return result["n"] TypeError: 'NoneType' object has no attribute 'getitem'

    I've checked the result with print result and it is None The deletion is made ok but the try to return result["n"] raises and error because result is None

    Did I missed something or did I find a bug?


    opened by Garito 28
  • Check if undefined fields are supplied on document

    Check if undefined fields are supplied on document

    If an undefined field is supplied to a document instance, a FieldDoesNotExist Exception will be raised. This way, you will be notified when you provide a field that does not exist.

    ATM when you do this:


    It will create a document instance for MyDoc. However, if undefined_field does not exist, the value test won't end up anywhere. You'll think the object is successfully created with the provided values, but actually it isn't.

    To remedy this situation, an exception will be raised. This way you'll be noticed about your mistake in development. If the document instance is created dynamically on bases of an API call data for example, then you can catch the exeption and notify the API user that they have provided an undefined field.

    opened by gitaarik 28
  • save doesn't work for datetime consistent with other fields.

    save doesn't work for datetime consistent with other fields.

    I am new to mongoengine, but this doesn't make any sense to me, that when I call my my_update() function, the user's updated_at field doesnt get updated but other fields do. here is my model:

    class User(db.Document):
        username = db.StringField(required=True, unique=True, max_length=20)
        created_at = db.DateTimeField(default=datetime.datetime.utcnow())
        updated_at = db.DateTimeField()
        friend_list = ListField(StringField(max_length=100))

    when I do a save, it saves the new friend_list correctly but it keeps the old updated_at field, and that one will never get updated again.

    def my_update(user_id):
        form = UserForm()
        user = User.objects.get_or_404(id=user_id)
        user.friend_list = insert_random_data()
        user.updated_at = datetime.datetime.utcnow()
        return users = User.objects.order_by('-updated_at', '-created_at')

    so if I run my_update a few times, it will update the friend_list each time, but the update_at field keeps staying the same !!! and I have no idea. I am really curious why is it behaving like this !

    opened by medyagh 27
  • Pep8 and more clean-up

    Pep8 and more clean-up

    Hi guys,

    Several times I ran into some cases where I came across these init() method returning a value, or some unused statements or variables, as well as many pep8 issues. It is never great to make a big change, but since we are now cleaning so many PRs and there will be anyway a big PR with #946 for next version, I thought it could be a good time to clean generally some code.

    I took some time to really read once (quickly) all the code line by line. It allowed me also to find some issues or strange behaviour and to add some TODOs.

    I would also like to take the opportunity to tackle one other point. We want to be PEP8 conform and this is very good. However one point is at least vague: line length. We have in our code some pieces which are strictly limited to 79 characters and some others to 119.

    PEP8 recommends 79 characters, however Django makes some exceptions there: https://docs.djangoproject.com/en/1.8/internals/contributing/writing-code/coding-style/

    Should we include the same point in our contribution guidelines? Some PRs have a lot of code doing only line breaks clean-up (which I tried to avoid in this cleaning effort to avoid unnecessary changes). And at the same time, I see a lot of places in the code where we have line breaks that do make the code significantly harder to read. @rozza @DavidBord @thedrow @seglberg @yograterol can I have your opinion on that point?

    Review on Reviewable

    opened by MRigal 27
  • fixed wrong _delta results on nested MapFields #931

    fixed wrong _delta results on nested MapFields #931

    Fix for #931 issue. When model restored from database and there is a nested MapField there is an error in wrong key for changes when trying to add/change item in lower-level MapField.

    Review on Reviewable

    opened by elephanter 24
  • Empty ListFields of EmbeddedDocuments with a unique field may only exist once (MongoEngine 0.9.0)

    Empty ListFields of EmbeddedDocuments with a unique field may only exist once (MongoEngine 0.9.0)

    Trying to save an empty list of embedded documents which have a unique field on another document causes the following error to be thrown:

    E11000 duplicate key error index: mydb.mycollection.mylist.myuniquefield_1 dup key: { : null }

    Interestingly, having a primary_key field in an EmbeddedDocument in an empty ListField doesn't cause an error.

    The workaround we found is to define the field on the EmbeddedDocument as unique and sparse. which is funny, since the sparse option is the reason I upgraded to mongoengine 0.9.0 in the first place...

    Discussion Documentation ListField 
    opened by eli-b 24
  • is it possible to search null objects ?

    is it possible to search null objects ?

    I'm trying to search null object with python NoneType but got the below error :

    raise ValidationError(message, errors=errors, field_name=field_name) mongoengine.errors.ValidationError: 'null' is not a valid ObjectId, it must be a 12-byte input or a 24-character hex string

    opened by prabhupad26 2
  • fix none() has no effect in update/aggregate / first

    fix none() has no effect in update/aggregate / first

    fix none() has no effect in update / aggregate / first and cause query on all collection.

    Not sure that this is the best solution for aggregation case But this the best I found

    opened by idoshr 0
  • Fields starting with underscore ignored on to_mongo or to_json call

    Fields starting with underscore ignored on to_mongo or to_json call

    Hello, community.

    I just realize that any field I define starting with an underscore will NOT be included in the serialization process.

    I did some testing and this comes from MongoEngine since if I use the Pymongo collection, I get every field.

    Is this a defined behavior? I could not find anything in the documentation about it. Please let me know if I should create an example code.

    opened by letoss 0
  • Support for TextSearch

    Support for TextSearch

    Hi guys! I have absolutely no idea if you even would consider this use case that at my Organization we were facing, but let me try anyway.

    We are currently using MongoEngine in our codebase, and we are using MongoAtlas to manager our cluster. Atlas Search was recently published, and we gave it a try, and as you all know, it is actually a lot faster than the normal search. Now, since we have some query that are quite expensive, we decided to migrate pretty much all the query to Atlas Search. Unfortunately this would mean two things:

    • Rewrite all the current query in our codebase (meaning pain and suffering that I would gladly skip)
    • Have an even different syntax without all the currently checks that MongoEngine has implemented.

    Now, to solve this use case, since we did not find any opensource solution that would solve it, we decide that doing the complicate things was actually more fun than doing the boring things: so we wrote a proxy, called AtlasQ, where its users can continue to use the MongoEngine syntax but they will be using the engine of Atlas Search. We have added come validity check in the inputs (you can call e method to ensure that the index exists and that all the fields are actually indexed, because my previous self debugged for too much time, and I do not want other people to share the same feelings); inputs and outputs of all the methods that mongoengine implemented (first(), filter(), aggregate(), count(), ...) have the same signatures.

    If this proxy could be useful, if there are actually other organizations that could benefit from that, we could easily merge it inside the mongoengine repository with a little bit of tuning here there!

    opened by 0ssigeno 0
  • v0.24.2(Jul 17, 2022)

  • v0.24.1(Mar 21, 2022)

    What's Changed

    • update dependency specifier to allow pymongo 4.x by @terencehonles in https://github.com/MongoEngine/mongoengine/pull/2630
    • elaborate_authentication_breaking_change_authsource by @bagerard in https://github.com/MongoEngine/mongoengine/pull/2634
    • Don't use deprecated property for emptiness check by @arthurio in https://github.com/MongoEngine/mongoengine/pull/2633
    • Prepare release 0 24 1 by @bagerard in https://github.com/MongoEngine/mongoengine/pull/2637

    New Contributors

    • @arthurio made their first contribution in https://github.com/MongoEngine/mongoengine/pull/2633
    Source code(tar.gz)
    Source code(zip)
  • v0.24.0(Feb 20, 2022)

  • v0.23.0(Mar 4, 2021)

  • v0.22.1(Dec 16, 2020)

  • v0.22.0(Dec 14, 2020)

  • v0.21.0(Nov 19, 2020)

  • v0.20.0(May 2, 2020)

  • v0.19.1(Jan 4, 2020)

  • v0.19.0(Dec 24, 2019)

  • v0.18.2(Jun 25, 2019)

  • v0.18.1(Jun 18, 2019)

  • v0.18.0(Jun 12, 2019)

  • v0.17.0(Mar 11, 2019)

  • v0.16.2(Nov 21, 2018)

  • v0.16.1(Nov 14, 2018)

  • v0.15.3(Jul 16, 2018)

  • v0.15.1(Apr 17, 2018)

  • v0.15.0(Apr 6, 2018)

  • v0.14.3(Oct 1, 2017)

  • v0.14.1(Oct 1, 2017)

    • Removed SemiStrictDict and started using a regular dict for BaseDocument._data #1630
    • Added support for the $position param in the $push operator #1566
    • Fixed DateTimeField interpreting an empty string as today #1533
    • Added a missing __ne__ method to the GridFSProxy class #1632
    • Fixed BaseQuerySet._fields_to_db_fields #1553
    Source code(tar.gz)
    Source code(zip)
  • v0.14.0(May 8, 2017)

    This release includes a few bug fixes and a significant code cleanup in an ongoing effort to make this codebase much healthier. Primary changes:

    • BREAKING CHANGE: Removed the coerce_types param from QuerySet.as_pymongo #1549
    • POTENTIAL BREAKING CHANGE: Made EmbeddedDocument not hashable by default #1528
    • Improved code quality #1531, #1540, #1541, #1547
    Source code(tar.gz)
    Source code(zip)
  • v0.13.0(Apr 16, 2017)

    This release adds UTF-8 support to the EmailField along with other validation tweaks (#1527).

    Previously, email addresses containing Unicode characters didn't work at all. Now, domains with Unicode characters are supported out of the box and similar validation on the user part can be explicitly enabled. Additionally, you can enable an optional validation of IP-based domain parts (e.g. "[email protected][]"), and you can have a whitelist of otherwise invalid domains (e.g. "[email protected]").

    Source code(tar.gz)
    Source code(zip)
  • v0.12.0(Apr 7, 2017)

    This is primarily a bugfix release, but it may also introduce breaking changes if you relied on a previously broken implementation. See https://mongoengine-odm.readthedocs.io/upgrade.html before upgrading.

    • POTENTIAL BREAKING CHANGE: Fixed limit/skip/hint/batch_size chaining #1476
    • POTENTIAL BREAKING CHANGE: Changed a public QuerySet.clone_into method to a private QuerySet._clone_into #1476
    • Fixed the way Document.objects.create works with duplicate IDs #1485
    • Fixed connecting to a replica set with PyMongo 2.x #1436
    • Fixed using sets in field choices #1481
    • Fixed deleting items from a ListField #1318
    • Fixed an obscure error message when filtering by field__in=non_iterable. #1237
    • Fixed behavior of a dec update operator #1450
    • Added a rename update operator #1454
    • Added validation for the db_field parameter #1448
    • Fixed the error message displayed when querying an EmbeddedDocumentField by an invalid value #1440
    • Fixed the error message displayed when validating unicode URLs #1486
    • Raise an error when trying to save an abstract document #1449
    Source code(tar.gz)
    Source code(zip)
  • v0.11.0(Dec 13, 2016)

    This release includes a major re-haul of MongoEngine's code quality and introduces a few breaking changes. It also touches many different parts of the package and although all the changes have been tested and scrutinized, you're encouraged to thoroughly test the upgrade.

    First breaking change involves renaming ConnectionError to MongoEngineConnectionError. If you import or catch this exception, you'll need to rename it in your code.

    Second breaking change drops Python v2.6 support. If you run MongoEngine on that Python version, you'll need to upgrade it first.

    Third breaking change drops an old backward compatibility measure where from mongoengine.base import ErrorClass would work on top of from mongoengine.errors import ErrorClass (where ErrorClass is e.g. ValidationError). If you import any exceptions from mongoengine.base, change it to mongoengine.errors.

    Lastly, we fixed absent rounding for DecimalField when force_string is set (#1103).

    Source code(tar.gz)
    Source code(zip)
  • v0.10.9(Dec 11, 2016)

  • v0.10.8(Dec 11, 2016)

    • Added support for QuerySet.batch_size #1426
    • Fixed query set iteration within iteration #1427
    • Fixed an issue where specifying a MongoDB URI host would override more information than it should #1421
    • Added ability to filter the generic reference field by ObjectId and DBRef #1425
    • Fixed delete cascade for models with a custom primary key field #1247
    • Added ability to specify an authentication mechanism (e.g. X.509) #1333
    • Added support for falsey primary keys (e.g. doc.pk = 0) #1354
    • Fixed QuerySet#sum/average for fields w/ explicit db_field #1417
    • Fixed filtering by embedded_doc=None #1422
    • Added support for cursor.comment #1420
    • Fixed doc.get__display #1419
    • Fixed repr method of the StrictDict #1424
    • Added a deprecation warning for Python 2.6
    Source code(tar.gz)
    Source code(zip)
A Pythonic, object-oriented interface for working with MongoDB.

PyMODM MongoDB has paused the development of PyMODM. If there are any users who want to take over and maintain this project, or if you just have quest

mongodb 341 Jun 22, 2022
MongoDB data stream pipeline tools by YouGov (adopted from MongoDB)

mongo-connector The mongo-connector project originated as a MongoDB mongo-labs project and is now community-maintained under the custody of YouGov, Pl

YouGov 1.9k Aug 5, 2022
PubMed Mapper: A Python library that map PubMed XML to Python object

pubmed-mapper: A Python Library that map PubMed XML to Python object 中文文档 1. Philosophy view UML Programmatically access PubMed article is a common ta

灵魂工具人 29 Aug 2, 2022
Pony Object Relational Mapper

Downloads Pony Object-Relational Mapper Pony is an advanced object-relational mapper. The most interesting feature of Pony is its ability to write que

null 3k Aug 11, 2022
Simplest SQL mapper in Python, probably

SQL MAPPER Basically what it does is: it executes some SQL thru a database connector you fed it, maps it to some model and gives to u. Also it can cre

null 1 Jan 6, 2022
PyMongo - the Python driver for MongoDB

PyMongo Info: See the mongo site for more information. See GitHub for the latest source. Documentation: Available at pymongo.readthedocs.io Author: Mi

mongodb 3.7k Aug 6, 2022
Motor - the async Python driver for MongoDB and Tornado or asyncio

Motor Info: Motor is a full-featured, non-blocking MongoDB driver for Python Tornado and asyncio applications. Documentation: Available at motor.readt

mongodb 2k Aug 9, 2022
Motor - the async Python driver for MongoDB and Tornado or asyncio

Motor Info: Motor is a full-featured, non-blocking MongoDB driver for Python Tornado and asyncio applications. Documentation: Available at motor.readt

mongodb 1.6k Feb 6, 2021
Monty, Mongo tinified. MongoDB implemented in Python !

Monty, Mongo tinified. MongoDB implemented in Python ! Inspired by TinyDB and it's extension TinyMongo. MontyDB is: A tiny version of MongoDB, against

David Lai 501 Aug 2, 2022
A simple password manager I typed with python using MongoDB .

Python with MongoDB A simple python code example using MongoDB. How do i run this code • First of all you need to have a python on your computer. If y

null 26 Jun 16, 2022
MongoX is an async python ODM for MongoDB which is built on top Motor and Pydantic.

MongoX MongoX is an async python ODM (Object Document Mapper) for MongoDB which is built on top Motor and Pydantic. The main features include: Fully t

Amin Alaee 101 Aug 6, 2022
Implementing basic MongoDB CRUD (Create, Read, Update, Delete) queries, using Python.

MongoDB with Python Implementing basic MongoDB CRUD (Create, Read, Update, Delete) queries, using Python. We can connect to a MongoDB database hosted

MousamSingh 4 Dec 1, 2021
sync/async MongoDB ODM, yes.

μMongo: sync/async ODM μMongo is a Python MongoDB ODM. It inception comes from two needs: the lack of async ODM and the difficulty to do document (un)

Scille 412 Aug 3, 2022
Micro ODM for MongoDB

Beanie - is an asynchronous ODM for MongoDB, based on Motor and Pydantic. It uses an abstraction over Pydantic models and Motor collections to work wi

Roman 787 Aug 10, 2022
A simple wrapper to make a flat file drop in raplacement for mongodb out of TinyDB

Purpose A simple wrapper to make a drop in replacement for mongodb out of tinydb. This module is an attempt to add an interface familiar to those curr

null 174 Jul 27, 2022
Query multiple mongoDB database collections easily

leakscoop Perform queries across multiple MongoDB databases and collections, where the field names and the field content structure in each database ma

bagel 5 Jun 24, 2021
A CRUD and REST api with mongodb atlas.

Movies_api A CRUD and REST api with mongodb atlas. Setup First import all the python dependencies in your virtual environment or globally by the follo

Pratyush Kongalla 1 Jan 27, 2022
Import entity definition document into SQLie3. Manage the entity. Also, create a "Create Table SQL file".

EntityDocumentMaker Version 1.00 After importing the entity definition (Excel file), store the data in sqlite3. エンティティ定義(Excelファイル)をインポートした後、データをsqlit

G-jon FujiYama 1 Jan 9, 2022
Py2neo is a comprehensive toolkit for working with Neo4j from within Python applications or from the command line.

Py2neo Py2neo is a client library and toolkit for working with Neo4j from within Python applications and from the command line. The library supports b

Nigel Small 1.1k Aug 7, 2022